# description
JSON envelope returned by an image-to-VSON extractor. Carries the canonical Penman text, the derived Turtle, optional structured graph, and metadata. A consumer that only wants the graph reads .vson_p; a consumer that wants triples reads .vson_t; a consumer that wants nodes/edges for a UI reads .graph.

# properties.scene_id.description
Stable identifier for this scene. URL-safe, document-unique.

# properties.version.description
VSON spec version. "1.0" for v1.0 strict. "1.0.5" for v1.0 + caption renderer + Phase 0 ontology additions (vso:class, vso:modifier, Persona). "1.1" adds VSON-X surface form and partial validation profile. "1.2" re-mints the VSO/RCC-8/Allen/shape namespaces under https://w3id.org/vson/, replacing the host v1.0-v1.1 published under (withdrawn, not aliased — see spec/CHANGELOG.md v1.2.0); envelope structure is unchanged from 1.1. Backwards-compatible: every v1.0 envelope remains valid under newer spec versions.

# properties.source.description
Provenance of the scene. Optional. Producers SHOULD populate it for any non-hand-authored scene; this schema does not enforce that, it only requires source.kind once the object is present.

# properties.vson_p.description
VSON-P (Penman) authoring form. SHOULD be the canonical authoring artifact when extraction targets Penman. Consumers MUST round-trip vson_p -> vson_t via the reference transpiler and SHOULD NOT diverge from vson_t. v1.1 and later: in VSON-X mode this field is the empty string "" (back-conversion to Penman is deferred to a future version, whenever t2p ships); those envelopes MUST satisfy the if/then rule below — at least one of vson_p or vson_x is non-empty.

# properties.vson_p.examples[]
(s / Composition :viewedBy (c / CameraView :angle eye_level) :depicts (a / PhysicalObject :class Apple))

# properties.vson_t.description
VSON-T (Turtle 1.2 / Turtle-star) form derived from vson_p or vson_x. Consumers MAY parse this directly with rdflib or any Turtle parser. Always non-empty.

# properties.vson_x.description
VSON-X (compact sigil-based) form, optional. Populated when authoring/extraction surface was VSON-X. Spec: docs/vson-x-semantics.md. Available v1.1+.

# properties.graph.description
Optional structured projection for UI clients. Lossy w.r.t. RDF semantics (no RDF-star annotations). Use vson_t for full fidelity.

# properties.conformance.description
SHACL conformance report. Producers MUST run validation before emitting; consumers MAY trust the conforms flag without re-validating. Conforms is always interpreted within the chosen profile (see profile field).

# properties.conformance.properties.profile.description
Validation profile. "strict" (default) uses shapes/vson-shapes.ttl (v1.0 byte-identical behavior). "relaxed" uses shapes/vson-shapes-relaxed.ttl (viewer anchoring / lemma / Quality dimension+value / Quality modifier downgraded to sh:Warning) for authoring-time documents; as of v1.1 no shipped command selects that file, so a producer sets this to "relaxed" only if it validated against it itself. v1.1+. Consumers MUST inspect both conforms and profile to determine document status; conforms=true under relaxed is NOT equivalent to v1.0 conformance.

# properties.conformance.properties.violations.description
Empty when conforms=true under chosen profile.

# properties.extraction.description
Optional metadata about how this VSON document was produced.

# allOf[].$comment
v1.0 / v1.0.5: vson_p is the source of truth and MUST be non-empty.

# allOf[].$comment
v1.1 and v1.2: at least one authoring surface (vson_p or vson_x) MUST be non-empty. Either Penman extraction (vson_p non-empty, vson_x absent) or VSON-X extraction (vson_p='', vson_x non-empty). Every version admitted by the enum above that allows an empty vson_p MUST be listed here, or the rule silently stops applying to it.

# $defs.GraphNode.properties.class.description
Domain class for PhysicalObject / Aggregate / Substance.

# $defs.GraphEdge.properties.label.description
VSO/Allen/RCC predicate local name (e.g. depicts, agent, before, EC).

# $defs.GraphEdge.properties.qualifiers.description
Edge-level annotations (probability, viewer, manner, ...).