9. Architecture Decisions
Significant, hard-to-reverse architectural decisions are recorded as
Architecture Decision Records (ADRs) in docs/adr/, following the
MADR format (Context, Decision, Considered
Alternatives, Consequences).
| ADR | Decision |
|---|---|
| ADR-0001 | Use a monorepo with a language-neutral shared/ contract (schema, error codes, conformance fixtures) rather than separate repos per language or a cross-compiled single implementation. |
| ADR-0002 | Split validation into Level 0 (JSON Schema) and Level 1 (semantic rules), with Level 0 always short-circuiting Level 1 on failure, rather than running all checks together. |
| ADR-0003 | Automate schema updates from the spec repo via repository_dispatch + the GitHub Contents API, always landing as a human-reviewed PR — never fetched at runtime, never auto-merged. |
| ADR-0004 | Capture the operational preconditions (checkout credential handling, repo Actions write + PR-create permissions, browser-bundle rebuild) that the auto-sync depends on to open its PR end-to-end. |
| ADR-0005 | Stay on JSON Schema draft-07 rather than 2019-09/2020-12: OCF's variance is conditional (if/then on sport), not recursive, so $dynamicRef/unevaluatedProperties add cost without value and would risk TS↔Python parity. Re-evaluate only for a recursive-polymorphic feature or at a v2 major bump. |
New architecturally significant decisions (anything that would be costly to
reverse, or that future contributors would reasonably ask "why was it done
this way?") should be added as a new numbered ADR in docs/adr/ and linked
here.