For developers

Build on the RSM ID contract

RSM Core owns the identity types, grammar, registry contracts, resolver interfaces, and conformance fixtures. Applications consume them. This page maps each part to the section that defines it, and says plainly what has been built.

Specified, not deployed

The protocol is defined (Document 08) and a reference implementation is designed (Document 09); both are proposed. No registry, resolver, or public API is operating. The proposed host rsmid.org serves only this explanatory website, which exposes no API. Code listings in Document 09 are interface shapes, not released software.

Implementation contract

Eight logical modules

Defined by Doc 08 §12.1. The names describe logical modules, not a required repository layout; every language implementation shares one grammar and one set of test vectors.

identity

Defined by specification

Canonical RID types, generation, and validation. Pure, deterministic, and free of network or SQL dependencies.

Doc 08 §3.1 · Doc 09 §3.2

naming

Defined by specification

RRN and RSN parsing, formatting, and registration. The canonical ABNF, exact byte comparison, and a versioned kind registry; lexical parsing kept apart from registry validation.

Doc 08 §18.2 · Doc 08 §18.3 · Doc 09 §15.1

registry

Proposed reference architecture

Prefix, authority, resource, and space contracts. Transactional issuance, append-only events, permanent non-reuse.

Doc 08 §5.2 · Doc 09 §4.1

resolution

Proposed reference architecture

Resolver request and result models. Typed statuses mapped to HTTP in one place, Accept negotiation, problem responses, policy-aware disclosure.

Doc 08 §18.7 · Doc 09 §15.2

governance

Defined by specification

Jurisdiction, stewardship, and policy references. Issuance jurisdiction is history, not a complete policy.

Doc 08 §8.6 · Doc 09 §8.4

provenance

Defined by specification

Issuance, transfer, lineage, and lifecycle evidence. Auditable chains of authority with effective dates.

Doc 08 §9.4 · Doc 09 §4.4

interop

Defined by specification

HTTPS, JSON, JSON-LD, and external ID mappings. External identifiers stay distinguishable from RSM-issued RIDs.

Doc 08 §6.4 · Doc 08 §7.5

conformance

Not available yet

Language-independent validation fixtures. Go, Rust, and TypeScript implementations share the same vectors, extended in v1.1 to names, kinds, lifecycle, HTTP, privacy, trust, and JSON-LD.

Doc 08 §18.10 · Doc 09 §15.5

Two documents, two kinds of rule

Normative contract versus reference implementation

Document 08 states what every conforming implementation must do. Document 09 proposes one way to build it, subject to Document 08. Build to the left column; treat the right as a design you may adapt.

What Document 08 requires, beside what Document 09 proposes
Topic	Normative — Document 08	Reference implementation — Document 09
RID	Grammar, 16-character default suffix from 80 random bits, exact-equality comparison, non-reuse. Doc 08 §3.1 · Doc 08 §3.5	Go value types with validated constructors; a candidate generator that does not by itself guarantee uniqueness. Doc 09 §5 · Doc 09 §6.2
RRN and RSN	Canonical ASCII ABNF with bounded segments, exact byte comparison, and no case folding or decoding; kinds from a versioned registry; an RSN is an RRN whose kind is exactly space. Doc 08 §2.4 · Doc 08 §18.2 · Doc 08 §18.3	Separate rid, rrn, and rsn packages with no network or SQL dependencies, plus naming/abnf and naming/kinds; ParseRRN kept apart from ValidateRegisteredRRN. Doc 09 §3.2 · Doc 09 §15.1
Registry	Four logical registries, minimum Identity Record contents, authenticated administration, and auditable delegation. Doc 08 §5.2 · Doc 08 §5.3.1	A representative SQLite schema — explicitly incomplete — with one active binding per resource. Doc 09 §4.1.1 · Doc 09 §4.3
Resolution	The logical sequence and the eight typed statuses; GET and HEAD reserved at rsmid.org/<rid>; versioned identity APIs, with RRN lookup by query parameter, never as a path segment. Doc 08 §6.3 · Doc 08 §6.8 · Doc 08 §18.5	A route table (/v1/identities, /v1/names/resolve, /readyz …), a resolver sequence across prefix registry, identity registry, and Locus, and a Go resolution contract that classifies status before rendering. Doc 09 §7.1 · Doc 09 §7.4 · Doc 09 §15.2
Statuses on the wire	A default HTTP code for each logical status, disclosure-dependent 403/404 and 410/404, problem+json errors with a stable code, Accept negotiation with 406, HEAD parity, and Vary: Accept. Doc 08 §18.5 · Doc 08 §18.6 · Doc 08 §18.7	One central mapping from logical status to transport code; public redaction may answer forbidden with the same 404 as not_found. Issuance answers 201 Created. Doc 09 §15.3 · Doc 09 §7.2
Representations	Every representation exposes its RID. A JSON identity response carries at least rid, kind, identityStatus, and resolutionStatus; JSON-LD needs a stable context mapping every property, and illustrative IRIs must be labelled. Doc 08 §7.1 · Doc 08 §18.6 · Doc 08 §18.9	A JSON-LD profile example whose rsmid.org/vocab IRIs are proposed and illustrative, not registered or deployed. Doc 09 §15.4
Deployment	The prefix is never a hostname; persistence rests on stewardship and tested recovery, not syntax. A documentation site may share the host only if RID root paths stay reserved. Doc 08 §6.3 · Doc 08 §16.4 · Doc 08 §18.5	Go, SQLite, and three local Locus nodes on proposed development ports. Doc 09 §8.1 · Doc 09 §12

Identifiers

Grammar and test vectors

RID — Document 08 §3.1 (ABNF-style summary)

RID    = prefix "." suffix
prefix = "0" / %x31-39 *15DIGIT          ; 1–16 digits, no leading zero
suffix = 12*32CROCKFORD                  ; uppercase only
CROCKFORD = 0 1 2 3 4 5 6 7 8 9 A B C D E F G H J K M N P Q R S T V W X Y Z

; default: 16 characters, 80 bits from a CSPRNG
; equality: exact canonical character comparison

RRN and RSN — Document 08 v1.1 §18.2 (ABNF verbatim)

RRN          = "rrn:" realm ":" authority ":" jurisdiction ":" space ":" kind "/" resource-id
realm        = segment
authority    = segment
jurisdiction = segment
space        = segment
kind         = segment
resource-id  = segment *("/" segment)
segment      = lowercase-or-digit *(lowercase-or-digit / "-" / "_")
lowercase-or-digit = %x61-7A / DIGIT

; every segment 1–64 characters; resource-id at most 16 segments;
; whole RRN at most 512 ASCII bytes; compared by exact byte equality
; RSN = an RRN whose kind is exactly "space"
; rrn:451:451labs:us-ca:wellzai:space/root

Parse lexically first and verify registration separately: a valid RRN may name an unregistered realm, authority, or kind (Doc 08 §18.2, Doc 08 §18.3). Reject uppercase and percent-encoded input; never repair it.

Not to be confused with

Lexical validity and registration. A parser can tell you an RID is well formed; only the registry can tell you it was issued.

Doc 09 §2.1

Implementation status

Implemented in this repository

This website implements lexical RID, RRN, and RSN checks in src/lib/identity, tested against the Document 09 vectors. They are not a conformance suite.

Parser vectors from Document 09

JSON

{
  "spec": "rsm-identity-v1",
  "cases": [
    { "input": "451.7K4M9Q2X8D5P0R6T", "valid": true, "prefix": "451", "suffix": "7K4M9Q2X8D5P0R6T" },
    { "input": "451.7K4M9Q2X8D5P0R6I", "valid": false, "reason": "invalid Crockford Base32 character" },
    { "input": "0451.7K4M9Q2X8D5P0R6T", "valid": false, "reason": "noncanonical prefix" },
    { "input": "451.7K4M9Q2X8D5P0R6T", "valid": true, "registryValidation": "depends on prefix registration" }
  ]
}

Lexical fixtures stay separate from registry-aware issuance tests; generation is tested with a controlled random source.

Source: Doc 09 §9.1

Records

Identity record and representation

The identity record is the registry’s envelope for one RID: names and their history, issuing authority, lifecycle, and the binding to the authoritative space. The representation is what that space supplies: content, relationships, and revision state. Keep them distinct in your data model.

application/json — identity response, Document 08 §18.6 (illustrative)

{
  "rid": "451.7K4M9Q2X8D5P0R6T",
  "kind": "document",
  "identityStatus": "active",
  "resolutionStatus": "resolved",
  "primaryRrn": "rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model",
  "spaceRid": "451.SD27J6QHDVEF0DYY",
  "spaceRsn": "rrn:451:451labs:us-ca:wellzai:space/root",
  "authority": "451labs",
  "representations": [
    {
      "mediaType": "text/html",
      "role": "landing-page"
    },
    {
      "mediaType": "application/ld+json",
      "role": "semantic-description"
    },
    {
      "mediaType": "application/json",
      "role": "identity-record"
    }
  ]
}

application/ld+json — profile of Document 09 §15.4 (proposed vocabulary)

{
  "@context": {
    "rid": "https://rsmid.org/vocab/rid",
    "rrn": "https://rsmid.org/vocab/rrn",
    "kind": "https://rsmid.org/vocab/kind",
    "title": "https://purl.org/dc/terms/title",
    "identityStatus": "https://rsmid.org/vocab/identityStatus",
    "space": {
      "@id": "https://rsmid.org/vocab/space",
      "@type": "@id"
    }
  },
  "@id": "https://rsmid.org/451.7K4M9Q2X8D5P0R6T",
  "rid": "451.7K4M9Q2X8D5P0R6T",
  "rrn": "rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model",
  "kind": "document",
  "title": "Outcome Formation Model",
  "identityStatus": "active",
  "space": "https://rsmid.org/451.SD27J6QHDVEF0DYY"
}

Every JSON-LD property is mapped in the context, as Document 08 §18.9 requires; the earlier Document 09 example’s unmapped title and identityStatus are corrected by the v1.1 profile. The rsmid.org/vocab IRIs are proposed and illustrative — not registered, not deployed. Both examples describe one referent, identified by one RID.

Resource representation envelope — Document 08 §7.2 (illustrative)

{
  "rid": "451.7K4M9Q2X8D5P0R6T",
  "rrn": "rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model",
  "kind": "document",
  "name": "Outcome Formation Model",
  "space": {
    "name": "Wellzai",
    "rsn": "rrn:451:451labs:us-ca:wellzai:space/root"
  },
  "governance": {
    "issuanceJurisdiction": "us-ca",
    "visibility": "public"
  },
  "lifecycle": {
    "identity": "active",
    "revision": 7
  },
  "representations": [
    {
      "mediaType": "text/html",
      "role": "landing-page"
    },
    {
      "mediaType": "application/ld+json",
      "role": "semantic-description"
    }
  ]
}

Keep the identity response (§18.6) apart from a resource representation (§7.1–§7.2): the first is registry-level identity metadata; the second is what the authoritative space serves about the resource. Their field names differ — primaryRrn and identityStatus beside rrn and lifecycle.identity — and no published schema reconciles them yet.

In the specification

Every representation exposes its canonical RID; the final structure will be versioned JSON Schema.

Doc 08 §7.1 · Doc 08 §7.2

Implementation status

The JSON-LD context IRIs in Document 09 are placeholders — explicitly not valid production vocabulary.

Doc 09 §7.3

Resolver API

The proposed HTTP interface

Proposed reference architecture Routes from Doc 09 §7.1, with the routing rules of Doc 08 §18.5: GET and HEAD /{rid} are reserved for exactly one valid RID, every identity API is versioned, and an RRN is looked up by query parameter, never used as a path segment. Mutation routes require authentication and least-privilege authorization; the public identifier path is a resolution interface, not a permission grant.

Method	Path	Purpose
GET	/{rid}	Content-negotiated identity view
GET	/v1/identities/{rid}	Policy-permitted metadata
GET	/v1/names/resolve?rrn=…	RRN to RID
POST	/v1/identities	Authorized, idempotent registration
POST	/v1/spaces	RSN and space registration
GET	/v1/spaces/{rid}	Space capabilities and authority
POST	/v1/identities/{rid}/transfer	Governed binding transition
GET	/v1/identities/{rid}/events	Authorized identity events
GET	/readyz	Registry and resolver health

Resolution request — Document 09 §7.3

GET /451.7K4M9Q2X8D5P0R6T HTTP/1.1
Host: rsmid.org
Accept: application/ld+json

Response a conforming gateway would return — Document 08 §18.5–§18.7

HTTP/1.1 200 OK
Content-Type: application/ld+json
Vary: Accept
Cache-Control: public, max-age=300

{
  "@context": {
    "rid": "https://rsmid.org/vocab/rid",
    "rrn": "https://rsmid.org/vocab/rrn",
    "kind": "https://rsmid.org/vocab/kind",
    "title": "https://purl.org/dc/terms/title",
    "identityStatus": "https://rsmid.org/vocab/identityStatus",
    "space": {
      "@id": "https://rsmid.org/vocab/space",
      "@type": "@id"
    }
  },
  "@id": "https://rsmid.org/451.7K4M9Q2X8D5P0R6T",
  "rid": "451.7K4M9Q2X8D5P0R6T",
  "rrn": "rrn:451:451labs:us-ca:wellzai:document/outcome-formation-model",
  "kind": "document",
  "title": "Outcome Formation Model",
  "identityStatus": "active",
  "space": "https://rsmid.org/451.SD27J6QHDVEF0DYY"
}

A restricted identity, redacted — identical to not_found (§18.7)

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
Cache-Control: no-store

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "code": "not_found"
}

Errors are application/problem+json with a stable code from the eight logical statuses (Doc 08 §18.6). Responses that vary by Accept carry Vary: Accept; an unsupported Accept gets 406; HEAD matches GET without a body. Public caches need explicit freshness bounds and must never store principal-specific responses (Doc 08 §18.8). Status codes are computed by the same module the resolver demonstration uses; the freshness value and problem type shown are illustrative.

Implementation status

rsmid.org is proposed, not an operational resolver. A conforming resolver may run under any approved hostname; the RID-to-path mapping stays the same.

Doc 08 §2.5

Go deeper

Conformance

What a conforming implementation must do

Core — parse, validate, generate, serialize, and compare RIDs deterministically; parse RRNs and RSNs; preserve RRN-to-RID mappings; reject malformed identifiers. Doc 08 §14.1
Issuer — enforce prefix delegation, suffix uniqueness, atomic registration, permanent non-reuse, and auditable provenance; never claim authority under an unregistered prefix. Doc 08 §14.2
Resolver — resolve through verified registry authority, return typed outcomes, serve human and machine responses, and enforce disclosure policy. Doc 08 §14.3
Federation — preserve canonical RIDs across spaces, avoid ownership assumptions, and distinguish source-authoritative records from cached ones. Doc 08 §14.4

The v1.1 conformance extension

Valid and invalid RRNs for each structural boundary.
Round-trip parsing and formatting.
Kind registration, positive and negative cases.
Allowed and disallowed lifecycle transitions.
RRN, RSN, and RID routes mapping to the same canonical identity.
Accept and HEAD behaviour.
All eight logical statuses and their disclosure-dependent HTTP outcomes.
Restricted identity nondisclosure.
Trust failures, redirects, SSRF, cycles, revocation, and cache invalidation.
JSON-LD expansion without silently dropped profile properties.
Cross-implementation byte-consistent canonical identifiers.

A publicly available educational simulation — including the resolver on this site — is not proof of conformance of a production resolver, and an implementation must not mark a test as passed because a simulated website illustrated it (Doc 08 §18.10, Doc 09 §15.5).

Source: Doc 08 §18.10 · Doc 09 §15.5

The eighteen v1.0 acceptance tests

One hundred thousand locally generated RIDs are syntactically valid and unique.
Concurrent issuance transactions never commit duplicate RIDs.
Unsupported prefixes fail authoritative registration.
RID serialization and parsing are deterministic across supported languages.
RRN and RSN parsing follows the published grammar.
Registered RRNs map unambiguously to canonical RIDs.
A resource survives renaming and republishing without RID changes.
Relocating a Locus instance does not change resource identity.
Authorized RRN transfer preserves its original RID association.
Retired identifiers cannot be reissued.
HTML and JSON-LD resolve to the same underlying referent.
Contextual representation does not change canonical identity.
A public resolver does not disclose restricted resource information.
A cross-space relationship resolves by RID.
Jurisdiction and bioregional metadata can change independently of RID.
Resolver authority spoofing is rejected.
Historical identity records remain interpretable after registry changes.
External identifiers remain distinguishable from RSM-issued identities.

Plus negative tests for invalid encodings, ambiguous aliases, revoked authorities, concurrent transfers, stale caches, and malicious endpoint responses. Document 09 stages delivery through five release gates, from identity primitives to operational hardening.

Source: Doc 08 §14.5 · Doc 09 §11.1

Preparing your systems

Design choices that will make integration straightforward

Each follows from the specification and is safe to adopt before any registry exists.

Reserve a field for the canonical RID
Store the RID beside your own identifiers rather than overloading one key with both meanings. Compare RIDs by exact string equality.
Never parse meaning out of an RID
The prefix is a namespace, not a hostname or an owner. Type, space, place, and jurisdiction come from resolution, not from the identifier.
Keep names, locations, and revisions separate
An RRN is a name, a URL is a location, a revision is a state, a digest identifies bytes. None of them is the RID.
Reference across systems by RID, with provenance
Relationships should name both ends by RID and keep the originating space, predicate, and asserting authority. Never merge records on similarity alone.

Specification library

The nine RSM specifications

01–07 are published at rsmone.com. 08 and 09, the RSM ID documents, are reproduced on this site. Classification and maturity are separate: a document can be normative and still proposed.

No.	Specification	Governing question	Classification	Version	Maturity
01	Regenerative Systems Model — A Living Outcome-Forming Ecology	Why does RSM exist?	Normative specification	v2.0	Maturity not stated
02	RSM Subject Model	What can exist and participate?	Normative specification	v2.1	Draft
03	RSM Semantic Model & Taxonomy Architecture	How is meaning represented and extended?	Normative specification	v4.0	Draft
04	RSM Canonical Model & Protocol Specification	What is authoritative state, and how does it interact?	Normative specification	v2.3	Draft
05	RSM Runtime & Federation Architecture	How does RSM operate across independent systems?	Normative specification	v2.0	Draft
06	RSM Reference Implementation & Conformance Specification	How do we know an implementation is really RSM?	Normative specification	v2.0	Draft
07	RSM Technology & Infrastructure Architecture	Through what technology will the specifications be realized?	Implementation architecture	v1.0	Maturity not stated
08	RSM ID — Identity, Naming & Resolution Specification	How is every resource identified, named, and resolved?	Normative specification	v1.1	Proposed
09	RSM ID — Core Identity Reference Implementation	How will the identity system be built and verified?	Reference implementation specification	v1.1	Proposed

Build on the RSM ID contract

Eight logical modules

identity

naming

registry

resolution

governance

provenance

interop

conformance

Normative contract versus reference implementation

Grammar and test vectors

Identity record and representation

The proposed HTTP interface

What a conforming implementation must do

Design choices that will make integration straightforward

Reserve a field for the canonical RID

Never parse meaning out of an RID

Keep names, locations, and revisions separate

Reference across systems by RID, with provenance

The nine RSM specifications