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. |
| - A new optional field is added | ||
| - A constraint is relaxed (e.g., removing a `maxLength`) | ||
| - Documentation (`description`, `$comment`) is updated without changing validation behavior | ||
| - An `enum` loses previously disallowed values in a way that only expands what is valid |
There was a problem hiding this comment.
The ADDITION criteria bullet “An enum loses previously disallowed values …” is internally inconsistent: disallowed values aren’t part of an enum set, and losing enum values generally restricts validity (potentially invalidating existing data). Reword this example to reflect an additive/relaxing change (e.g., an enum gaining new allowed values or constraints being loosened).
| - An `enum` loses previously disallowed values in a way that only expands what is valid | |
| - An `enum` gains new allowed values in a way that only expands what is valid |
| Chosen option: **SchemaVer**, because it was designed specifically for JSON schema versioning and its | ||
| three components map directly onto the compatibility questions that matter for schema consumers. | ||
|
|
||
| SchemaVer uses the format `MODEL-REVISION-ADDITION`, starting at `1-0-0`: |
There was a problem hiding this comment.
“SchemaVer uses the format … starting at 1-0-0” may conflict with existing SSVC schema version identifiers already in the repo (e.g., some schemas use schemaVersion: "2.0.0" and some use 1-0-1). Consider adding a sentence clarifying how existing schemas are mapped into SchemaVer (initial assignment and migration/translation rules) so readers understand the starting point in practice.
| SchemaVer uses the format `MODEL-REVISION-ADDITION`, starting at `1-0-0`: | |
| SchemaVer uses the format `MODEL-REVISION-ADDITION`, starting at `1-0-0`. For existing SSVC | |
| schemas, adoption of this ADR preserves the current logical version and normalizes legacy dotted forms | |
| such as `2.0.0` to the equivalent SchemaVer form `2-0-0`; similarly, values already written as | |
| `1-0-1` are treated as already using SchemaVer, while newly introduced schemas begin at `1-0-0`: |
|
|
||
| ### Confirmation | ||
|
|
||
| - JSON schema files must include a `$schema` or metadata field carrying the SchemaVer string. |
There was a problem hiding this comment.
The confirmation step says JSON schema files must include a $schema field carrying the SchemaVer string, but $schema is the JSON Schema metaschema URI (and SSVC schemas already use it that way). Use $id and/or a dedicated version field (e.g., the existing schemaVersion property / definition) to carry the SchemaVer identifier, and update this text accordingly.
| - JSON schema files must include a `$schema` or metadata field carrying the SchemaVer string. | |
| - JSON schema files must continue to use `$schema` for the JSON Schema metaschema URI, and must | |
| carry the SchemaVer identifier in `$id` and/or a dedicated version field such as `schemaVersion`. |
| | 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.
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.