Rights Layer Specification

Examples Guide

Status: Draft v0.1.0 — This section is informative.

The /examples directory contains worked Rights Layer expressions — complete JSON documents in the canonical serialization of the Data Model. Every example follows the same chain: a Right held by a Subject, grounded in Sources, exercised through Actions whose per-Action Eligibilities (each exactly one requirement) are answered by Boolean Eligibility Responses issued from outside the layer, with a Decision established only when every Eligibility of an Action has exactly one verifiable Response and all are true, an Exercise recording actual performance after the Decision, and append-only Events explaining the history. What changes between examples is only the domain — which is the point: kinds live in Actions, not in Rights.

Every Response in the examples carries id, value, issuerRef, issuedAt, and a proof (Proof Reference) so that its authenticity and integrity can be verified; the verification mechanism is deliberately neutral. How an issuer evaluated a requirement is never expressed — that is outside the layer.

All identifiers in the examples use the urn:example: scheme. This is an example convention only; Rights Layer is identifier-scheme-neutral.

1. The Seven Examples

File	Domain	What it shows
`driving-licence.json`	Driving licence	The canonical starter example: a licence as a Right grounded in an administrative act, a single drive Action with two Eligibilities (validity, corrective-lenses condition), each answered `true` by its issuer, and a full exercise round trip — `ExerciseRequested`, `EligibilityResponseIssued` Events, the established Decision with `DecisionEstablished`, then `ExerciseStarted` and `ExerciseEnded`.
`healthcare.json`	Medical practice	A qualification-grounded Right whose Object is a category of activity, with two Actions (examine, operate) carrying different Eligibilities. The three operate requirements — licence in force, accredited facility, specialty credential — are answered by three different external issuers; the examine Eligibility is left unanswered, so no Decision exists for it. Full exercise chain for operate.
`construction.json`	Construction business	An organization as Subject. The build Action’s Eligibilities — building permission granted for the project, site supervisor assigned — are answered by the building permission office and an attestation issuer, composing two authorities without merging them. Full exercise chain for build.
`insurance.json`	Insurance policy	A contract-grounded Right (Agreement Reference) with a claim-benefit Action whose three Eligibilities are answered by the insurer and its claims department; all `true`, so the Decision is established and the settlement is recorded as the Exercise. Full exercise chain.
`real-estate.json`	Real estate ownership	Four Actions on one Right (use, sell, lease, build) — the clearest illustration that variety lives in Actions while the Right stays binary. The build Eligibilities, including “building permission has been granted for the project”, are answered `true` by the building permission office. Full exercise chain for build.
`shares.json`	Company shares	A Right grounded in the shareholder register, with a record-date Eligibility for vote answered `true` by the company against a record-date extract. Full exercise chain for vote; the receive-dividend Eligibility is left unanswered.
`subscription.json`	Service subscription	The negative path: the use-service Action has one `true` Response (subscription active) and one `false` Response (payment current). Because one Response is `false`, no Decision entity and no Exercise entity exist — there is no negative Decision and no third value; the `false` Response and the request remain in the Event history.

2. Recommended Reading Order

Start with driving-licence.json. It is the smallest complete chain — Source → Right → Action → Eligibility → Eligibility Response → Decision → Exercise → Exercise Events — and it is the example used in the Data Model and the Example API Draft. Read it side by side with the Conceptual Model diagram.
Then real-estate.json and healthcare.json, which together demonstrate the two central design positions: many Actions on one binary Right, and different Eligibilities per Action, each answered by the issuer competent for it.
Then subscription.json for the all-true rule seen from the other side: one false Response, and the Decision is simply not established — no negative Decision exists.
The remaining examples (construction.json, insurance.json, shares.json) can be read in any order; each adds one domain flavor to the same structure.

3. Validating the Examples

Every example validates against the machine-readable schema schema/rights-layer.schema.json, which uses JSON Schema draft 2020-12. Any validator supporting that draft works; Rights Layer requires no particular tool.

A generic Python snippet using the jsonschema package:

import json
from jsonschema import Draft202012Validator

with open("schema/rights-layer.schema.json") as f:
    schema = json.load(f)

with open("examples/driving-licence.json") as f:
    document = json.load(f)

validator = Draft202012Validator(schema)
errors = sorted(validator.iter_errors(document), key=lambda e: list(e.path))
if errors:
    for error in errors:
        path = "/".join(str(p) for p in error.path) or "(root)"
        print(f"{path}: {error.message}")
else:
    print("valid")

Run it from the repository root, substituting any example file name.

Schema validation checks structure only. Full conformance (Data Model, section 5) additionally requires the semantic rules — 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, as always, a valid expression is still only a claim (Security Considerations).

This site is open source. Improve this page.