Rights Layer Specification

Data Model

Status: Draft v0.1.0 — This section is normative except where marked informative.

This document defines the abstract data model of Rights Layer and its canonical JSON serialization. The model is serialization-independent; JSON is the canonical interchange form, and a JSON-LD context is provided for graph/RDF interoperability. Other serializations (XML, CBOR, relational, …) are possible and conformant if they preserve the model.

Machine-readable schema: schema/rights-layer.schema.json.

1. General Rules

1.1 Identifiers

Every entity has an id that MUST be a URI.
Rights Layer is identifier-scheme-neutral: https: URLs, urn: URNs, did: identifiers, or any other URI scheme MAY be used. No scheme is required or privileged (Principle P1).
Identifiers denote; they do not authenticate. Verification of control over an identifier is out of scope.

1.2 Types

Every entity has a type whose value is a Rights Layer core term (Right, Action, …) optionally followed by additional profile types.

1.3 Time

All timestamps use RFC 3339 (date-time), with explicit offset or Z.
Events distinguish occurredAt (when the fact happened in the world) from recordedAt (when it was recorded in an expression).

1.4 References

A property whose name ends in Ref or whose type is a Reference holds a URI (or a Reference object) pointing at an entity, possibly in an external system of record. Dereferencing behavior is out of scope.

1.5 Extension

Any entity MAY carry additional properties under extensions (an object keyed by profile-defined names). Consumers MUST ignore unknown extensions. Core property semantics MUST NOT be altered by extensions (Principle P0: extensibility without interpretive ambiguity).

2. Normative Requirements

The following requirements bind every conforming expression, producer, and consumer. They restate and anchor the rules defined throughout this specification.

NR-1. One Eligibility SHALL represent exactly one requirement.
NR-2. One Action MAY have zero or more Eligibilities (0..n).
NR-3. One Eligibility SHALL have at most one valid Eligibility Response.
NR-4. One Eligibility Response SHALL correspond to exactly one Eligibility. A Response MUST NOT be shared across Eligibilities.
NR-5. The value of an Eligibility Response SHALL be a Boolean.
NR-6. true SHALL mean that the corresponding Eligibility is satisfied.
NR-7. false SHALL mean that the corresponding Eligibility is not satisfied.
NR-8. The absence of a Response SHALL mean that the Eligibility is unanswered. Absence MUST NOT be treated as a third value, and intermediate values (unknown, pending, indeterminate, notEvaluated, or similar) MUST NOT be introduced into the core model.
NR-9. An Eligibility Response SHALL be verifiably attributable to its legitimate issuer (authenticity) and SHALL provide a means to establish that it has not been altered after issuance (integrity).
NR-10. The mechanism by which authenticity and integrity are realized (digital signatures, PKI, verifiable credentials, authenticated channels, institutional infrastructures, or any other verifiable method) is outside the scope of this specification and SHALL NOT be constrained by it.
NR-11. A Decision for an Action SHALL be established only when every Eligibility associated with that Action has exactly one verifiable Response and every such Response is true.
NR-12. A Decision SHALL NOT represent an institutional legal effect. How an institution or system acts on an established Decision is outside the scope of this specification.
NR-13. An Exercise SHALL represent the fact that the Action was actually performed after its Decision was established.
NR-14. The core model SHALL NOT include a Context concept or any other general-purpose container for evaluation material.
NR-15. Institutional operation, evaluation methods, workflows, and implementation methods are outside the scope of this specification.

3. Entities

3.1 Subject

Property	Type	Req.	Description
`id`	URI	yes	Identifier of the subject
`type`	string	yes	`"Subject"`
`subjectKind`	string	no	e.g. `person`, `organization`, `legal-entity`, `public-body`, `system`, `software-agent`, `ai`, `robot`, `other` — open vocabulary; the core does not limit Subjects to humans
`name`	string	no	Display name (see Privacy)
`extensions`	object	no	Profile extensions

3.2 Object

Property	Type	Req.	Description
`id`	URI	yes	Identifier of the object
`type`	string	yes	`"Object"`
`objectKind`	string	no	Free classification, e.g. `land-parcel`, `vehicle-class`, `policy`, `share-class`, `service`
`description`	string	no	Human-readable description
`registryRef`	URI	no	Where the object is authoritatively recorded
`extensions`	object	no

3.3 Source

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Source"`
`sourceKind`	string	yes	`statute` \| `contract` \| `registration` \| `judgment` \| `administrative-act` \| `inheritance` \| `qualification` \| `ordinance` \| `other`
`citation`	string	no	Human-readable citation (e.g. article of law, contract clause)
`reference`	URI	no	Locator of the source in its system of record
`authorityRef`	URI	no	Authority behind the source
`agreementRef`	AgreementReference	no	When the source is an agreement
`validFrom` / `validUntil`	date-time	no	Effective period, if any
`extensions`	object	no

3.4 Right

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Right"`
`subjectRef`	URI	yes	The holding Subject
`objectRef`	URI	no	The related Object, if any
`sourceRefs`	URI[]	yes (1..*)	Grounding Sources
`actions`	Action[] or URI[]	yes (1..*)	Exercisable Actions (inline or by reference)
`status`	string	no	Informative derived state: `active` \| `suspended` \| `revoked` \| `expired`. Normative state is the Event history; how state is derived is not fixed by the core.
`eventRefs`	URI[]	no	History of this Right
`extensions`	object	no

3.5 Action

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Action"`
`name`	string	yes	Verb-like label, e.g. `use`, `sell`, `lease`, `build`, `drive`, `examine`, `operate`, `claim-benefit`, `vote`
`description`	string	no
`eligibilities`	Eligibility[]	no (0..*)	Requirements for exercising this Action, one per Eligibility (NR-1, NR-2)
`extensions`	object	no

Action names are an open vocabulary. The core fixes only the meaning of Action (“an act performed on the basis of a Right”); vocabulary and granularity (operate vs operateVehicle vs operateHeavyVehicle vs providePassengerTransport) are the responsibility of each institution or profile.

3.6 Eligibility

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Eligibility"`
`requirement`	string	yes	Human-readable statement of exactly one requirement (NR-1)
`requirementRef`	URI	no	The requirement’s authoritative definition in the governing institution (a statute clause, a published policy, or any external definition). Evaluation of the requirement is outside the layer.
`response`	EligibilityResponse	no	The at-most-one valid Response (NR-3). Absent = unanswered (NR-8).
`extensions`	object	no

An Eligibility MUST NOT bundle multiple requirements, express evaluation logic, or carry institutional effect. An Action needing ten requirements has ten Eligibility entries.

3.7 Eligibility Response

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"EligibilityResponse"`
`value`	boolean	yes	`true` = the Eligibility is satisfied; `false` = not satisfied (NR-5, NR-6, NR-7). No other value exists.
`issuerRef`	URI	yes	The identifiable entity that issued this Response. The core does not restrict issuer kinds (person, legal person, public body, industry body, system, AI, certification service, …).
`issuedAt`	date-time	yes	When the Response was issued
`proof`	ProofReference	yes	Means of verifying authenticity and integrity (NR-9). The mechanism is not constrained (NR-10).
`evidenceRefs`	URI[]	no	Optional supporting Evidence (auxiliary material; not the Response itself)
`extensions`	object	no

A Response appears in exactly one place: the response property of its Eligibility. This structurally guarantees the one-to-one binding (NR-3, NR-4). Rights Layer never generates Responses; how the issuer evaluated the requirement is outside the layer (NR-15).

3.8 Evidence

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Evidence"`
`evidenceType`	string	yes	e.g. `licence-record`, `registry-extract`, `certificate`, `attestation`, `document`
`evidenceSourceRef`	URI	yes	The Evidence Source it came from
`content`	object	no	Directly held evidence content (profile-defined shape) — direct holding and external reference are both allowed
`proof`	ProofReference	no	How it can be verified
`validFrom` / `validUntil`	date-time	no
`extensions`	object	no

Evidence is auxiliary reference material behind a Response, a Right, or a Source. It is never itself an Eligibility Response.

3.9 Evidence Source

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"EvidenceSource"`
`name`	string	no	e.g. “Land Registry”, “Medical Licence Register”
`operatorRef`	URI	no	Authority operating it
`extensions`	object	no

3.10 Authority

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Authority"`
`name`	string	no
`roles`	string[]	no	`grantor` \| `attester` \| `registrar` \| `regulator` — open vocabulary
`jurisdiction`	string	no	Free-form jurisdiction label
`extensions`	object	no

Any number of Authorities MAY be involved in a right structure (as Source authorities, Response issuers, Evidence Source operators, …). The core does not fix how many Authorities an institution has or how they are organized.

3.11 Decision

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Decision"`
`actionRef`	URI	yes	The Action whose Eligibilities are all satisfied
`rightRef`	URI	no	The Right the Action belongs to (convenience)
`responseRefs`	URI[]	yes	The Eligibility Responses this Decision rests on — exactly one per Eligibility of the Action, each with `value: true` (NR-11). Empty array when the Action has zero Eligibilities.
`requestRef`	URI	no	The ExerciseRequested Event that prompted evaluation, if any
`establishedBy`	URI	no	The entity that recorded the establishment
`establishedAt`	date-time	yes
`extensions`	object	no

A Decision entity asserts establishment: it exists only when the rule of NR-11 holds. There is no “negative Decision” — one false Response or one unanswered Eligibility means no Decision is established. A Decision carries no result code, no partial satisfaction, no weighting, and no institutional effect (NR-12). Alternative conditions and exceptions are expressed in how Eligibilities are defined, or outside the layer.

3.12 Exercise

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Exercise"`
`rightRef`	URI	yes
`actionRef`	URI	yes
`subjectRef`	URI	yes	Who performed the Action
`decisionRef`	URI	yes	The established Decision that preceded performance (NR-13)
`eventRefs`	URI[]	no	Its Exercise Events
`extensions`	object	no

An Exercise records the fact of actual performance. It does not automatically carry institutional validity; effect, start/end processing, suspension, cancellation, audit, and billing are external responsibilities.

3.13 Event / Exercise Event

Property	Type	Req.	Description
`id`	URI	yes
`type`	string	yes	`"Event"` (Exercise Events additionally carry `"ExerciseEvent"`)
`eventType`	string	yes	Core: `RightGranted` \| `RightRevoked` \| `RightSuspended` \| `RightReinstated` \| `SourceChanged` \| `ExerciseRequested` \| `EligibilityResponseIssued` \| `DecisionEstablished` \| `ExerciseStarted` \| `ExerciseEnded`
`aboutRef`	URI	yes	The Right, Source, Eligibility, Decision, or Exercise concerned
`actorRef`	URI	no	Who caused / recorded the fact
`occurredAt`	date-time	yes	When the fact happened
`recordedAt`	date-time	no	When it was recorded
`data`	object	no	Event-type-specific payload
`proof`	ProofReference	no
`extensions`	object	no

Events are append-only: a recorded Event MUST NOT be modified or deleted; corrections are expressed by later Events. An Event records a fact and carries no institution-specific state-transition logic; which institutional effect attaches to which Event is decided outside the layer.

3.14 Proof Reference

Property	Type	Req.	Description
`type`	string	yes	`"ProofReference"`
`proofKind`	string	no	Free-form label of the verification mechanism (`registry-lookup`, `signed-document`, `paper-record`, …). No specific technology is assumed.
`reference`	URI	yes	Where/how to verify
`description`	string	no

3.15 Agreement Reference

Property	Type	Req.	Description
`type`	string	yes	`"AgreementReference"`
`reference`	URI	yes	Locator of the agreement
`agreementKind`	string	no	`contract` \| `terms` \| `treaty` \| `policy` \| `other`
`partyRefs`	URI[]	no	Parties to the agreement

4. Document Form (informative)

A Rights Layer document is a JSON object with:

{
  "@context": "https://rights-layer.org/ns/v0",
  "type": "RightsExpression",
  "specVersion": "0.1.0",
  "entities": [ { "...": "Subject / Object / Right / ... entities" } ]
}

@context is OPTIONAL and only needed for JSON-LD processing. Plain-JSON consumers MAY ignore it. The namespace URI is served under the project domain rights-layer.org.

An Action with answered Eligibilities looks like this (informative):

{
  "id": "urn:example:action:001",
  "type": "Action",
  "name": "drive",
  "eligibilities": [
    {
      "id": "urn:example:eligibility:001",
      "type": "Eligibility",
      "requirement": "The licence is within its validity period.",
      "requirementRef": "urn:example:requirement:a",
      "response": {
        "id": "urn:example:response:001",
        "type": "EligibilityResponse",
        "value": true,
        "issuerRef": "urn:example:issuer:1",
        "issuedAt": "2026-07-12T00:00:00Z",
        "proof": {
          "type": "ProofReference",
          "reference": "urn:example:proof:1"
        }
      }
    }
  ]
}

5. Conformance

An expression conforms to Rights Layer v0.1.0 if:

it validates against the JSON Schema, and
it respects the semantic rules of this document — in particular the normative requirements NR-1 to NR-15 (one requirement per Eligibility; at most one Boolean, verifiable Response per Eligibility; Decisions established only under the all-true rule; Exercises only after their Decision; append-only Events; at least one Source per Right), and
extensions do not redefine core semantics.

A producing system conforms if every expression it emits conforms. A consuming system conforms if it accepts every conforming expression and ignores unknown extensions.

Note that the JSON Schema cannot check cross-entity rules (e.g. that a Decision’s responseRefs cover every Eligibility of its Action); those are semantic conformance rules.

This site is open source. Improve this page.