Evidence
SDS Schema Versioning and Backward Compatibility
Version policy, compatibility guarantees, and migration examples for teams integrating SDS extraction outputs into long-lived enterprise workflows.
Last updated: 2026-03-10
Version policy
Schemas follow a semantic release model MAJOR.MINOR. Major versions can introduce breaking changes. Minor versions are additive and backward compatible. Every response includes a schema_version field and every request may pin the version explicitly.
| Release type | Example | Compatibility contract |
|---|---|---|
| Major | 2.0 | May rename/move fields. Migration guide and dual-run window required. |
| Minor | 2.3 | Additive fields only. Existing fields and semantics remain stable. |
| Patch | 2.3.1 | Non-contractual fixes only (parsing quality, docs, metadata quality). |
Backward compatibility rules
- Existing field names and types are immutable within a major line.
- New fields in minor versions are optional by default.
- Enumerations can only expand in minor versions, never contract.
- Deprecated fields remain supported for at least two minor releases or 180 days.
- Breaking changes require a new major version and a published migration map.
Deprecation lifecycle
| Phase | Duration | What customers see |
|---|---|---|
| Announce | Day 0 | Changelog notice and migration mapping published. |
| Dual support | 90 to 180 days | Old and new fields returned together with `deprecated` metadata. |
| Removal warning | 30 days before cutoff | Response-level warning and account notifications. |
| Removal | Cutoff date | Deprecated field removed in next major or scheduled minor cutoff. |
Migration example: Section 2 hazard object
v1.x payload
{
"schema_version": "1.9",
"hazards_identification": {
"classification": ["Flammable Liquid - Category 2"],
"h_statements": ["H225"],
"p_statements": ["P210"]
}
}v2.x payload
{
"schema_version": "2.0",
"hazards_identification": {
"ghs_classification": [
{
"code": "Flam. Liq. 2",
"label": "Flammable Liquid - Category 2"
}
],
"hazard_statements": [{ "code": "H225", "text": "Highly flammable liquid and vapour" }],
"precautionary_statements": [{ "code": "P210", "text": "Keep away from heat/sparks/open flames" }]
}
}Migration example: Section 3 composition table
v1.x payload
{
"composition": [
{
"name": "Acetone",
"cas": "67-64-1",
"percent": "95-100"
}
]
}v2.x payload
{
"composition": [
{
"substance_name": "Acetone",
"cas_number": "67-64-1",
"concentration": {
"min_percent": 95,
"max_percent": 100
}
}
]
}Compatibility matrix
| Client behavior | v1.x | v2.x | Recommendation |
|---|---|---|---|
| Version-pinned request | Supported | Supported | Preferred for production integrations. |
| Unpinned request | Receives account default | Receives account default | Avoid in regulated workflows. |
| Strict JSON schema validation | Stable within major line | Stable within major line | Update validators before major cutover. |
| Field alias fallback | Available during deprecation | Available during deprecation | Use only during migration window. |
Change communication and release cadence
- Minor schema releases are batched monthly.
- Major schema releases are planned quarterly with advance notice.
- Every release publishes a machine-readable diff and migration checklist.
- Accounts can schedule cutover windows for pinned schema upgrades.
Consumer migration checklist
- Pin current schema version in all extraction requests.
- Run dual-write validation on a representative holdout set.
- Compare downstream transforms and policy rules for renamed fields.
- Switch production traffic only after parity criteria are met.
- Remove deprecated field dependencies before cutoff date.
Update log
- 2026-03-10: Added explicit version policy, compatibility rules, and deprecation lifecycle.
- 2026-03-10: Added concrete migration examples for hazard and composition payload changes.
- 2026-03-10: Added compatibility matrix and client migration checklist.
FAQ
Can we stay on an older major schema while preparing migrations?
Yes. Major versions are supported in parallel during the published migration window, with clear deprecation dates for legacy contracts.
Will minor releases ever break our existing parser?
No. Minor releases are additive by policy. Existing field names, types, and meanings remain unchanged within a major version line.
How do we validate migration safety before cutover?
Use dual-run testing on your own SDS sample set, compare transformed outputs, and require parity on critical sections before switching traffic.
Related pages
- Accuracy methodology and scoring rules
- Benchmark results and cohort slices
- API docs and schema references
- Security controls and deployment model
- SDS extraction API
- Request schema migration support
Planning a schema migration?
Request schema migration support
and get a version-pinned cutover plan.