Key takeaways
- A safety data sheet has 16 standard sections; a good JSON record mirrors them one to one, so every system reads the same keys.
- Missing values stay null or empty: the extraction is instructed not to guess a field the document does not state.
- Every extraction carries a confidence_score and a warnings list, so review effort goes only where the document was unclear.
Why a fixed record matters#
Safety data sheets (SDS, also called MSDS) follow the 16-section layout of the Globally Harmonized System (GHS) and the EU CLP/REACH format. The layout is standard. The PDFs are not: every supplier typesets them differently, tables break across pages, and the same fact appears under different wording. A system that wants the UN number, the H statements or the flash point has to find them first.
A fixed JSON record removes that step. SafetyDataSheetAPI returns the same 16 sections, with the same field names, for every document. Downstream code reads transport_information.un_number whether the supplier is a multinational or a small distributor. The field list is published as a JSON Schema, and each section also has its own schema under /schema/sections/.
The 16 sections as keys#
Each GHS section maps to one top-level key:
product_identification: product name, codes, synonyms, supplier and contact detailshazards_identification: GHS classification, signal word, pictograms, H and P statementscomposition: an array of substances with CAS, EC and index numbers and concentrationsfirst_aid: measures by route of exposurefire_fighting: extinguishing media and special hazardsaccidental_release: precautions, containment and clean-uphandling_storage: safe handling, storage conditions, incompatibilitiesexposure_controls_ppe: exposure limits and protective equipmentphysical_chemical_properties: appearance, pH, melting and boiling points and morestability_reactivity: reactivity, stability, conditions to avoidtoxicological_information: acute and chronic endpointsecological_information: ecotoxicity, persistence, bioaccumulationdisposal_considerations: waste methods and contaminated packagingtransport_information: UN number, shipping name, hazard class, packing groupregulatory_information: regulations, REACH status, SVHC substancesrevision_metadata: issue and revision dates, version, superseded document
A worked example#
For an acetone SDS, the identification and transport parts of the record look like this (shortened):
{
"product_identification": { "product_name": "Acetone" },
"composition": [
{ "substance_name": "Acetone", "cas_number": "67-64-1", "concentration_percent": "100" }
],
"transport_information": {
"un_number": "1090",
"proper_shipping_name": "Acetone",
"hazard_class": "3",
"packing_group": "II"
}
}The response also carries a confidence_score, a warnings list and the output as JSON, XML and CSV, so one call serves an API consumer, an XML-based EHS system and a spreadsheet user.
Null means "not stated"#
If a supplier leaves out the flash point, flash_point comes back empty rather than estimated. That keeps compliance data honest. When a document is ambiguous, contradictory or partly unreadable, the record says so in warnings. Route any record with warnings or a low confidence_score to a person before using it for a compliance decision.
Frequently asked questions
How many fields are in the record?
The 1.0 schema has 16 sections and about 100 fields. The field list is published as JSON Schema and as an OpenAPI contract.
Can I get XML or CSV instead of JSON?
Yes. Each extraction returns JSON, XML and CSV in the same response, in an outputs object.
Will field names change?
Names are stable within a schema major version, and you can pin the version with schema_version. See the schema versioning policy.