SDS Output Schema v1.0 and Versioning

What is fixed today

Schema version 1.0 is enforced on every extraction. The extraction record (outputs.json, and data for bulk items) always contains these 16 sections, in this order, whatever the document looks like:

product_identification, hazards_identification, composition, first_aid, fire_fighting, accidental_release, handling_storage, exposure_controls_ppe, physical_chemical_properties, stability_reactivity, toxicological_information, ecological_information, disposal_considerations, transport_information, regulatory_information, revision_metadata.

• Inside each section the field names are fixed too (about 100 fields in all, for example storage_class, water_hazard_class, voc_content, svhc_substances and per-mode transport_information.modes). The machine-readable definition is a JSON Schema: /schema/sds-schema-v1.json.
• A value that is not in the document is null; a list that is not in the document is empty. Nothing is guessed to fill a gap.
• The model is asked for exactly this structure. Whatever it returns is then checked against the schema on our side: unknown keys are dropped, missing keys are added as null, and simple type slips (a number where text is expected, a single string where a list is expected) are corrected. If the model ignored the structure, the response carries a warning to review it.
• Beside the record, responses carry document_language, is_safety_data_sheet, confidence_score, warnings and schema_version. A document that is not a safety data sheet is flagged with is_safety_data_sheet: false and a warning.

What the schema does not fix is the content of the values. They are copied from the document by a language model, so wording, completeness and accuracy are not guaranteed; the confidence score is the model's own estimate. See the accuracy methodology.

Pinning the version

Send schema_version as a form field on POST /extract-sds or POST /extract-sds/bulk. Only 1.0 exists, so today pinning protects you from the day a second version appears: you keep receiving the shape you integrated against, and a value we do not support is refused instead of being answered with a different shape.

curl -X POST https://safetydatasheetapi.com/extract-sds \
  -H "Authorization: Bearer $SDS_API_KEY" \
  -F "[email protected]" \
  -F "schema_version=1.0"

An unsupported value returns 400 with error.code unsupported_schema_version and lists the supported versions. Leaving the field out means the current version.

Rules for changing the schema

Versions are written MAJOR.MINOR. These are the rules we commit to for any future release; no second version has been released yet.

• Every change is listed in the changelog before or when it ships.
• Unpinned requests receive the current version, so production integrations should pin.
• Not yet built: serving more than one version at the same time, and a published machine-readable diff between versions. We will say so here when they exist.

Custom schemas

Version 1.0 is one general schema for all customers. A customer-specific field set, names or mapping is an enterprise engagement on a dedicated deployment; see contact.

Update log

• 2026-10-24: Schema 1.0 enforced on every extraction (fixed sections and field names, nulls for missing values), schema_version pinning added, and this page rewritten to describe only what exists. The earlier text described a version policy, deprecation metadata and version 2 examples that were not implemented.

FAQ

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