Short answer
An SOP step data schema is a fixed set of fields that every extracted step must carry: identity and revision, the original text, a normalized action with its objects, tools and parameters, preconditions and success checks, safety marks, roles, media and provenance. Buyers define it before extraction so suppliers and annotators deliver comparable records that planners, alignment and evaluation can use without re-parsing documents.
Why fix the schema before extraction
Every downstream use of procedures reads the same step fields. Grounding records need the action and objects; video alignment needs stable step IDs and evidence of completion; task graphs need preconditions and produced states; evaluation items need text, order and success checks. If each supplier or extraction vendor structures steps its own way, you pay twice: once to extract and again to reconcile.
A written schema also becomes a contract artifact. Acceptance tests can check every delivered record against it, and later deliveries stay comparable with earlier ones. This page covers procedure text; the per-clip fields for demonstration video live in the demonstration clip metadata schema, and the two should share IDs.
Three record levels
- Procedure record: document identity, revision, effective date, owning role, source format, site scope, domain, language, occupation mapping and rights.
- Step record: one per step or substep, with the field groups below.
- Media record: each image or diagram with its callouts, linked to steps; sourcing such media is covered on visual work instructions.
Step field groups
| Group | Fields | Notes |
|---|---|---|
| Identity | step_id, procedure_id, revision, position, parent_step_id | Substeps point to their parent |
| Text | text_original, text_normalized, language | Original is verbatim and never edited |
| Action | verb, objects with roles, quantity | Roles: target, tool, material, fixture, location |
| Parameters | name, value, unit, tolerance, confidential flag | Keep the original string beside the normalized value |
| Conditions | preconditions, postconditions, success_check, branch reference | Success checks must be observable or marked otherwise |
| Safety and quality | hazard, required PPE, criticality, caution text | Criticality: safety, quality or none |
| Actor and timing | role, documented standard time | Only if the source states it |
| Structure | depends_on, optional, repeatable, granularity level | depends_on refers to the task graph |
| Evidence | visual_signature, linked media, linked video segments | visible, partly visible or non_visual |
| Provenance | extraction method, model version, reviewer, confidence, source location | Page and position in the source file |
Each group has a companion page where the hard choices are made. Preconditions and success checks follow preconditions and postconditions; numeric values follow parameters and tolerances extraction; how finely to split steps follows step granularity; dependencies follow task graphs from procedures.
Illustrative schema and record
{
"_comment": "Illustrative only — abbreviated JSON Schema for one step record",
"$id": "procedure_step.v0.4",
"type": "object",
"required": ["step_id", "procedure_id", "revision", "position", "text_original",
"verb", "objects", "success_check", "visual_signature", "provenance"],
"properties": {
"step_id": {"type": "string", "pattern": "^[A-Z0-9-]+\\.s[0-9]{2}(\\.[0-9]+)?$"},
"text_original": {"type": "string"},
"text_normalized": {"type": "string"},
"verb": {"enum": ["inspect", "clean", "place", "fit", "fasten", "hand_start", "route", "remove", "verify", "record"]},
"objects": {"type": "array", "items": {"type": "object",
"required": ["name", "role"],
"properties": {"name": {"type": "string"}, "role": {"enum": ["target", "tool", "material", "fixture", "location"]},
"part_no": {"type": ["string", "null"]}, "visible_cues": {"type": ["string", "null"]}}}},
"parameters": {"type": "array", "items": {"type": "object",
"properties": {"name": {"type": "string"}, "value": {"type": ["number", "null"]}, "unit": {"type": ["string", "null"]},
"original": {"type": "string"}, "confidential": {"type": "boolean"}}}},
"success_check": {"type": "object", "properties": {"text": {"type": "string"}, "observable": {"type": "boolean"}}},
"criticality": {"enum": ["safety", "quality", "none"]},
"visual_signature": {"enum": ["visible", "partly_visible", "non_visual"]},
"provenance": {"type": "object", "required": ["method", "source_page"]}
}
}
# Illustrative only — one synthetic record that validates against the schema above
step_id: WI-ASM-212.s06
procedure_id: WI-ASM-212
revision: E
position: 6
text_original: "Fit the cover and hand-start all four screws. Final torque per card TQ-7."
text_normalized: "Hand-start the four cover screws."
verb: hand_start
objects:
- {name: screw_m4, role: target, part_no: "000-5521", visible_cues: "silver pan-head, four in tray"}
- {name: cover_plate, role: fixture, part_no: "000-5502", visible_cues: "gray plate with two ribs"}
parameters:
- {name: final_torque, value: null, unit: null, original: "per card TQ-7", confidential: true}
preconditions: [cover_on, screws_staged]
success_check: {text: "all four screws engaged two or more turns", observable: true}
criticality: quality
visual_signature: partly_visible
depends_on: [WI-ASM-212.s05, WI-ASM-212.s04]
provenance: {method: model_then_review, model: extract_v0.3, reviewer: sme_A, source_page: 2, confidence: high}
Note what the record does with the compound source sentence: fitting the cover is a separate step (s05), the torque value is held back as confidential rather than silently dropped, and the original wording is kept.
Mapping from structured sources
When a supplier authors in a structured standard, map its elements to the schema rather than re-extracting from rendered PDFs. DITA defines a task topic specialized from its generic topic type, in general and strict variants (OASIS DITA TC); ask which variant a supplier uses, since that determines how much normalization remains. S1000D keeps procedural content in data modules within a common source database, each identified by a unique data module code (S1000D Steering Committee); use that code as, or alongside, procedure_id to keep traceability.
For normalized text, a controlled language keeps verbs and phrasing consistent. ASD-STE100 Simplified Technical English is a controlled natural language standard for technical documentation (ASD STEMG, 2025); whether to adopt one is discussed on controlled-language procedures.
For coverage analysis, map each procedure to occupational task lists. O*NET maps task statements to detailed work activities (O*NET Resource Center), and the 2018 Standard Occupational Classification defines 867 detailed occupations, classifying each worker by the tasks performed (BLS, 2018). A shared occupation code on every procedure record makes gaps visible across suppliers; see occupational task taxonomies.
Rules that keep records usable
- Never edit text_original. Normalization goes in its own field.
- One action per step record. Compound sentences become substeps with a parent.
- Objects carry visible cues as well as names and part numbers, so they can be grounded.
- Units are normalized, with the original string retained.
- Confidential values are masked and flagged, never deleted without trace.
- Unknown is explicit: a null with a reason, not an empty string.
- The schema is versioned, and each record names the version it validates against.
Parameters that depend on the buyer
- Step granularity and the verb vocabulary.
- Which optional field groups are required for your use.
- Languages, and whether translations are separate records or fields.
- Whether model extraction is allowed, and what review it needs; see validating LLM-extracted steps.
- Delivery format. JSON Lines suits small corpora; a columnar format such as Apache Parquet, which supports nested data (Apache Software Foundation), suits large ones.
Acceptance tests
- Validation: every record passes the schema, with no exceptions.
- Completeness: every step in the sampled source documents, including steps hidden in tables and callouts, has a record.
- Round trip: on a sample, source_page and position lead back to the exact source text, and text_original matches it.
- Extraction accuracy: experts check a random sample of verbs, objects, parameters and success checks against the source; you set the error ceiling.
- Vocabulary conformance: verbs, roles and states come only from the agreed lists.
- Reference integrity: every depends_on, media and video reference resolves.
Limitations
A schema structures text; it adds no motion, force or perception data, and every step still needs demonstrations or robot data to be executed. Normalization can strip nuance, which is why the original text stays. Model-filled fields can invent parameters or conditions that the source does not state, so provenance and review are part of the schema, not extras.
Questions to ask suppliers and extraction vendors
- Are procedures authored in a structured format, or only as word-processor files and PDFs?
- Do documents use stable step numbers that survive revisions?
- Which parameters are confidential, and how should they be masked?
- Will extraction use a model, and which fields will a person review?
- How will you handle steps that live in tables, callouts or images?
- Can every record point back to the page and position it came from?
- How will schema changes be versioned and applied to records already delivered?
Discuss your requirements
If you want procedures delivered in a defined schema, share the schema and the tasks it should cover with SourceX. SourceX looks for US businesses that hold suitable procedures, checks the data and the supplier's licensing permissions, and coordinates the license and delivery. SourceX's role is sourcing, rights review, licensing and delivery coordination; extraction and annotation are scoped case by case. It reviews each requirement and follows up about potential sources; a request does not guarantee a match. The procedures hub, the humanoid training data guide and the catalog page on licensing SOPs and playbooks cover related material.
Explore sourcing and licensing options with SourceX
Sources
- DITA (Darwin Information Typing Architecture) - OASIS DITA Technical Committee — task topic type and its variants.
- S1000D International specification for technical publications using a common source database — procedural data modules with unique codes.
- O*NET Database: Task Statements and Detailed Work Activities — task statements mapped to work activities.
- Standard Occupational Classification (2018 SOC) — detailed occupations classified by tasks performed.
- ASD-STE100 Simplified Technical English — controlled language for technical documentation.
- Apache Parquet — columnar format for large record sets.