XRAI RFCs
Requests For Comments — the process for changing the XRAI spec.
Small clarifications, typo fixes, and non-normative doc improvements don’t need an RFC. Submit them as direct PRs.
Anything that would require a version bump — new primitives, changed entity / relation schemas, new MIME types, new conformance requirements, new URI schemes — requires an RFC.
Why
Specs that drift without a paper trail rot. An RFC is a commitment: here’s the idea, here’s the motivation, here’s what will break, here’s how we migrate. Future you (and anyone reading the spec in 2029) will thank present you for writing it down.
Process
- Open a Discussion first. If the room shrugs, file an issue. If the idea has traction, proceed to RFC.
- Copy
0000-template.md to NNNN-<slug>.md. NNNN is the next available 4-digit number (check latest merged RFC + 1).
- Fill in every section honestly. “Alternatives considered” and “Backwards compatibility” are the ones most RFCs get wrong — no hand-waving.
- Open a PR with the RFC markdown only. No implementation. The RFC itself is the thing under review.
- Discussion period: minimum 2 weeks. Longer for breaking changes. BDFL (@jamestunick) is the eventual decider in Year 1; transitions to Apache/W3C Community Group post-1000-adopters.
- Accepted RFCs merge. Implementation happens in a follow-up PR that references the RFC number.
- Rejected RFCs merge into
rfcs/_rejected/ with a # Why not postscript. No RFC is deleted — the history is the library of decisions.
Statuses
- Draft — author still writing. PR in draft state.
- Under review — PR open, public discussion period active.
- Accepted — merged to
main. Implementation may begin.
- Implemented — ships in a spec version. RFC marked with the shipping version.
- Superseded — replaced by a later RFC. RFC keeps a pointer to the successor.
- Rejected — moved to
_rejected/ with a “Why not” postscript.
- Withdrawn — author pulled it before merge. Archived in
_withdrawn/.
What NOT to file an RFC for
- Typo / grammar / formatting in existing docs → direct PR
- Example clarifications (adding a sample that shows existing behavior) → direct PR
- New reference runtime adapters (Three.js / Unreal / visionOS) → direct PR, they conform to the spec, they don’t change it
- Tooling (validator CLI, MCP server extensions, test harness) → direct PR or issue
- Anything that breaks published schemas without a migration path → RFC and major version bump
In-flight RFCs
None yet. First candidates planned for v1.1:
- 0001 — Event primitives (temporal scheduling, trigger chains, reaction graphs). Currently stubbed in v1.0.
- 0002 — Typed n-ary hyperedges (replaces v1.0 binary relations). Currently spec’d at SPEC.md § Future.
- 0003 — Conformance test corpus + normative runtime behavior.
File one if you want to write it.
Governance note
RFCs are how the community shapes XRAI post-BDFL. Year 1: @jamestunick merges. Year 2+: transferred to Apache Software Foundation or W3C Community Group once 1000+ external adopters are validated. Never to a single-vendor foundation. The RFC process itself may be revised by an RFC (meta-level — use rfcs/meta/NNNN-<slug>.md).