# Obligation-First — full LLM context

<!-- of-version: llms-full-current -->
> An open upper schema for normative content (laws, cases, joint interpretations) bound to Semantic Arts gist. v0.6.3 is the current released specification. Record `@id` values are adopter-local, opaque, and permanent. Jurisdiction represents legal competence, with territorial and institutional scope modeled independently.

This file is the deeper companion to llms.txt. Where llms.txt gives a one-screen summary, this file is the full context an LLM-powered tool needs to reason about Obligation-First, generate adopter records, or answer detailed questions without scraping.

## Specification

Source of truth: https://github.com/snapsynapse/obligation-first/blob/main/PROTOCOL.md

### Core principles

1. Obligation-first modeling — normative content is mapped through the obligations it creates, interprets, or allocates, not through the text of the source document.
2. Bind to existing standards — gist for upper ontology, LegalRuleML for deontic operators, Akoma Ntoso / ELI / ECLI / USLM for source-text IRIs. Reference, do not duplicate.
3. Permanent IRIs — `https://w3id.org/of/v1/` is the planned permanent vocabulary prefix and will resolve to `https://obligationfirst.org/v1/` once the w3id.org redirect is filed. Until then, `https://obligationfirst.org/v1/` is the live CI-verified resolution target.
4. Small core, explicit extensions - the spine, proceeding strand, category layer, Party, Jurisdiction, Tombstone, and shared provenance. Domain-specific metadata stays in an adopter-owned context.
5. Federated `@id` + crosswalks (v0.3) - record `@id` values are adopter-local, opaque, and permanent. Standard identifiers ride as typed crosswalks, never as the record `@id`. `owl:sameAs` is identity, `describesSameEntityAs` is weaker record correspondence, and `skos:exactMatch` is concept-to-concept alignment.
6. Evidence honesty (v0.6) - missing authority, deontic, actor, date, and lifecycle evidence remains unknown or absent. Adapters do not fabricate a basis, silently default an unknown duty to Requirement, or copy one date into another field.

### The four-role spine

| Role | of: term | gist class | What it is |
|---|---|---|---|
| Authority | of:Authority | wraps gist:Organization or gist:GovernmentOrganization | An organization exercising an evidenced legal, administrative, adjudicative, enforcement, or standards role |
| Container | of:Instrument | gist:Agreement (negotiated) / gist:Specification (promulgated) | The artifact with binding force — a law, agreement, or ruling |
| Secondary | of:Term | gist:Specification; negotiated Terms may also assert gist:ContractTerm | A clause or provision within an Instrument |
| Primary | of:Obligation | explicit unclassified state or deontic quartet | A source-grounded normative position |

### The proceeding strand

| Role | of: term | gist class |
|---|---|---|
| Matter | of:Proceeding | of:LegalProceeding over gist:Event |
| Asserted | of:Allegation | gist:Content (assertion text) + gist:Intention (when intent-bearing) |
| Decided | of:Determination | gist:Determination |

### The deontic quartet

| of: term | LegalRuleML | gist | Meaning |
|---|---|---|---|
| of:Requirement | lrml:Obligation | gist:Requirement | A primary duty to act |
| of:Restriction | lrml:Prohibition | gist:Restriction | A primary duty to refrain |
| of:Permission | lrml:Permission | gist:Permission | An authorized capacity to act |
| of:Reparation | lrml:Reparation | gist:Requirement + gist:Intention (+ gist:Event when actuated) — see note | A secondary duty triggered by violation of a primary obligation |

v0.2 closed the open gist binding for of:Reparation per Semantic Arts feedback (Dave McComb, 2026-05-26). The of:Reparation class is preserved as a distinct deontic subclass — LegalRuleML 1:1 alignment and SPARQL queryability depend on it. The gist binding is the layered pattern: gist:Requirement for the secondary duty itself, gist:Intention for the declared legislative intent attached to the creating Term, and (when the remedy is actually ordered or carried out) gist:Event conceptually, recorded via the proceeding strand.

### Core relations (full list)

- of:issuedBy (Instrument or Determination → Authority[]) - issuer or promulgator only
- of:heardBy (Proceeding → Authority[]) - forum hearing the matter
- of:administeredBy / regulatedBy / enforcedBy (Instrument → Authority[]) - distinct operational roles
- of:hasTerm (Instrument → Term[]) — composition
- of:creates (Term → Obligation[]) — the deontic content of a Term
- of:hasAllegation (Proceeding → Allegation[]) — asserted facts in a matter
- of:hasDetermination (Proceeding → Determination[]) — rulings issued in a matter
- of:decides (Determination → Allegation[]) — what the ruling resolved
- of:disposition (Determination → enum) — confirmed / rejected / partial / dismissed / settled / vacated / issued
- of:anchors (Determination, Term, or Obligation → Obligation, Term, or ObligationCategory) - interpretive link, not causal enforcement state
- of:recognizes / of:imposes (Determination → Obligation[]) - existing duty recognition versus new remedial duty imposition
- gist:isCategorizedBy (Obligation → ObligationCategory[]) - classification; exactMatch is not membership
- of:constrains (Determination → Instrument, Term, Obligation, or Determination) - causal limit on present effect
- of:resultingInstrument (Determination → Instrument[]) - joins an issuance act to a forward-looking normative artifact
- of:defeats (Term → Term[]) — Term-level override per Lawsky default logic / LegalRuleML §7.4. General/fallback defeasibility predicate.
- of:rebuts (Term → Term[]) — subproperty of of:defeats. Defeating Term reaches the opposite conclusion (LegalRuleML §7.4 rebut). Entails of:defeats. Added in v0.2.
- of:undercuts (Term → Term[]) — subproperty of of:defeats. Defeating Term denies the rule's applicability in this context (LegalRuleML §7.4 undercut). Entails of:defeats. Added in v0.2.
- of:violationOf (Reparation → Obligation) — symmetric/inverse of triggers_on_violation_of. Adopters MAY assert from either side; if both present, must be consistent. Added in v0.2.
- of:supersedes (Instrument → Instrument[]) — post-enactment whole-Instrument replacement
- of:wouldSupersede (Instrument → Instrument[]) — subjunctive form for proposed Instruments
- of:executableEncoding (Term | Obligation → typed reference) — pointer to a Catala / Blawx / OpenFisca / other executable encoding. Both Term and Obligation accept the field.

### Force and lifecycle

- `normative_force`: binding / voluntary / nonbinding / contractual / unknown
- `lifecycle_status`: publication or legal lifecycle
- `operative_status`: whether the content presently operates
- `enforcement_status`: whether it is presently enforceable and under what posture
- `computed_as_of`: date for computed present-state assertions

The axes are independent but graph validation rejects incoherent combinations such as proposed plus enforceable, voluntary plus enforceable without an evidenced binding basis, or a future effective date reported operative as of an earlier date.

### Authority interface

Every of:Authority requires an identified organization. `authority_basis` is optional and multi-valued. When present, each basis cites an Instrument, source URL, or source citation for legal competence. A silent source produces no basis instead of a fabricated self-reference. Jurisdiction is optional when unknown and uses of:Jurisdiction for legal competence; `territorial_scope` and `institutional_scope` remain independent.

### Defeasibility semantics

- Direct: A defeats B → A overrides B in any conflict.
- Transitive: A defeats B, B defeats C → A defeats C (closure may be computed; explicit relation is authoritative).
- No mutual defeat: A defeats B + B defeats A is invalid.
- Cross-Instrument allowed: a Term in Instrument X may defeat a Term in Instrument Y.
- Inferred conflict is out of scope. of:defeats is asserted, not inferred.
- Sub-types added in v0.2: of:rebuts (opposite conclusion) and of:undercuts (denies applicability), both subproperties of of:defeats. Either entails of:defeats; the general predicate remains valid for the v0.1-compatible binary case.

### ExecutableEncoding shape

Polymorphic typed reference:
- kind: catala | blawx | openfisca | logical-english | l4 | lkif | lrml | other
- uri (IRI of the encoding artifact)
- version (optional)
- engine_version (optional)
- notes (optional)

A Term or Obligation MAY have multiple executableEncoding references (one per engine).

### Conformance levels

- Level 1 — IRI-only: @id and @type use canonical of: IRIs. @context references https://obligationfirst.org/v1/context.jsonld. The @id resolves and is permanent, with HTTP 301 or a queryable Tombstone on retirement.
- Level 2 — Schema-and-graph-conformant (recommended): L1 plus record schemas, inverse and relation checks, lifecycle coherence, all emitted surfaces, a published `.well-known` naming profile, and typed legal-competence jurisdiction where the source supports one.
- Level 3 — Crosswalk-conformant: L2 plus (v0.3) every crosswalk the adopter's naming profile declares is present on every applicable record. The recommended baseline is the crosswalk matrix: Wikidata QID for authorities (SHOULD, sameAs), ELI for instruments where the jurisdiction issues ELIs (MUST, eli_uri), ECLI / neutral citation for court decisions (MUST), Akoma Ntoso element IRIs for provisions (SHOULD/MAY, akn_uri), urn:lex as a fallback (MAY), and EuroVoc concepts for obligation subjects (SHOULD). Requirements are RFC 2119 and conditional on coverage — a US-only adopter is never failed for lacking an ELI that does not exist. The earlier "round-trip with at least one of Akoma Ntoso, ELI, or ECLI" definition is superseded.

### Versioning

- Major version increments break adopters. Minor increments are additive. Patch increments are textual.
- IRI prefix is versioned by major: w3id.org/of/v1/, w3id.org/of/v2/, etc.
- v1.0 commitment: no breaking changes within v1.x. v2.0 is the only path for breaking changes.
- v1.x and v2.x will be maintained for 12 months after v2.0 ships.

## Worked examples (full)

### Moffatt v. Air Canada (BCCRT 149) — proceeding strand

Tests: Authority + 2 Parties + Proceeding + 2 Allegations + Determination + recognized common-law Requirement. Exercises typed actors, multi-valued decides, recognition grounding, and a remedy linked to its resulting Obligation.

Source: https://github.com/snapsynapse/obligation-first/blob/main/examples/air-canada/README.md

### Colorado SB 24-205 — three-layer reality

Tests:
- Layer 1 (legislation): 2 Authorities + 1 Instrument (status: enacted, enforcement_status: constrained) + 1 Term + 1 Requirement + 1 Reparation.
- Layer 2 (enforcement): Proceeding + Allegation + 2 Determinations (federal stay + AG non-enforcement statement).
- Layer 3 (political direction): 2nd Instrument, SB26-189 Automated Decision-Making Technology (status: proposed until signed), with wouldSupersede pointing at SB 24-205. 3rd Authority (Colorado AI Policy Work Group) with non-government authority_basis.

Source: https://github.com/snapsynapse/obligation-first/blob/main/examples/colorado-sb24-205/README.md

### Utah OAIP JIA — joint interpretation

Tests: PubLedge round-trip with exact source text and a JSON-LD multi-type contractual Term (`of:Term` plus `gist:ContractTerm`).

Source: https://github.com/snapsynapse/obligation-first/blob/main/examples/publedge-jia-utah-72/README.md

### EU AI Act Article 50 — source-hierarchy collapse

Tests: Regulation + interpretive Guidelines Instruments, article-vs-recital distinction, Terms that create Obligations vs Terms anchored to for interpretation only. Collapses a multi-layer EU source hierarchy (regulation, recital, guideline, code of practice) into uniform Terms and Obligations.

Source: https://github.com/snapsynapse/obligation-first/blob/main/examples/eu-ai-act-article-50/README.md

## Crosswalks

- gist (Semantic Arts): https://github.com/snapsynapse/obligation-first/blob/main/reference/crosswalks/gist.md
- LegalRuleML 1.0: https://github.com/snapsynapse/obligation-first/blob/main/reference/crosswalks/legalruleml.md
- Akoma Ntoso (OASIS LegalDocML): https://github.com/snapsynapse/obligation-first/blob/main/reference/crosswalks/akomantoso.md
- ELI / ECLI: https://github.com/snapsynapse/obligation-first/blob/main/reference/crosswalks/eli-ecli.md

## Adopters

- EveryAILaw — https://everyailaw.com/ (AI laws and obligations) — live binding for statutory and regulatory obligations
- PubLedge — https://publedge.org/ (joint interpretations) — live binding for instruments, terms, obligations, and determinations
- AI Incident Law — https://aiincidentlaw.org/ (AI-related cases) — live binding for proceedings, allegations, determinations, and authorities

All three projects publish v0.6 bindings: EveryAILaw publishes statutory duties and categories, PubLedge publishes negotiated and administrative-issuance records, and AI Incident Law publishes proceedings and adjudicative determinations. The combined graph passes the released federation contract.

## Adoption — three steps

1. Reference the canonical @context: set `@context: "https://obligationfirst.org/v1/context.jsonld"` on every record.
2. Validate record shapes and the graph contract. Publish a `.well-known` naming profile and use `obligation-first >=0.6.0 <0.7.0` when the projection emits v0.6 vocabulary.
3. Cite obligationfirst.org as the canonical reference.

## Assistant-assisted setup

For assistant-assisted repository work, use the GuideCheck artifact at `https://obligationfirst.org/.well-known/assistant-guide.txt`.

Required ceremony:
1. Fetch the guide without credentials.
2. Verify it with https://guidecheck.org/verify or another conformant verifier.
3. Report verifier name and version, achieved level, guide SHA-256, blocking findings, and warnings.
4. Ask the user to confirm they have read the guide and approve proceeding under the reported level.
5. Do not execute actions before confirmation.

The Level 4 manifest is at `https://obligationfirst.org/.well-known/assistant-guide-manifest.txt`. It pins the guide SHA-256 and byte count and uses the public repository copy at `assistant-guide.txt` as the repository-file anchor. This is a provenance check, not a safety claim.

## Endpoints

- @context: https://obligationfirst.org/v1/context.jsonld
- Shared definitions schema: https://obligationfirst.org/v1/schema/common.schema.json
- Authority schema: https://obligationfirst.org/v1/schema/authority.schema.json
- Jurisdiction schema: https://obligationfirst.org/v1/schema/jurisdiction.schema.json
- Party schema: https://obligationfirst.org/v1/schema/party.schema.json
- Instrument schema: https://obligationfirst.org/v1/schema/instrument.schema.json
- Term schema: https://obligationfirst.org/v1/schema/term.schema.json
- Obligation schema: https://obligationfirst.org/v1/schema/obligation.schema.json
- Obligation category schema: https://obligationfirst.org/v1/schema/obligation-category.schema.json
- Proceeding schema: https://obligationfirst.org/v1/schema/proceeding.schema.json
- Allegation schema: https://obligationfirst.org/v1/schema/allegation.schema.json
- Determination schema: https://obligationfirst.org/v1/schema/determination.schema.json
- Tombstone schema: https://obligationfirst.org/v1/schema/tombstone.schema.json
- ExecutableEncoding schema: https://obligationfirst.org/v1/schema/executable-encoding.schema.json
- Naming profile schema: https://obligationfirst.org/v1/schema/naming-profile.schema.json
<!-- of-version: llms-full-release-url -->
- Release package: https://obligationfirst.org/releases/v0.6.3/
- Assistant guide: https://obligationfirst.org/.well-known/assistant-guide.txt
- Assistant guide manifest: https://obligationfirst.org/.well-known/assistant-guide-manifest.txt
- Sitemap: https://obligationfirst.org/sitemap.xml
- Atom feed: https://obligationfirst.org/feed.xml
- Agent capabilities: https://obligationfirst.org/agents.json

## License

- Spec text and reference material: CC BY 4.0
- Code, schemas, scripts, examples: Apache 2.0

## Repo

https://github.com/snapsynapse/obligation-first

## Contact

- Author: Sam Rogers — https://www.linkedin.com/in/samrogers
- Publisher: PAICE.work PBC — https://paice.foundation/