xra1

XRAI v1.0 — Public Specification Draft

Status: Pedagogical entry point + public draft. The full engineering spec (XRAI v2.0, glTF 2.0 + XRAI_core extension) is at specs/XRAI_FORMAT_SPECIFICATION_V2.md in the Portals monorepo. License: CC0 (public domain) for the normative JSON schema; MIT for reference parsers. Governance: BDFL (@jamestunick) until 1000+ external adopters, then community foundation transfer.

Two specs, one format:

• This doc (v1.0): minimal public-launch spec. Flat JSON. Grokkable in 1 hour, implementable in 1 week. Entry point for LLM authors + Three.js / PlayCanvas / WebXR adapters.
• XRAI_FORMAT_SPECIFICATION_V2.md (v2.0): full engineering spec. glTF 2.0-based with XRAI_core extension. The canonical Portals runtime format. “DNA, not the organism.”

v1.0 is a subset of v2.0 — every v1.0 doc is a valid v2.0 scene once wrapped in glTF envelope. Choose v1.0 for quick LLM authoring / lightweight tools; use v2.0 when you need glTF interop + the full entity-component-extension system.

Normative source of truth: the running Portals runtime. Whatever parses and renders correctly in Portals v4 today IS v1.0-compatible. Engineering spec v2 is what Portals actually emits; v1.0 is the stable public contract both specs guarantee.

---

Scope of v1.0

v1.0 covers scene-level spatial composition. Event/causal/counterfactual/agent/belief extensions are v1.1+ (see §Future).

v1.0 is deliberately minimal. Worse-is-better (Gabriel 1989). Lessons from JSON beating XML, WWW beating Xanadu.

Top-level schema (draft)

{
  "xrai_version": "1.0",
  "id": "<uuid-v4>",
  "created_at": "<ISO-8601>",
  "author": { "type": "llm|human|agent", "id": "<opaque>" },
  "origin": { "app": "portals", "version": "v4", "scene": "SimpleAR" },
  "scene": {
    "anchors": [],
    "entities": [],
    "relations": [],
    "events": []
  },
  "metadata": {}
}

Entity (primitive node)

{
  "id": "<local-id>",
  "type": "<type-uri>",
  "model_id": <int | null>,
  "transform": {
    "position": [x, y, z],
    "rotation": [x, y, z, w],
    "scale": [x, y, z]
  },
  "material": { "color": "<css-color>", "preset": "<name>", "opacity": 0..1 },
  "animation": { "type": "<anim-name>", "params": {} },
  "components": [ { "type": "<component-type>", "props": {} } ],
  "metadata": {}
}

Types in v1.0: object.primitive (cube/sphere/cylinder/capsule/plane/quad), object.glb (URL-referenced), object.hologram, object.light, object.emitter, object.wire-source.

Relation (binary edge, v1.0 only; hyperedges v1.1)

{
  "id": "<local-id>",
  "type": "<relation-type>",
  "from": "<entity-id>",
  "to": "<entity-id>",
  "props": {}
}

Relation types declared for v1.0: parent-of, wire-binds, reacts-to-audio, tracks. Runtime pass-through + renderer wiring ships in the reference implementation (see RFC-0004 — Relation types + runtime semantics for status). Conformance clause §4 “Preserves unknown fields on round-trip” covers forward-compat while runtime adopters catch up.

Event (v1.0 stub — fuller schema in v1.1)

{
  "id": "<local-id>",
  "t": "<ISO-8601>",
  "type": "<event-type>",
  "entity": "<entity-id>",
  "metadata": {}
}

MIME type + file extension

• application/vnd.xrai+json
• .xrai (single graph), .xrai.jsonl (stream)

URI scheme

• xrai://<graph-uuid>/node/<entity-id>
• xrai://<graph-uuid>/relation/<relation-id>
• xrai://<graph-uuid>/event/<event-id>

Minimal example

{
  "xrai_version": "1.0",
  "id": "a9b3c1d5-…",
  "created_at": "2026-04-22T12:00:00Z",
  "author": {"type": "human", "id": "jatunick@gmail.com"},
  "origin": {"app": "portals", "version": "v4", "scene": "SimpleAR"},
  "scene": {
    "anchors": [],
    "entities": [
      {
        "id": "cube_1",
        "type": "object.primitive",
        "model_id": 0,
        "transform": {
          "position": [0, 0.25, -1.5],
          "rotation": [0, 0, 0, 1],
          "scale": [0.18, 0.18, 0.18]
        },
        "material": {"color": "cyan", "preset": "neon"}
      }
    ],
    "relations": [],
    "events": []
  }
}

Conformance

A runtime conforms to XRAI v1.0 if it:

1. Accepts any well-formed v1.0 document
2. Renders entities with positions, rotations, scales, materials, animations
3. Preserves unknown fields on round-trip (forward-compat)
4. Produces v1.0 output that any other v1.0 runtime can consume

Future (roadmap, non-normative)

• v1.1: typed n-ary hyperedges (replaces binary relations); causal event chains; affordance primitives
• v1.2: counterfactual branches; POV / observer semantics
• v2.0: personal / shared namespaces; cryptographic provenance; federated queries
• v2.1: node embeddings + analogy retrieval; PageRank-style salience
• v3.0: self-referential schema; meta-layer events (“the graph noticed X”)

Contributing

• File issues with reproducible examples
• Propose changes as RFCs (markdown files in /rfcs/)
• BDFL (@jamestunick) merges during Year 1; community foundation transfer Year 2+
• MIT / CC0 only; no other licenses accepted

Acknowledgments

Built on 80 years of prior art: Vannevar Bush (memex), Ted Nelson (Xanadu), Tim Berners-Lee (WWW, GGG), Larry Page + Sergey Brin (PageRank), Douglas Hofstadter (analogy-as-cognition), Howard Pattee (epistemic cut), Herbert Simon (near-decomposability). XRAI is their synthesis, made shippable by LLMs.

This site is open source. Improve this page.