Add ADR-0015: SSVC JSON schemas use SchemaVer for versioning#1121
Add ADR-0015: SSVC JSON schemas use SchemaVer for versioning#1121
Conversation
Resolves #601. Documents the decision to adopt SchemaVer (MODEL-REVISION-ADDITION) for SSVC JSON schema versioning, explaining why it fits schema evolution better than SemVer or CalVer, and defines the rules for incrementing each component. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
sei-renae
requested review from
cgyarbrough,
j--- and
sei-vsarvepalli
as code owners
There was a problem hiding this comment.
Pull request overview
Adds an Architectural Decision Record (ADR) documenting adoption of SchemaVer for SSVC JSON schema versioning, and updates the ADR index to reference it (resolves #601).
Changes:
- Added ADR-0015 describing SchemaVer (
MODEL-REVISION-ADDITION) for SSVC JSON schema evolution. - Updated
docs/adr/index.mdto include ADR-0015 in the Accepted Records list.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/adr/index.md | Adds ADR-0015 link to the ADR index. |
| docs/adr/0015-ssvc-json-schemas-use-schemaver.md | New ADR defining SchemaVer rationale, increment rules, and process implications for SSVC JSON schemas. |
| | Component | When to increment | Compatibility implication | | ||
| |------------|-------------------|--------------------------| | ||
| | `MODEL` | Schema change is incompatible with **any** historical data | Existing data **will not** validate | | ||
| | `REVISION` | Schema change may prevent interaction with **some** historical data | Existing data **may not** validate | | ||
| | `ADDITION` | Schema change is compatible with **all** historical data | Existing data **will** continue to validate | |
There was a problem hiding this comment.
The SchemaVer table uses leading double pipes (||) which will render as an empty first column (or break table formatting) in many Markdown renderers. Use standard table syntax with a single leading | per row so the table renders correctly in MkDocs.
| - A previously optional field becomes required (breaks data that omitted it) | ||
| - An `enum` gains values that affect round-trip processing for some consumers | ||
| - Constraints are tightened in a way that some existing data would fail (e.g., a minimum length | ||
| is added to a string field) |
There was a problem hiding this comment.
In the REVISION criteria, “An enum gains values …” does not make existing historical data fail validation, so it doesn’t match the earlier REVISION compatibility implication (“existing data may not validate”). Either move this to ADDITION (if focusing on validation compatibility), or adjust the compatibility definitions/wording to explicitly account for consumer/tooling compatibility rather than schema validation.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This pull request documents a new architectural decision to adopt SchemaVer for versioning SSVC JSON schemas, and updates the ADR index accordingly. The main goal is to provide a versioning scheme tailored to the compatibility needs of JSON schema consumers, rather than relying solely on Semantic Versioning (SemVer), which is already used for other SSVC components.
Documentation of new schema versioning approach:
0015-ssvc-json-schemas-use-schemaver.md) describing the adoption of SchemaVer for SSVC JSON schemas, detailing the rationale, versioning rules, and implications for compatibility and process.index.md) to include the new decision record for SchemaVer usage.Resolves Create ADR for SSVC JSON schema versioning #601. Documents the decision to adopt SchemaVer (MODEL-REVISION-ADDITION) for SSVC JSON schema versioning, explaining why it fits schema evolution better than SemVer or CalVer, and defines the rules for incrementing each component.