Skip to content

PROTOCOL.md

Latest commit

 

History

History
232 lines (164 loc) · 12.1 KB

PROTOCOL.md

File metadata and controls

232 lines (164 loc) · 12.1 KB
Raw
@type https://w3id.org/semanticarts/ns/ontology/gist/Specification
title PubLedge Protocol
version 0.1.1-pre
license CC-BY-4.0
created 2026-04-18
modified 2026-04-18

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:

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 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: {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: 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: {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 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:

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 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: {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:

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 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 — 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