Obligation-First

A shared upper schema for normative content — laws, cases, and agreements — bound to the Semantic Arts gist upper ontology.

Obligation-First is a methodology and a JSON-LD context. The methodology says that normative content is best modeled by what it requires, not what it says. The schema gives that methodology a machine-readable shape.

Live at obligationfirst.org. Drafting in public. v0.1.0-draft. Subject to revision before the v0.1 freeze.

What this is

A small, opinionated upper schema with two parts:

1. The four-role spine — Authority, Instrument, Term, Obligation. Inherited from the Knowledge-as-Code pattern that PubLedge introduced. Bound to gist classes.
2. The proceeding strand — Proceeding, Allegation, Determination. New in Obligation-First. Models cases, enforcement actions, and rulings without forcing premature factual classification.

Together they cover three domains in one schema:

• Statutes and regulations — laws and the obligations they create (used by EveryAILaw)
• Proceedings and enforcement — cases, allegations, rulings (used by AI Incident Law)
• Joint interpretations — agreements between authorities and regulated parties (used by PubLedge)

Role in the PAICE legal graph

Obligation-First is the interstitial layer between the PAICE legal projects. It does not replace EveryAILaw, AI Incident Law, or PubLedge. It gives them a shared contract:

• EveryAILaw contributes statutory and regulatory Obligation records.
• AI Incident Law contributes Proceeding, Allegation, and Determination records that anchor back to those Obligations.
• PubLedge contributes joint-interpretation Instrument, Term, and Obligation records that clarify or re-allocate the same underlying Obligations.

The join surface is deliberately small: stable @id values, a shared @context, schema validation, and anchors for cross-project references.

Why obligation-first

Most legal data models center on the document. Obligation-First centers on what the document makes you do. The advantages compound:

• Cross-jurisdictional comparison becomes natural. Two laws with the same Obligation are commensurable even when their texts differ.
• Proceedings link cleanly to statutes. A Determination anchors to the Obligation it interprets, not the textual provision.
• Joint interpretations re-allocate Obligations between parties — exactly what JIAs and RMAs do.
• Rules-as-code engines plug in below the schema. A Provision can carry an executableEncoding reference to a Catala scope, a Blawx ruleset, or an OpenFisca formula without changing the schema.

Adopters

• EveryAILaw — AI law and obligation tracker, now publishing an Obligation-First binding for statutory and regulatory obligations.
• PubLedge — open recordkeeping protocol for joint interpretations, now publishing Obligation-First records for authorities, instruments, terms, obligations, and determinations.
• AI Incident Law — public-record corpus of AI-related cases, now publishing Obligation-First proceedings, allegations, determinations, and authorities.

If you'd like to bind your project to v0.1, see Quick start below or CONTRIBUTING.md.

Quick start — bind a dataset in three steps

1. Reference the canonical @context — set @context: "https://obligationfirst.org/v1/" on every record. Repo-local extensions go in a second context object.
2. Validate against the JSON Schemas — run every record through the schema for its @type (eight schemas at https://obligationfirst.org/v1/schema/). Schema-conformant adopters (Level 2) pass validation for every published record.
3. Cite obligationfirst.org as the canonical reference — adopter sites and documentation should link back. The IRI prefix is permanent.

To validate your own records locally:

git clone https://github.com/snapsynapse/obligation-first.git
cd obligation-first
npm install
npm run validate    # runs scripts/validate-examples.mjs

The validator walks examples/*/records/ and checks every JSON record against the appropriate schema. Adopters can drop their own records into a directory of the same shape and reuse the script.

Machine-readable endpoints

Every artifact an adopter or agent needs is dereferenceable at a stable URL:

Endpoint	Purpose
/v1/context.jsonld	The JSON-LD @context for v1
/v1/schema/*.schema.json	JSON Schemas — one per entity (eight total)
/v1/schema/authority.schema.json	Authority schema
/v1/schema/instrument.schema.json	Instrument schema
/v1/schema/term.schema.json	Term schema
/v1/schema/obligation.schema.json	Obligation schema
/v1/schema/proceeding.schema.json	Proceeding schema
/v1/schema/allegation.schema.json	Allegation schema
/v1/schema/determination.schema.json	Determination schema
/v1/schema/executable-encoding.schema.json	Executable encoding schema
/llms.txt, /llms-full.txt	LLM-readable summary + full context
/agents.json	Agent capabilities and endpoint inventory
/.well-known/assistant-guide.txt	GuideCheck Human-Verifiable Assistant Guide for assistant-assisted repo work
/feed.xml	Atom feed of releases
/sitemap.xml, /robots.txt	SEO + AI-crawler allow-list
/.well-known/security.txt	Security disclosure (RFC 9116)
/changelog.html	Changelog (redirects to GitHub CHANGELOG.md)

The IRI prefix https://obligationfirst.org/v1/ is the resolution target. Once v0.1 freezes, https://w3id.org/of/v1/ will be filed at w3id.org as the permanent canonical IRI.

Repository layout

Path	Purpose
PROTOCOL.md	The Obligation-First specification
PRIOR-ART.md	Survey of legal ontologies, deontic logic foundations, and rules-as-code projects
ROADMAP.md	Versioning plan, resolved-in-v0.1 table, deferred decisions
CHANGELOG.md	Material changes per version
schema/context.jsonld	The JSON-LD @context for v1 (canonical source — copied to docs/v1/ by CI)
schema/*.schema.json	JSON Schemas for each entity
scripts/validate-examples.mjs	Validation harness: every JSON record under examples/*/records/ is checked against the appropriate schema
scripts/lib/adopter-kit.mjs	Reusable adopter helper for schema validation, graph validation, and aggregate record bundles
scripts/validate-adopter-records.mjs	CLI validator for adopter record directories
scripts/report-anchor-graph.mjs	Cross-project anchors report for adopter exports and worked examples
vendor/gist/	Pinned snapshot of Semantic Arts gist (14.1.0)
reference/crosswalks/	Mappings to LegalRuleML, Akoma Ntoso, ELI/ECLI, gist
reference/adopter-kit.md	How adopters reuse the binding helper introduced after EveryAILaw
reference/review/	Public external review questions for v0.1 freeze
reference/w3id-pr.md	Prepared w3id.org permanent identifier PR notes
reference/og-image-prompt.md	Structured prompt for generating the OG social-card image
examples/{air-canada,colorado-sb24-205,publedge-jia-utah-72}/	Worked examples — three real record sets round-tripped through v0.1, with 23 canonical JSON record files under the records/ subdirectories
docs/	Published website served by GitHub Pages from main /docs (canonical at obligationfirst.org)
.github/workflows/	CI: validation on every push (test.yml), Pages deploy (pages.yml), monthly a11y audit (a11y.yml)
_workshop/	Design conversation archives

What this is not

• Not a replacement for Akoma Ntoso, LegalRuleML, or ELI. Obligation-First references those standards; it does not duplicate them.
• Not a rules engine. The schema points at executable encodings (Catala, Blawx, OpenFisca) but does not implement them.
• Not legal advice. The schema is descriptive, not prescriptive.
• Not an attempt to model all of law. Scoped to the three domains above.

Status

v0.1.0-draft. Spec, schemas, worked examples, adopter kit, and first three PAICE legal bindings are complete and live. Open items before v0.1 freeze:

• External review (Semantic Arts feedback on gist binding for Reparation; LegalRuleML community feedback on deontic alignment)
• File w3id.org PR for the permanent IRI

Current local stage: Obligation-First is operating as the validation and identifier contract between EveryAILaw, PubLedge, and AI Incident Law. The next useful work is external review, permanent IRI filing, and cross-project anchor enrichment.

For anchor enrichment, run npm run report:anchors against the worked examples or node scripts/report-anchor-graph.mjs <adopter-export> [...] against sibling adopter exports.

The IRI prefix https://obligationfirst.org/v1/ is the resolution target. https://w3id.org/of/v1/ is planned as the permanent canonical IRI once v0.1 freezes.

License

Spec text and reference material under CC BY 4.0. Code (schemas, scripts, examples) under Apache 2.0.

Exception: example records under examples/ that bear https://everyailaw.com/ identifiers are reproduced from the EveryAILaw corpus by express permission, solely as schema illustration. They are NOT licensed under Apache 2.0 or CC BY 4.0, and no rights in the EveryAILaw corpus are granted by this repository. See NOTICE and https://everyailaw.com/.

Stewarded by PAICE.work PBC. Transition to an independent steward (PAICE Foundation) is anticipated.