Schemas / Document
rig.document
v0.31.0 · draft 3 fields 2 required
Fields
| Field | Type | Meaning | |
|---|---|---|---|
rig |
string | required | Contract version this document targets (MAJOR.MINOR.PATCH) |
document |
object | optional | Optional metadata (title, author, createdAt, modifiedAt, defaultUnit, colorSpace, language, timeZone, ifcSchema, pdfX, outputCondition, trapped, ...) |
entities |
array<object> | required | Scene / graph contents. An unparented rig.spatial.vertex is a scene; without one, unparented entities are the roots. |
JSON document envelope for Rig interchange. Format when present as a file or payload.
This is the Contract wire format (JSON). Field meaning remains POD; vectors and quats are JSON number arrays. On disk the envelope is a .rig file, or a .rigz ZIP when a data/ folder of sidecar files travels with it - interchange. Hosts may use other encodings internally - portable emission targets this envelope.
Root
colorSpace names the colour space every rgba / rgb value in the file is expressed in; absent = srgb. One key for the whole document - per-component colour spaces do not exist.
defaultUnit is the scene length unit ("mm", "px", "in", ...) for transform, geometry, and stroke. A rig.layout.page may override with unit. Ratios stay 0-1 - Measurements.
language is a BCP 47 tag (en, en-GB, fr) for the document's text. Hosts pick hyphenation and spelling resources from it - the region subtag matters (en-GB and en-US hyphenate differently), so a document that knows its region says so. Absent = host default. One key for the whole document - per-run language is a style concern, not envelope metadata.
Axes
One convention for the file. A host with another convention converts at the edge - same bargain as colorSpace.
- 2D page / geometry: +X right, +Y down. Rectangle
yis the top edge. - 3D: right-handed, +Y up. Camera and directional / spot light look along local −Z.
timeZone is an IANA id (e.g. Australia/Sydney) for wall-clock calendar fields (rig.calendar.*). Absent = host local. Do not put NTP hour offsets here - those are a host cache of “now” and break across DST.
ifcSchema is the IFC release this document was derived from (ifc2x3 / ifc4 / ifc4x3). Absent = not an IFC-derived document. Portable BIM meaning lives on rig.bim.*; .ifc files are a host mapping - openbim.md.
FGF / pellet jobs are rig.print.*, not these keys - print.md.
Print-job keys (optional):
An ICC DestOutputProfile is a host file / asset path at emit time - not a portable envelope blob.
Entity
Rules
- Component keys must be catalog schema ids - not host type names (
Transform) and not C++ class names. - Serialize only portable fields listed on each schema. Omit host caches (Euler, world matrix, selection state, dirty flags, GPU handles).
- Unknown
rig.*schema ids: validators warn by default; fail with--strict. - Being Rig means speaking this envelope: entities with POD components keyed by schema ids - see honors.md. The envelope is the portable composition. Live hosts also honor SUDE and runtime ECS conventions.
Extension components
A key matching x.<vendor>.<name> carries a component the Contract has not named. Validators pass the payload through unchecked and report it - including under --strict, where it is a note rather than a failure.
"components": {
"rig.spatial.transform": { "position": [0, 0, 0], "rotation": [0, 0, 0, 1], "scale": [1, 1, 1] },
"x.acme.flower_of_life": { "radius": 40, "rings": 3 }
}
This exists because "ship what you support" previously worked in one direction only: a host could implement part of Rig, but could not carry anything Rig had not named. A real host has more component types than the catalog has ids, so without an escape hatch it keeps a private format alongside .rig - the outcome the Contract exists to prevent.
The bargain is explicit. Extensions travel; they do not port. Another host will preserve them across a round trip if it is careful, and will not understand them. Nothing in the Contract gives x.* meaning, and no validator will ever check one.
So the namespace is a place to put what is genuinely yours, not a way to avoid the catalog:
- Reach for a
rig.*id first. If a concept is portable, it belongs in the vocabulary, and the catalog grows when a real host needs it. <vendor>should identify who owns the meaning - an app, an org, a pack.- Do not mirror a Contract component under
x.*to add one field. That splits the meaning across two keys and no reader will merge them. - Runtime state stays out. An extension is still POD you meant to save, not a cache with a new prefix.
Machine grammar: schemas/json/rig.document.schema.json.
See docs/interchange.md for on-disk .rig / .rigz.
JSON Schema
Resolves at https://rig.works/schemas/rig.document.schema.json —
raw file.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://rig.works/schemas/rig.document.schema.json",
"title": "rig.document",
"description": "Rig JSON document envelope. Component keys must be rig.<domain>.<name> schema ids.",
"type": "object",
"additionalProperties": false,
"required": [
"rig",
"entities"
],
"properties": {
"rig": {
"type": "string",
"description": "Contract version this document targets (e.g. 0.9.0).",
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
},
"document": {
"type": "object",
"additionalProperties": true,
"properties": {
"title": {
"type": "string"
},
"author": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"modifiedAt": {
"type": "string"
},
"defaultUnit": {
"type": "string"
},
"colorSpace": {
"type": "string",
"description": "Colour space for all rgba/rgb values (default: srgb)."
},
"language": {
"type": "string",
"pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
"description": "BCP 47 language tag for document text (e.g. en, en-GB). Hosts pick hyphenation and spelling resources from it - the region subtag matters (en-GB vs en-US patterns). Absent = host default."
},
"timeZone": {
"type": "string",
"description": "IANA time zone for wall-clock calendar fields (e.g. Australia/Sydney). Absent = host local."
},
"ifcSchema": {
"type": "string",
"enum": [
"ifc2x3",
"ifc4",
"ifc4x3"
],
"description": "IFC schema this document was derived from. Absent = not an IFC-derived document."
},
"pdfX": {
"type": "string",
"description": "PDF/X identification (e.g. PDF/X-4). Empty/absent = not a PDF/X job."
},
"outputCondition": {
"type": "string",
"description": "OutputIntent OutputConditionIdentifier (e.g. FOGRA39, CGATS TR 001)."
},
"trapped": {
"type": "string",
"enum": [
"unknown",
"true",
"false"
],
"description": "PDF Info Trapped; absent = unknown."
}
}
},
"entities": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"components"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Stable within this file; entity-typed fields reference these ids."
},
"components": {
"type": "object",
"propertyNames": {
"pattern": "^(rig|x)\\.[a-z0-9_]+\\.[a-z0-9_]+$"
},
"additionalProperties": true,
"properties": {
"rig.anim.curve": {
"$ref": "./rig.anim.curve.schema.json"
},
"rig.anim.tween": {
"$ref": "./rig.anim.tween.schema.json"
},
"rig.art.attribution": {
"$ref": "./rig.art.attribution.schema.json"
},
"rig.art.creation": {
"$ref": "./rig.art.creation.schema.json"
},
"rig.art.dimensions": {
"$ref": "./rig.art.dimensions.schema.json"
},
"rig.art.image": {
"$ref": "./rig.art.image.schema.json"
},
"rig.art.location": {
"$ref": "./rig.art.location.schema.json"
},
"rig.art.material": {
"$ref": "./rig.art.material.schema.json"
},
"rig.art.object": {
"$ref": "./rig.art.object.schema.json"
},
"rig.art.subject": {
"$ref": "./rig.art.subject.schema.json"
},
"rig.audio.analysis": {
"$ref": "./rig.audio.analysis.schema.json"
},
"rig.audio.bus": {
"$ref": "./rig.audio.bus.schema.json"
},
"rig.bim.building": {
"$ref": "./rig.bim.building.schema.json"
},
"rig.bim.classify": {
"$ref": "./rig.bim.classify.schema.json"
},
"rig.bim.comment": {
"$ref": "./rig.bim.comment.schema.json"
},
"rig.bim.facet": {
"$ref": "./rig.bim.facet.schema.json"
},
"rig.bim.occurrence": {
"$ref": "./rig.bim.occurrence.schema.json"
},
"rig.bim.pset": {
"$ref": "./rig.bim.pset.schema.json"
},
"rig.bim.relation": {
"$ref": "./rig.bim.relation.schema.json"
},
"rig.bim.site": {
"$ref": "./rig.bim.site.schema.json"
},
"rig.bim.space": {
"$ref": "./rig.bim.space.schema.json"
},
"rig.bim.spec": {
"$ref": "./rig.bim.spec.schema.json"
},
"rig.bim.storey": {
"$ref": "./rig.bim.storey.schema.json"
},
"rig.bim.topic": {
"$ref": "./rig.bim.topic.schema.json"
},
"rig.bim.type": {
"$ref": "./rig.bim.type.schema.json"
},
"rig.bim.viewpoint": {
"$ref": "./rig.bim.viewpoint.schema.json"
},
"rig.book.contribution": {
"$ref": "./rig.book.contribution.schema.json"
},
"rig.book.cover": {
"$ref": "./rig.book.cover.schema.json"
},
"rig.book.identifier": {
"$ref": "./rig.book.identifier.schema.json"
},
"rig.book.publication": {
"$ref": "./rig.book.publication.schema.json"
},
"rig.book.subject": {
"$ref": "./rig.book.subject.schema.json"
},
"rig.book.title": {
"$ref": "./rig.book.title.schema.json"
},
"rig.cad.boolean": {
"$ref": "./rig.cad.boolean.schema.json"
},
"rig.cad.chamfer": {
"$ref": "./rig.cad.chamfer.schema.json"
},
"rig.cad.cuboid": {
"$ref": "./rig.cad.cuboid.schema.json"
},
"rig.cad.cylinder": {
"$ref": "./rig.cad.cylinder.schema.json"
},
"rig.cad.dimension": {
"$ref": "./rig.cad.dimension.schema.json"
},
"rig.cad.extrude": {
"$ref": "./rig.cad.extrude.schema.json"
},
"rig.cad.fillet": {
"$ref": "./rig.cad.fillet.schema.json"
},
"rig.cad.reference_line": {
"$ref": "./rig.cad.reference_line.schema.json"
},
"rig.cad.reference_plane": {
"$ref": "./rig.cad.reference_plane.schema.json"
},
"rig.cad.revolve": {
"$ref": "./rig.cad.revolve.schema.json"
},
"rig.cad.sphere": {
"$ref": "./rig.cad.sphere.schema.json"
},
"rig.calendar.attendee": {
"$ref": "./rig.calendar.attendee.schema.json"
},
"rig.calendar.event": {
"$ref": "./rig.calendar.event.schema.json"
},
"rig.calendar.exception": {
"$ref": "./rig.calendar.exception.schema.json"
},
"rig.calendar.recurrence": {
"$ref": "./rig.calendar.recurrence.schema.json"
},
"rig.calendar.span": {
"$ref": "./rig.calendar.span.schema.json"
},
"rig.calendar.weekly": {
"$ref": "./rig.calendar.weekly.schema.json"
},
"rig.commerce.discount": {
"$ref": "./rig.commerce.discount.schema.json"
},
"rig.commerce.offer": {
"$ref": "./rig.commerce.offer.schema.json"
},
"rig.commerce.price": {
"$ref": "./rig.commerce.price.schema.json"
},
"rig.dev.machine": {
"$ref": "./rig.dev.machine.schema.json"
},
"rig.dev.op": {
"$ref": "./rig.dev.op.schema.json"
},
"rig.dmx.fixture": {
"$ref": "./rig.dmx.fixture.schema.json"
},
"rig.font.anchor": {
"$ref": "./rig.font.anchor.schema.json"
},
"rig.font.avar": {
"$ref": "./rig.font.avar.schema.json"
},
"rig.font.axis": {
"$ref": "./rig.font.axis.schema.json"
},
"rig.font.cell": {
"$ref": "./rig.font.cell.schema.json"
},
"rig.font.component": {
"$ref": "./rig.font.component.schema.json"
},
"rig.font.face": {
"$ref": "./rig.font.face.schema.json"
},
"rig.font.glyph": {
"$ref": "./rig.font.glyph.schema.json"
},
"rig.font.group": {
"$ref": "./rig.font.group.schema.json"
},
"rig.font.kern": {
"$ref": "./rig.font.kern.schema.json"
},
"rig.font.layer": {
"$ref": "./rig.font.layer.schema.json"
},
"rig.geometry.arc": {
"$ref": "./rig.geometry.arc.schema.json"
},
"rig.geometry.ellipse": {
"$ref": "./rig.geometry.ellipse.schema.json"
},
"rig.geometry.line": {
"$ref": "./rig.geometry.line.schema.json"
},
"rig.geometry.mesh": {
"$ref": "./rig.geometry.mesh.schema.json"
},
"rig.geometry.nurbs_surface": {
"$ref": "./rig.geometry.nurbs_surface.schema.json"
},
"rig.geometry.path": {
"$ref": "./rig.geometry.path.schema.json"
},
"rig.geometry.path3d": {
"$ref": "./rig.geometry.path3d.schema.json"
},
"rig.geometry.polygon": {
"$ref": "./rig.geometry.polygon.schema.json"
},
"rig.geometry.rectangle": {
"$ref": "./rig.geometry.rectangle.schema.json"
},
"rig.geometry.regular_polygon": {
"$ref": "./rig.geometry.regular_polygon.schema.json"
},
"rig.geometry.ring": {
"$ref": "./rig.geometry.ring.schema.json"
},
"rig.geometry.spline": {
"$ref": "./rig.geometry.spline.schema.json"
},
"rig.geometry.spline3d": {
"$ref": "./rig.geometry.spline3d.schema.json"
},
"rig.geometry.star": {
"$ref": "./rig.geometry.star.schema.json"
},
"rig.input.buttons": {
"$ref": "./rig.input.buttons.schema.json"
},
"rig.interact.selectable": {
"$ref": "./rig.interact.selectable.schema.json"
},
"rig.io.dmx": {
"$ref": "./rig.io.dmx.schema.json"
},
"rig.io.osc": {
"$ref": "./rig.io.osc.schema.json"
},
"rig.io.sacn": {
"$ref": "./rig.io.sacn.schema.json"
},
"rig.io.serial": {
"$ref": "./rig.io.serial.schema.json"
},
"rig.layout.applied_master": {
"$ref": "./rig.layout.applied_master.schema.json"
},
"rig.layout.character_style": {
"$ref": "./rig.layout.character_style.schema.json"
},
"rig.layout.facing": {
"$ref": "./rig.layout.facing.schema.json"
},
"rig.layout.frame": {
"$ref": "./rig.layout.frame.schema.json"
},
"rig.layout.frame_chain": {
"$ref": "./rig.layout.frame_chain.schema.json"
},
"rig.layout.grid": {
"$ref": "./rig.layout.grid.schema.json"
},
"rig.layout.master": {
"$ref": "./rig.layout.master.schema.json"
},
"rig.layout.page": {
"$ref": "./rig.layout.page.schema.json"
},
"rig.layout.paragraph_style": {
"$ref": "./rig.layout.paragraph_style.schema.json"
},
"rig.layout.section": {
"$ref": "./rig.layout.section.schema.json"
},
"rig.layout.table_style": {
"$ref": "./rig.layout.table_style.schema.json"
},
"rig.led.uv_map": {
"$ref": "./rig.led.uv_map.schema.json"
},
"rig.legal.agreement": {
"$ref": "./rig.legal.agreement.schema.json"
},
"rig.legal.party": {
"$ref": "./rig.legal.party.schema.json"
},
"rig.light.look": {
"$ref": "./rig.light.look.schema.json"
},
"rig.media.asset_ref": {
"$ref": "./rig.media.asset_ref.schema.json"
},
"rig.media.code": {
"$ref": "./rig.media.code.schema.json"
},
"rig.media.text": {
"$ref": "./rig.media.text.schema.json"
},
"rig.meta.named": {
"$ref": "./rig.meta.named.schema.json"
},
"rig.meta.tags": {
"$ref": "./rig.meta.tags.schema.json"
},
"rig.mod.binding": {
"$ref": "./rig.mod.binding.schema.json"
},
"rig.mod.lfo": {
"$ref": "./rig.mod.lfo.schema.json"
},
"rig.mod.trigger": {
"$ref": "./rig.mod.trigger.schema.json"
},
"rig.music.arrangement": {
"$ref": "./rig.music.arrangement.schema.json"
},
"rig.music.clock": {
"$ref": "./rig.music.clock.schema.json"
},
"rig.music.midi_input": {
"$ref": "./rig.music.midi_input.schema.json"
},
"rig.music.midi_output": {
"$ref": "./rig.music.midi_output.schema.json"
},
"rig.music.note": {
"$ref": "./rig.music.note.schema.json"
},
"rig.music.pattern": {
"$ref": "./rig.music.pattern.schema.json"
},
"rig.music.sequencer": {
"$ref": "./rig.music.sequencer.schema.json"
},
"rig.music.step": {
"$ref": "./rig.music.step.schema.json"
},
"rig.music.transport": {
"$ref": "./rig.music.transport.schema.json"
},
"rig.node.graph": {
"$ref": "./rig.node.graph.schema.json"
},
"rig.node.link": {
"$ref": "./rig.node.link.schema.json"
},
"rig.node.node": {
"$ref": "./rig.node.node.schema.json"
},
"rig.node.param": {
"$ref": "./rig.node.param.schema.json"
},
"rig.node.pin": {
"$ref": "./rig.node.pin.schema.json"
},
"rig.node.publish": {
"$ref": "./rig.node.publish.schema.json"
},
"rig.organisation.identity": {
"$ref": "./rig.organisation.identity.schema.json"
},
"rig.paint.brush": {
"$ref": "./rig.paint.brush.schema.json"
},
"rig.paint.fill": {
"$ref": "./rig.paint.fill.schema.json"
},
"rig.paint.fill_stroke": {
"$ref": "./rig.paint.fill_stroke.schema.json"
},
"rig.paint.gradient": {
"$ref": "./rig.paint.gradient.schema.json"
},
"rig.paint.library": {
"$ref": "./rig.paint.library.schema.json"
},
"rig.paint.solid": {
"$ref": "./rig.paint.solid.schema.json"
},
"rig.paint.stroke": {
"$ref": "./rig.paint.stroke.schema.json"
},
"rig.paint.stroke_style": {
"$ref": "./rig.paint.stroke_style.schema.json"
},
"rig.paper.article": {
"$ref": "./rig.paper.article.schema.json"
},
"rig.paper.citation": {
"$ref": "./rig.paper.citation.schema.json"
},
"rig.paper.identifier": {
"$ref": "./rig.paper.identifier.schema.json"
},
"rig.paper.issue": {
"$ref": "./rig.paper.issue.schema.json"
},
"rig.party.account": {
"$ref": "./rig.party.account.schema.json"
},
"rig.person.contact": {
"$ref": "./rig.person.contact.schema.json"
},
"rig.person.employment": {
"$ref": "./rig.person.employment.schema.json"
},
"rig.person.name": {
"$ref": "./rig.person.name.schema.json"
},
"rig.person.portrait": {
"$ref": "./rig.person.portrait.schema.json"
},
"rig.person.vital": {
"$ref": "./rig.person.vital.schema.json"
},
"rig.pixel.canvas": {
"$ref": "./rig.pixel.canvas.schema.json"
},
"rig.pixel.composite": {
"$ref": "./rig.pixel.composite.schema.json"
},
"rig.pixel.effect_chain": {
"$ref": "./rig.pixel.effect_chain.schema.json"
},
"rig.pixel.layer": {
"$ref": "./rig.pixel.layer.schema.json"
},
"rig.pixel.mask_path": {
"$ref": "./rig.pixel.mask_path.schema.json"
},
"rig.pixel.palette": {
"$ref": "./rig.pixel.palette.schema.json"
},
"rig.pixel.raster": {
"$ref": "./rig.pixel.raster.schema.json"
},
"rig.pixel.region": {
"$ref": "./rig.pixel.region.schema.json"
},
"rig.pixel.source": {
"$ref": "./rig.pixel.source.schema.json"
},
"rig.pixel.tile_map": {
"$ref": "./rig.pixel.tile_map.schema.json"
},
"rig.pixel.tile_set": {
"$ref": "./rig.pixel.tile_set.schema.json"
},
"rig.place.address": {
"$ref": "./rig.place.address.schema.json"
},
"rig.place.geo": {
"$ref": "./rig.place.geo.schema.json"
},
"rig.plant.cultivar": {
"$ref": "./rig.plant.cultivar.schema.json"
},
"rig.plant.habit": {
"$ref": "./rig.plant.habit.schema.json"
},
"rig.plant.occurrence": {
"$ref": "./rig.plant.occurrence.schema.json"
},
"rig.plant.portrait": {
"$ref": "./rig.plant.portrait.schema.json"
},
"rig.plant.taxon": {
"$ref": "./rig.plant.taxon.schema.json"
},
"rig.print.compression": {
"$ref": "./rig.print.compression.schema.json"
},
"rig.print.job": {
"$ref": "./rig.print.job.schema.json"
},
"rig.print.machine": {
"$ref": "./rig.print.machine.schema.json"
},
"rig.print.material": {
"$ref": "./rig.print.material.schema.json"
},
"rig.print.process": {
"$ref": "./rig.print.process.schema.json"
},
"rig.render.blend": {
"$ref": "./rig.render.blend.schema.json"
},
"rig.render.light": {
"$ref": "./rig.render.light.schema.json"
},
"rig.render.material": {
"$ref": "./rig.render.material.schema.json"
},
"rig.render.visibility": {
"$ref": "./rig.render.visibility.schema.json"
},
"rig.rights.statement": {
"$ref": "./rig.rights.statement.schema.json"
},
"rig.sensor.gpio": {
"$ref": "./rig.sensor.gpio.schema.json"
},
"rig.sensor.presence": {
"$ref": "./rig.sensor.presence.schema.json"
},
"rig.sim.particle_emitter": {
"$ref": "./rig.sim.particle_emitter.schema.json"
},
"rig.sim.rigidbody": {
"$ref": "./rig.sim.rigidbody.schema.json"
},
"rig.spatial.anchor": {
"$ref": "./rig.spatial.anchor.schema.json"
},
"rig.spatial.camera": {
"$ref": "./rig.spatial.camera.schema.json"
},
"rig.spatial.group": {
"$ref": "./rig.spatial.group.schema.json"
},
"rig.spatial.layer": {
"$ref": "./rig.spatial.layer.schema.json"
},
"rig.spatial.relationship": {
"$ref": "./rig.spatial.relationship.schema.json"
},
"rig.spatial.transform": {
"$ref": "./rig.spatial.transform.schema.json"
},
"rig.spatial.vertex": {
"$ref": "./rig.spatial.vertex.schema.json"
},
"rig.story.character_style": {
"$ref": "./rig.story.character_style.schema.json"
},
"rig.story.flow": {
"$ref": "./rig.story.flow.schema.json"
},
"rig.story.paragraph": {
"$ref": "./rig.story.paragraph.schema.json"
},
"rig.story.paragraph_style": {
"$ref": "./rig.story.paragraph_style.schema.json"
},
"rig.story.table": {
"$ref": "./rig.story.table.schema.json"
},
"rig.ui.action": {
"$ref": "./rig.ui.action.schema.json"
},
"rig.ui.control": {
"$ref": "./rig.ui.control.schema.json"
},
"rig.ui.group": {
"$ref": "./rig.ui.group.schema.json"
},
"rig.ui.panel": {
"$ref": "./rig.ui.panel.schema.json"
}
}
}
}
}
}
}
}