Data Schema Preferences — Rounds & Mobile App Partners

Shot-Level Schema

Required Fields

Field	Type	Description
`sourceId`	`string`	Unique shot identifier, stable across re-fetches.
`roundId`	`string`	Parent round identifier.
`holeId`	`string`	Identifier for the hole this shot belongs to.
`clubType`	`string \| null`	Club used (see Appendix C).
`startLat` / `startLon`	`number`	GPS coordinates where the shot was struck.
`shotTime`	`string`	ISO 8601 timestamp of the shot.

Strongly Recommended Fields

Field	Type	Description
`startTerrain`	`string`	Lie at the start of the shot. One of: `TEE`, `FAIRWAY`, `ROUGH`, `SAND`, `RECOVERY`, `GREEN`, `UNKNOWN`.
`endTerrain`	`string`	Lie where the ball ended up (same enum).
`penalties`	`integer`	Number of penalty strokes assessed on this shot (0 if none).

Nice-to-Have Fields

Field	Type	Description
`shotInHole`	`integer`	1-indexed sequence number of this shot within the hole. If not provided, we infer ordering from timestamps.
`endLat` / `endLon`	`number \| null`	GPS coordinates where the ball came to rest. Highly valuable for distance and strokes-gained calculations.
`startMetersToGreen`	`number \| null`	Distance from shot origin to center of green, in meters.
`endMetersToGreen`	`number \| null`	Distance from ball resting position to center of green, in meters.
`shotDistance`	`number \| null`	Straight-line distance the ball traveled, in meters.

Hole-Level Schema

Required Fields

Field	Type	Description
`holeNumber`	`integer`	1–18.
`par`	`integer`	Par for the hole.
`score`	`integer`	Player's score on the hole.

Strongly Recommended Fields

Field	Type	Description
`putts`	`integer`	Number of putts taken.
`fairwayResult`	`string \| null`	`"HIT"`, `"LEFT"`, `"RIGHT"`, or `null` (for par 3s).
`totalPenalties`	`integer`	Sum of penalty strokes on the hole.
`firstPuttDistanceFeet`	`number \| null`	Distance of the first putt in feet.
`pinLatitude` / `pinLongitude`	`number \| null`	Actual pin position for this round.

Nice-to-Have Fields

Field	Type	Description
`gir`	`boolean`	Green in regulation.
`upDown`	`boolean \| null`	Whether the player got up-and-down from off the green.

Round-Level Schema

Field	Type	Description
`roundId`	`string`	Unique round identifier.
`courseId`	`string`	Identifier for the course played. Ideally the USGA course identifier.
`courseName`	`string`	Human-readable course name.
`teeName`	`string \| null`	Tee set played (e.g., `"Blue"`, `"White"`).
`courseRating`	`number \| null`	USGA course rating for the tee played.
`slopeRating`	`number \| null`	USGA slope rating for the tee played.
`roundDate`	`string`	ISO 8601 date of the round.