Open Publication Protocol v0.3.1

Source: spec-publication-protocol/index.md

Open Publication Protocol v0.3.1

Status

Draft

Overview

Open Publication Protocol v0.3.1 defines a minimal interoperable publication surface for versioned published documents hosted on a public publication site such as pubs.ilowe.me.

The primary goal of this protocol is to let software agents discover, resolve, and retrieve published documents reliably. In practice, this means a host exposes a stable public surface that an agent can crawl from the root listing, identify a document family by URN, and retrieve an exact immutable published version.

This protocol is intended to support Spec Driven Development (SDD) workflows. In an SDD workflow, specifications are treated as a primary source of truth and agents consume them as executable or near-executable constraints rather than as informal background reading.

This version specifies:

This version does not specify:

Motivation

Agentic systems need more than human-friendly documentation. They need discoverable, stable, machine-addressable publication surfaces with predictable versioning behavior.

Without that publication layer, an agent can read the wrong revision, fail to locate the canonical copy of a document, or rely on a moving alias where a pinned version is required.

This protocol therefore focuses on a narrow goal: make published documents easy for agents to discover from a single host root and safe to retrieve using stable canonical URLs and stable publication URNs.

Relationship to Open Publication URNs

This specification depends on Open Publication URNs for the definition of:

This specification defines how a publication host exposes those identifiers over HTTP. It does not redefine the urn:pub: identifier model.

Namespace authority and claim lifecycle are defined separately by Open Publication Namespace Claims.

Terminology

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals.

Concepts

Published Document

A published document is a human-readable artifact exposed by a publication host.

Examples include:

This protocol uses "document" as the generic publication unit. A host MAY classify documents further using metadata such as kind.

Publication Host

A publication host is the public HTTP origin that serves published documents, family indexes, listings, and related artifacts.

Examples include:

Source-of-Truth Repository

A publication host is backed by a single Git repository that acts as the source of truth for all published documents on that host.

This protocol does not require a specific forge or branching model.

Source of Truth

For a given host H, there MUST be exactly one authoritative source-of-truth Git repository R.

R is authoritative for:

Published content served from H MUST be derived from R.

This protocol does not require a specific publication workflow, but it does require that publication outputs be reproducible from repository state chosen by the host operator.

Publication Model

Given a host H, a namespace NS, a document family name N, and a version V, the host publishes a document version through a set of related resources.

For each published family, the host MUST expose:

For each published version, the host MUST expose:

For the host as a whole, the host MUST expose:

This version does not require a distinct machine-only version URL because the version URN already provides the canonical machine identifier.

Required URL Layout

Root Listing

The host root MUST provide a listing of published document families:

The listing MUST include enough information for a client or human to discover:

The root listing is the primary discovery entrypoint for agents.

Latest Human-Readable Alias

Each published family MUST expose a latest human-readable alias:

Example:

This resource is a moving alias for the latest published version of the family.

Canonical Human-Readable Version URL

Each published version MUST have a canonical human-readable URL:

Example:

This resource is intended for human readers and agent retrieval.

Family Index URL

Each published family MUST expose a family index:

Example:

The family index lists the published versions known for that family.

Canonicality Rules

Latest Resolution

For each published family, the host MUST determine one latest published version.

If all versions in the family follow semantic versioning, the host SHOULD determine latest by semantic version precedence.

If the family uses a different version style, the host MUST use one deterministic rule and MUST apply that rule consistently across:

The latest alias at https://H/NS/N/ MUST resolve to the same published version advertised as latest elsewhere on the host.

HTTP Semantics

This protocol defines minimum observable HTTP behavior for interoperable hosts.

Success

Redirects

Missing Resources

Content Types

Listing Requirements

The root listing MAY be rendered in any human-readable or machine-readable form, but it MUST preserve the same semantic information.

At minimum, each listed published version MUST expose:

Additional metadata MAY be included, such as:

If a host exposes both a human-oriented listing page and a machine-readable manifest, the two representations MUST agree on canonical URLs and URNs for the same published versions.

Machine-Readable Manifest

A host MAY expose a machine-readable manifest in addition to the root listing.

If a machine-readable manifest is exposed, it SHOULD be stable at a well-known path such as:

At minimum, each manifest record MUST expose the same fields required by the listing requirements section.

This version does not require a particular manifest schema beyond the minimum record fields defined above.

Optional Artifact Metadata

This protocol treats published content generically as documents. A host MAY add document metadata to help agents choose the right artifact.

Useful optional metadata includes:

Examples of kind values include:

Host Invariants

A conforming host MUST satisfy all of the following invariants:

Relationship to Spec Driven Development

This protocol does not define Spec Driven Development itself. Instead, it defines one publication substrate that makes SDD artifacts portable across agents, hosts, and repositories.

In an SDD workflow, an agent typically needs to answer questions such as:

This protocol standardizes those lookup steps so agents do not need host-local scraping rules or out-of-band knowledge.

References

The rationale for this protocol aligns with recent writing on Spec Driven Development and agent-oriented specification workflows:

These references are informative, not normative.

Example

For host pubs.ilowe.me, namespace ilowe, family name spec-publication-protocol, and version 0.3.0:

Example Listing Record

{
  "family_urn": "urn:pub:ilowe:spec-publication-protocol",
  "version_urn": "urn:pub:ilowe:spec-publication-protocol:0.3.0",
  "namespace": "ilowe",
  "name": "spec-publication-protocol",
  "version": "0.3.0",
  "kind": "spec",
  "latest_url": "https://pubs.ilowe.me/ilowe/spec-publication-protocol/",
  "human_url": "https://pubs.ilowe.me/ilowe/spec-publication-protocol/0.3.0/",
  "family_index_url": "https://pubs.ilowe.me/ilowe/spec-publication-protocol/versions/"
}

Open Questions