Handwriting semantics · Processing API
Smart Scorecards
scoring logic.
Map handwritten scorecard entries to stable API values, understand when the service withholds automatic acceptance, and build a review experience that never turns uncertain evidence into a guessed result.
Literal → canonical value → decision
Interpret the mark. Preserve the evidence.
For each supported page, POST /api/v1/scorecards/process returns one cell for every row and field. The service retains the visible literal, normalizes known scorecard notation into value, preserves alternate candidates, and assigns either ACCEPTED or NEEDS_REVIEW. Deterministic rules can only downgrade a result to review; they never replace a provider-selected value or fill a missing cell.
literal.Seven fields per row
Rows and numeric values.
Front-nine pages use rows 1–9; back-nine pages use 10–18. The printed total label FT or BT is returned as canonical row T. Numeric values are whole numbers from 0 through 999. An unrecorded cell is represented by null, not zero, except that a dash in putts explicitly means zero.
| Field | Recognized entry | Meaning |
|---|---|---|
score | 0–999 | The total strokes recorded for the hole. |
putts | 0–999 or a dash | A dash is interpreted as 0. A blank remains null. |
fir | Result mark, direction, or blank | Fairway-in-regulation outcome. A blank or dash remains null. |
teeClub | Supported club name or blank | The club used from the teeing area. |
gir | Result mark, direction, unavailable mark, or blank | Green-in-regulation outcome. A blank or dash remains null. |
approachClub | Supported club name or blank | The club used for the recorded approach. |
approachDistance | 0–999 or blank | A whole-number approach distance; blank remains null. |
The response always uses these fields: score, putts, fir, teeClub, gir, approachClub, approachDistance.
Case-insensitive club vocabulary
Normalize club names.
Whitespace, case, periods, underscores, and hyphens do not change a supported club token. The API returns an uppercase canonical value. Odd-degree wedges are supported across the complete 40°–70° range.
| Handwritten options | Canonical value | Behavior |
|---|---|---|
| D, Dr, DR, Drv, Driver | DRIVER | Accepted without review when the literal and provider value agree. |
| Md, MD, Mini Driver | MINI_DRIVER | Accepted without review when the literal and provider value agree. |
| 1W–9W | 1W–9W | Wood. |
| 1H–9H | 1H–9H | Hybrid. |
| 1I–9I | 1I–9I | Iron. |
| 1–9 | 1I–9I | A bare single digit defaults to the corresponding iron. |
| PW, LW, AW, GW, SW | Same token | Named wedge. |
| 40–70 | 40°–70° | A two-digit value in this range is a degree wedge. |
| 52w, 52d, 52*, 52° | 52° | Wedge suffixes are normalized to the degree value. |
4I, 5I, and 6I because a handwritten I is commonly read as 1. Use 51w, 51d, 51*, or 51° for a 51-degree wedge.Fairway and green outcomes
Resolve FIR and GIR marks.
FIR and GIR share the same hit, miss, mishit, and directional vocabulary. GIR additionally supports an explicit unavailable state. The canonical accuracy vocabulary currently contains 16 values.
| Handwritten options | Canonical value | Field | Behavior |
|---|---|---|---|
| ✓, ✔, ✅, ☑, check, checkmark, hit | HIT | FIR and GIR | Accepted when the provider value agrees. |
| X, ✕, ✖, ×, miss, missed | MISS_UNKNOWN | FIR and GIR | A recorded miss with no direction. |
| M, MH, mishit | MISS_MISHIT | FIR and GIR | A mishit is a miss, retained as its own canonical value. |
| - | null | FIR and GIR | Not recorded. |
| v | HIT | FIR and GIR | Treated as a likely OCR rendering of a handwritten check mark. |
Use a complete check mark when authoring or printing golfer instructions. The recognition service may normalize an OCR v to HIT. Arrows and chevrons are intentionally unsupported; use the documented letters and numbers instead.
Canonical miss geometry
Retain the direction of a miss.
Simple lateral or distance directions can be auto-accepted when every observation agrees. Combined directions are recognized but remain reviewable under the current policy. This conservative boundary avoids presenting a precise two-axis miss as settled when compact handwriting is difficult to distinguish.
| Handwritten options | Canonical value | Behavior |
|---|---|---|
| L, Left | MISS_LEFT | Accepted when the provider value agrees. |
| R, Right | MISS_RIGHT | Accepted when the provider value agrees. |
| FL, Far Left | MISS_FAR_LEFT | Accepted when the provider value agrees. |
| FR, Far Right | MISS_FAR_RIGHT | Accepted when the provider value agrees. |
| S, Short | MISS_SHORT | Accepted when the provider value agrees. |
| Lo, Long | MISS_LONG | Accepted when the provider value agrees. |
| RS, R/S | MISS_RIGHT_SHORT | Recognized, then routed to review as a compound direction. |
| RLo, R/Lo | MISS_RIGHT_LONG | Recognized, then routed to review as a compound direction. |
| LS, L/S | MISS_LEFT_SHORT | Recognized, then routed to review as a compound direction. |
| LLo, L/Lo | MISS_LEFT_LONG | Recognized, then routed to review as a compound direction. |
Arrows, chevrons, triangle-like marks, and prose descriptions of those shapes are not directional aliases. The service preserves the literal evidence, leaves the canonical value unresolved, and routes the cell to review.
GIR unavailable
| Handwritten options | Canonical value |
|---|---|
| UN | GIR_UNAVAILABLE |
| UR | GIR_UNAVAILABLE |
| NA or N/A | GIR_UNAVAILABLE |
| Unreachable or Unavailable | GIR_UNAVAILABLE |
| Not Available or Not Applicable | GIR_UNAVAILABLE |
GIR_UNAVAILABLE is valid only in gir. It represents a hole where the golfer could not reasonably attempt the green in regulation after an earlier shot. It is neither a hit nor an ordinary miss and should not be counted as a GIR opportunity. The same notation in fir is unresolved and requires review.
Conservative acceptance
Know why a cell needs review.
A recognized canonical value can still carry NEEDS_REVIEW. Clients must use decision as the acceptance boundary and treat value as reviewable evidence until a person confirms it.
| Review signal | Rule |
|---|---|
| Provider uncertainty | The provider marks the observation UNCERTAIN or INVALID, requests review, or returns more than one candidate. |
| Literal contradiction | The deterministic interpreter cannot reconcile the original literal with the provider-selected canonical value. |
| OCR correction | A likely glyph correction—such as W read as M, H read as N, or I read as 1—preserves candidates but requires review. |
| Compound direction | A combined lateral-and-distance miss is recognized, then receives COMPOUND_DIRECTION_REQUIRES_REVIEW under the current calibration policy. |
| Putts exceed score | Both cells are routed to review when a hole's putts are greater than its score. |
| FIR is not applicable | A populated FIR cell is routed to review when course context says FIR does not apply, including a par 3. |
providerConfidence is always null. The provider does not supply a calibrated field probability, so CADDIE.100 does not manufacture a percentage. Inspect decision, candidates, and evidence.reasonCodes instead.
Integration contract
Build review into the round flow.
ACCEPTED cells automatically. Present every NEEDS_REVIEW cell for confirmation, even when value is populated.null means no accepted recorded value. Zero is an explicit numeric value, including a dash in the putts field.literal, candidates, and reason codes to explain why the cell is being reviewed.See the processing endpoint contract → for request, response, idempotency, retention, and failure behavior.
scorecard-handwriting-interpretation@1; accuracy scorecard-accuracy-normalizer@2; clubs scorecard-club-normalizer@2; numeric literals scorecard-numeric-literal@1; calibration scorecard-handwriting-calibration@1; policy scorecard-handwriting-policy@1.