Schemas & Validation

JSON Schema is the contract layer between agents, tools, and the orchestrator agent. Every artifact crossing an agent boundary must validate.

Validation tool

python3 tool_scripts/common.py \
  --schema schemas/<name>.schema.json \
  --data <path/to/artifact.json>

Implementation: jsonschema library. Prints OK (exit 0) or error list (exit 1).

Writing a new schema

Template

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "<name>",
  "description": "What this artifact represents and who consumes it.",
  "type": "object",
  "additionalProperties": false,
  "required": ["field1", "field2"],
  "properties": {
    "field1": {
      "type": "string",
      "description": "What this field means in the pipeline."
    }
  }
}

Conventions

Rule	Why
`additionalProperties: false` on every object	Catch typos and hallucinated fields
Explicit `required` arrays	Fail fast on missing data
Rich `description` on every field	Agents read schema descriptions for semantics
Embed formulas in descriptions	`assembly.schema.json` includes the transform chain
Use `enum` for fixed sets	`joint_type`
`minItems`/`maxItems: 3` for vectors	Enforce `[x,y,z]` arrays

Array of objects pattern

"parts": {
  "type": "array",
  "minItems": 1,
  "items": {
    "type": "object",
    "additionalProperties": false,
    "required": ["name", "description"],
    "properties": { ... }
  }
}

Recursive definitions

Use $defs for nested structures (see parts.schema.json):

"$defs": {
  "part_hint": {
    "type": "object",
    "properties": {
      "children": {
        "type": "array",
        "items": { "$ref": "#/$defs/part_hint" }
      }
    }
  }
}

Integrating validation into subagents

Every subagent prompt ends with:

## After writing
Validate:
python3 tool_scripts/common.py --schema schemas/<name>.schema.json --data <path>
Fix any errors before finishing.

The orchestrator agent also validates after subagent writes and re-invokes on failure.

Integrating validation into the orchestrator agent

In orchestrator.md, after each subagent step:

Validate: python3 tool_scripts/common.py --schema schemas/<name>.schema.json --data <path>
Re-invoke with errors appended, up to loop.max_validation_retries times.

For orchestrator agent-written artifacts (render_views.json):

Validate render_views.json before rendering.

Testing schemas

Valid fixture

Create a minimal valid example and validate:

python3 tool_scripts/common.py \
  --schema schemas/parts.schema.json \
  --data test_fixtures/valid_parts.json

Invalid fixture

Test that missing required fields are caught:

# Should exit 1 with error messages
python3 tool_scripts/common.py \
  --schema schemas/parts.schema.json \
  --data test_fixtures/invalid_parts_missing_world_center.json

Against real run artifacts

python3 tool_scripts/common.py \
  --schema schemas/assembly.schema.json \
  --data .intermediate/dishwasher/001/iterations/006/assembly.json

Modifying an existing schema

Breaking changes (adding required fields, removing fields, changing types) require:

Update the schema
Update the agent prompt that produces the artifact
Update any agent/script that consumes the artifact
Update orchestrator agent skip logic if needed
Re-run or migrate existing .intermediate/ artifacts

Non-breaking changes (adding optional fields, improving descriptions) are safe.

Schema ↔ IR mapping

Schema	IR name	Producer
`parts.schema.json`	Parts IR	analyze subagent
`assembly.schema.json`	Layout IR	initialize_placement.py / update_placement.py
`critic.schema.json`	Critique IR	critic subagent
`render_views.schema.json`	Render plan	orchestrator agent
`component_dims.schema.json`	Component dims	blender_measure_glbs.py

Common validation errors

Error	Cause	Fix
`'field' is a required property`	Agent omitted a field	Re-invoke agent or add field manually
`Additional properties are not allowed`	Extra/hallucinated field	Remove the unknown field
`is not of type 'number'`	String where number expected	Fix type in JSON
`is too short`	`[x, y]` instead of `[x, y, z]`	Add missing axis

Extending the Pipeline Tool Script Standards