PubLedge Protocol

PubLedge is an open recordkeeping protocol for fact-specific written interpretations between two parties.

A PubLedge record captures a question, an answer, who agreed to it, what statutes or rules it relies on, and what the parties are now permitted, required, or restricted from doing as a result. Records are plain markdown with structured frontmatter. They are versioned in git, hash-pinned for integrity, and machine-readable through schemas bound to an open upper ontology.

What PubLedge is for

PubLedge generalizes a single class of artifact across many domains:

• Regulatory — Joint Interpretation Agreements (JIAs), Regulatory Mitigation Agreements (RMAs), no-action letters, private letter rulings, advisory opinions
• Civic — HOA decision logs, co-op governance records, flying-club asset agreements, tool-library lending records, community land-trust commitments
• Private — published private rulings between two parties (e.g., a vendor and a regulator) where one party wants the public to be able to read and rely on the interpretation

The civic and regulatory framings are different use cases of the same underlying artifact: a written interpretation, jointly authored or approved, that constrains future behavior between the parties and may be of interest to third parties.

Core principles

1. Human-readable, machine-verifiable — every record is markdown a person can read and JSON a machine can parse.
2. Plain text, no proprietary dependencies — git is the only required tool.
3. Open ontology — entities bind to Semantic Arts gist (CC-BY 4.0) for cross-system interoperability.
4. Hash-pinned integrity — every published record is hashed in MANIFEST.yaml; tampering is detectable.
5. Drafting-in-public posture — published records carry a disclaimer until reviewed and accepted by the relevant authority.

Entity model

PubLedge inherits the Knowledge-as-Code four-role spine and binds each role to a gist class:

The act of issuance is itself typed gist:Determination. This separates the artifact (the agreement) from the event (the act of agreeing).

The vocabulary mapping is published at /reference/vocabulary/ and bound machine-readably in /schema/json/context.jsonld.

Required structure

Every PubLedge instrument has YAML frontmatter and a markdown body.

Required frontmatter fields

"@type": "https://w3id.org/semanticarts/ns/ontology/gist/Agreement"  # or Contract
id: PL-JIA-NNNN                          # Permanent identifier, monotonic, never reused
slug: jurisdiction-topic-period          # Human-readable URL slug
title: "Plain-language title"
jurisdiction: us-ut                       # ISO-style jurisdiction code
issued_date: YYYY-MM-DD
issued_by:                                # The Authority
  "@type": "https://w3id.org/semanticarts/ns/ontology/gist/SubCountryGovernment"
  name: "..."
  ref: "..."                              # Authoritative URL
parties:
  - name: "..."
    role: requesting_party | interpreting_authority | counterparty
obligation_kind: [requirement, restriction, permission]   # any subset
statute_anchors:
  - cite: "Bluebook-style citation"
    url: "Canonical EveryAILaw anchor or authoritative source"
terms:
  - "@type": "https://w3id.org/semanticarts/ns/ontology/gist/ContractTerm"
    text: "Plain-language clause"
status: draft | reviewed | published | superseded
disclaimer: "Default text or instrument-specific override"
created: YYYY-MM-DD
modified: YYYY-MM-DD

RMAs additionally require:

enforcement_authority:
  name: "..."
term_length: "ISO-8601 duration or 'indefinite'"
review_date: YYYY-MM-DD

Recommended body structure

In order:

1. Summary — 2-3 sentences a non-specialist can read
2. Background — context for the requesting party and the question presented
3. Question(s) presented — what the parties asked
4. Interpretation — what the authority agreed
5. Terms — narrative form of the frontmatter terms[]
6. Statute citations — narrative form of statute_anchors[] with reasoning
7. Limitations — scope, exclusions, expiry triggers
8. Effective date and review trigger

The body is the canonical human-readable form. The frontmatter is the canonical machine-readable form. Both must agree; the validator (scripts/validate.js) enforces this.

Identifiers and slugs

• Permanent ID: PL-{KIND}-NNNN where KIND is JIA, RMA, NAL (no-action letter), PLR (private letter ruling), OPN (advisory opinion). Monotonic, never reused, survives slug renames.
• Slug: lowercase, hyphen-separated, jurisdiction prefix, topic descriptor, optional issuance period. Example: utah-mental-health-chatbot-disclosure-2026q2.
• Internal references between PubLedge entities use the permanent ID, resolved at build time.

Statute citations

Citations carry both a Bluebook-style cite and a url. The URL must be the most stable resolvable anchor available:

1. First preference: an Every AI Law provision anchor.
2. Second preference: the official jurisdictional source (e.g., le.utah.gov, sec.gov, irs.gov).
3. Never: a paywall, a PDF on a private mirror, or an unstable third-party summary.

Citation text is never duplicated into PubLedge — always linked out. PubLedge is the interpretation registry, not a statute mirror.

Integrity

Every published file referenced by MANIFEST.yaml is SHA-256 hashed. The manifest itself is the control file and is not self-hashed. Verification:

./scripts/validate-hashes.sh

After intentional edits:

./scripts/validate-hashes.sh --update

CI runs validate-hashes.sh on every push. A mismatch fails the build.

The hash mechanism is adapted from skill-provenance. PubLedge does not adopt the full skill-provenance protocol — only the integrity pattern.

Discoverability

Every PubLedge site exposes the following at the root:

These are the primary mechanisms by which AI agents and search engines discover PubLedge content without scraping HTML. They are mandatory.

Drafting in public

Every PubLedge instrument carries a disclaimer frontmatter field. The default text:

Suggested prior art. Not official output of any authority.

The disclaimer is rendered prominently in the page header until status: published is reached and the responsible authority has either signed off or expressly declined to do so. Records that move to published without authority sign-off must retain a softened disclaimer indicating that the interpretation is the requesting party's good-faith reading, not an official ruling.

This posture is non-optional. PubLedge exists in part to publish interpretations before an authority issues an official version, so that a public conversation has source material to work from.

Supersession

When an instrument is replaced:

1. The new instrument carries supersedes: PL-JIA-NNNN in frontmatter.
2. The old instrument has its status set to superseded and gains superseded_by: PL-JIA-NNNN+1.
3. Both remain in the registry; URLs do not break.
4. The old instrument's page renders a banner pointing to the new one.

This is mandatory. PubLedge never deletes, only supersedes. The historical record is part of the value.

License

PubLedge content (markdown, YAML, HTML) is licensed CC-BY 4.0. PubLedge code, schemas, and scripts are licensed Apache 2.0. See LICENSE, LICENSE-APACHE, LICENSE-CC-BY-4.0.

Bundled vendor snapshots retain their upstream licenses. The pinned gist core ontology is CC-BY 4.0 (Semantic Arts).

What PubLedge is not

• Not a regulator. PubLedge does not issue rulings.
• Not a law firm. PubLedge templates are prior art, not legal advice.
• Not a blockchain. The integrity layer is plain SHA-256 over plain files.
• Not a CMS. PubLedge ships a static site; editors edit markdown in git.
• Not a replacement for official channels. PubLedge complements official rulings; it does not pretend to substitute for them.

See also

• Prior Art — survey of analogous instruments PubLedge draws from
• Registry — published JIAs and RMAs
• Templates — fill-in JIA and RMA templates
• Vocabulary — gist binding map