---
"@type": "https://w3id.org/semanticarts/ns/ontology/gist/Specification"
title: "PubLedge Protocol"
version: "0.2.0"
license: "CC-BY-4.0"
created: 2026-04-18
modified: 2026-08-04
---

# 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](https://semanticarts.com/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:

| Role | Name | gist class | What it is |
|---|---|---|---|
| Authority | Authority | `gist:GovernmentOrganization` | The party with interpretive or regulatory authority (Utah OAIP, SEC, IRS, CFPB; or, for civic uses, an HOA board, co-op council, etc.) |
| Container | Instrument | `gist:Agreement` (JIA) or `gist:Contract` (RMA, enforceable) | The interpretation record itself |
| Secondary | Term | `gist:ContractTerm` | An individual clause within an instrument |
| Primary | Obligation | `gist:Requirement` / `gist:Restriction` / `gist:Permission` | The behavior the instrument requires, prohibits, or permits |

The Obligation-First binding represents evidenced issuance as an administrative `of:Determination`. This separates the artifact from the authoritative act that created or published it. An issuance determination targets the instrument, decides no allegation, and is not a substitute for the adjudicative determinations published by AI Incident Law. Proposed or draft instruments do not receive an issuance determination until an official source and issuance date establish that the act occurred.

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

```yaml
"@type": "https://w3id.org/semanticarts/ns/ontology/gist/Agreement"  # or Contract
id: {jurisdiction}-{authority}-{kind}-{seq}  # Permanent identifier, lowercase; seq native where available else zero-padded, scoped to jurisdiction+kind
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: proposed | enacted | enforcing | phased-enforcement | pending-replacement | expired | superseded | withdrawn | terminated
editorial_status: draft | reviewed | published
disclaimer: "Default text or instrument-specific override"
created: YYYY-MM-DD
modified: YYYY-MM-DD
```

RMAs additionally require:

```yaml
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**: `{jurisdiction}-{authority}-{kind}-{seq}`, all lowercase. `jurisdiction` is the ISO-style code (e.g. `us` for federal, `us-ut` for Utah). `authority` is the kebab-case authority slug (e.g. `oaip`, `sec`, `cfpb`, `irs`, `cftc`). `kind` is one of `jia`, `rma`, `nal` (no-action letter), `plr` (private letter ruling), `ao` (advisory opinion), `il` (interpretive letter), `tpl` (template). `seq` is the native document number where the authority provides one (e.g. `plr-202506001`, `il-17-65`); otherwise a zero-padded sequential number scoped to `{jurisdiction, kind}` ordered by effective date (e.g. `rma-0001`). IDs are permanent, never reused, and survive 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](https://everyailaw.com/) 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:

```bash
./scripts/validate-hashes.sh
```

After intentional edits:

```bash
./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](https://skillprovenance.dev). PubLedge does not adopt the full skill-provenance protocol — only the integrity pattern.

## Discoverability

Every PubLedge site exposes the following at the root:

| File | Purpose |
|---|---|
| `/sitemap.xml` | All canonical URLs |
| `/feed.xml` | RSS — registry updates and protocol changelog |
| `/agents.json` | Agent discovery + MCP endpoint pointer |
| `/llms.txt` | Concise index for LLM consumption |
| `/robots.txt` | Crawl directives (allow all by default) |
| `/schema/json/` | JSON Schemas + JSON-LD context |

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 composed from `source` and legal `status`, independently of `editorial_status`. A published demonstration remap remains non-authoritative, and a PubLedge-original draft remains suggested prior art unless authority sign-off changes `source` to `authority-issued`.

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: {prior-id}` in frontmatter.
2. The old instrument has its `status` set to `superseded` and gains `superseded_by: {new-id}`.
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.

## Authority response

PubLedge is operator-agnostic. The authority that issued or enforces an instrument is never the operator of the registry. The protocol nonetheless gives that authority a first-class, low-friction way to respond to or correct any record about its own instrument, without operating, hosting, or maintaining anything.

Three mechanisms, lowest friction first:

1. Open a GitHub issue or pull request against the record. Standard git. No PubLedge account.
2. Point to the authority's own published statement. The record gains an `authority_response` entry whose `source` is the authority's URL; PubLedge quotes, it does not paraphrase.
3. Supply a signed statement recorded directly in the record's frontmatter under `authority_response`.

The `authority_response` field is an optional list. Each entry:

```yaml
authority_response:
  - from: utah-oaip            # authority slug or name
    date: 2026-05-18           # ISO date
    position: clarifies        # see DEFINITIONS.md → Authority response positions
    statement: >
      The Office's view is that ... .
    source: https://...        # optional: the authority's own published statement
    signature: pgp:0xABCD1234  # optional: detached-signature or PGP fingerprint reference
```

Rendering rules:

1. An authority response is rendered prominently on the record page, above the body, visually distinct from the `disclaimer`.
2. A response never deletes or edits the original interpretation. It annotates it. This follows the same never-delete-only-annotate rule as Supersession.
3. Multiple responses are kept in chronological order. None is removed when a later one is added.

Non-goals, stated so the posture is unambiguous:

- This is not sign-off-as-a-service. PubLedge does not solicit responses and does not gate publication on them.
- Absence of a response means nothing. It is not implied consent, dispute, or endorsement.
- The authority controls its own words. Where `source` is present, the authority's published text governs; the in-record `statement` is a convenience copy.

This section reinforces, rather than softens, "Not a regulator": PubLedge gives the regulator a microphone, not a console.

## 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](vendor/gist/) 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.md](PRIOR-ART.md) — survey of analogous instruments PubLedge draws from
- `_workshop/TAXONOMY.md` — site ontology and bucket definitions
- `_workshop/CONTENT-GUIDE.md` — full per-content-type frontmatter and rendering conventions
- `vendor/gist/` — pinned upper ontology snapshot