---
cuppy_hub: cuppy
cuppy_path: reference/standard/open-standard.md
cuppy_section: docs
cuppy_doc: AH15-2490
cuppy_doc_uuid: 5712f216-f864-4aef-80d6-c20ee13066ea
cuppy_permalink: https://cuppy.io/cuppy/d/AH15-2490
cuppy_version: 1
cuppy_updated: 2026-10-17T06:32:45.511Z
cuppy_canonical: https://cuppy.io/cuppy/docs/reference/standard/open-standard
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: 5d07b84b9dcc672899f2144c69d94268484607b5355db18806e14b12b143d5cc
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---

# The open standard: three artifact specs

The leverage in a documentation platform is not its API. It is being the format other
tools emit and consume. So what is offered as an open standard here is the **artifacts**
— three of them, smallest first — and not the product.

This document is the outline of that standard as the specification decides it (D99,
revision 24, with the program in Q3). The schemas themselves live in their own
repositories, generated from the product's own type sources; this is the map of what
they cover, what conformance means, and what an implementation that is not cuppy has to
do.

**A correction a reader coming from an older brief needs.** The three specs are
`cuppy-document`, `cuppy-signal` and `cuppy-known-issues`. They are **not** the hub
layout, the document contract and the MCP surface: the command registry and the
settings registry are the product and are versioned with it, and the hub skeleton
beyond `_boot/` and the folder card is a convention others may match rather than a
standard. The reason is given below, because it is the most common thing to get wrong
about this program.

## 1. The three specs

| spec | the core object | extensions | producers | consumers |
|---|---|---|---|---|
| `cuppy-document` | the front matter: role, shape, short id, summary, covers, facets, depends_on, freshness, source | the six shape blocks, and `x-<vendor>` namespaced blocks | any docs-as-code repository, a control plane pushing release documents, a system pushing entity dossiers | any agent, any hub, and search engines through the raw document URL |
| `cuppy-signal` | a learning event: a retrieval, an outcome, an attempt, a note or a gap, with its kind, its points, its half-life and its context | custom kinds in a namespace | an agent client, a continuous-integration job, a hub | a hub, a reranker, an analytics store |
| `cuppy-known-issues` | the feed: a signature, what it means, the fixes, what it was fixed in, and whether the message misleads | vendor blocks | a hub, a vendor's continuous integration | an agent's error envelope, a dashboard |

Why those three and in that order. `cuppy-document` is the one artifact two parties
already want to exchange: a repository that writes front matter and a hub that serves
it. `cuppy-signal` is the one artifact that makes a hub improve rather than merely
store, and it is worth standardising precisely because the events come from clients
nobody controls. `cuppy-known-issues` is the smallest useful public feed a vendor can
publish, and the one with an obvious consumer that is not a hub at all.

## 2. What is normative, and what is informative

**Normative** — an implementation that does not do these is not conforming:

- The **field set and types** of each core object, as the published schema states them.
- The **closed vocabularies**: the five roles, the seven shapes, the four freshness
  tiers (`probed`, `sourced`, `crawled`, `asserted`) and the status values.
- The **freshness floor**: an authored write stores `asserted`; only an executed
  attempt or a vendor artifact may raise a tier, and a verifier field is written by the
  platform and never by an author.
- The **extension rule**: an extension block is namespaced `x-<vendor>` and carries its
  own schema URL. An implementation validates a namespaced block it knows, **ignores**
  one it does not, and **refuses** an unknown block that is not namespaced.
- The **pointer rule**: a stored reference between documents is an id, never a path.
- The **deprecation rule**: a field is deprecated for one minor version before it is
  removed.

**Informative** — described so an implementation can interoperate, not required:

- The **folder spine** beyond `_boot/` and the folder card. Others may match it; it is
  a convention, and `reference/standard/hub-standard.md` is where it is written down.
- The **three depth rungs** and their names. The rungs are how cuppy serves a document;
  a conforming producer does not have to have depths at all.
- The **retrieval design**: the four stages, the fusion constant, the learned re-rank.
  All product.
- The **boot document's** sections and budgets. A hub that has no boot document can
  still emit conforming documents.

**Explicitly not standardised**, and this is the half that keeps the standard small:
the command registry, which is cuppy's API; the settings registry; and the hub skeleton
beyond the two names above. Standardising the product would be standardising one
implementation's shape, which is the failure mode the program is designed to avoid.

## 3. How the standard versions itself

Three rules, and the specs are useless without them.

1. **Every schema carries a `$id` URL with a semantic version**, and the schema is
   **generated** from the product's own type sources rather than written twice. A drift
   between the generated schema and the schema committed in the spec repository is a
   build failure, not a discovery made later by a reader.
2. **An extension is namespaced and versioned on its own.** A vendor adds a block
   without colliding with anyone and without forking the core.
3. **A field is deprecated for one minor version before removal**, so a producer has a
   release in which both spellings validate.

Added to those, two program rules from Q3: the specification changes only through its
repository with a versioned changelog, and the platform never ships a format change the
specification does not already describe. The second one is the expensive one to keep and
the only one that makes the standard credible.

## 4. How a product other than cuppy implements it

A conforming **producer** has to do four things.

1. **Emit front matter that validates** against `cuppy-document`: the common fields, the
   right shape block when the body is not plain markdown, no path in a pointer field,
   and `asserted` freshness on anything it authored itself.
2. **Keep its own identifiers out of the id field.** A short id is minted by the hub
   that stores the document. A producer that has its own identifier carries it in a
   namespaced extension block, not in `short_id`.
3. **Declare its extensions** under `x-<vendor>` with a schema URL, so a consumer that
   does not know the vendor still round-trips the document unchanged.
4. **Emit signals for what it observes, not for what it believes.** A retrieval, an
   outcome and an attempt are events; a claim that a document is good is not one.

A conforming **consumer** has to do three.

1. **Validate what it knows and ignore what it does not.** An unknown namespaced block
   is data to be preserved, not an error.
2. **Round-trip unchanged.** A document read and written back carries every block it
   arrived with, including the ones the consumer could not interpret.
3. **Respect the freshness floor.** A consumer that re-serves a document may not
   promote its tier.

Conformance is meant to be mechanical: a fixture set per shape, plus a validator
command line (`cuppy validate`) that accepts every fixture and refuses a document
carrying an unknown non-namespaced block. **Neither exists in this tree yet** — the
software development kit and its validator are Phase 4 and 5 work, and nothing under
`apps/` or `packages/` implements either, read by searching the tree at the base commit
in this document's front matter. Treat the conformance kit as a proposal with a
specified shape, not as something you can run today.

## 5. The honest position, and the bar for governance

The bar the program sets itself is **a second producer**, and it is not met. Stated
plainly, against the case study in
`tracking/roadmap/research/2026-10-12-open-standard-positioning.md`:

| what a standard needs | where this one is |
|---|---|
| a core schema, versioned, outside the product | the core schema exists, is unversioned, and lives inside the product |
| an extension mechanism | present, and hub-only |
| more than one producer and consumer | one of each |
| a conformance kit | tests inside the product, not a kit |
| governance beyond one party | one owner |

Two moves are cheap and are the next ones: the schema repository with versioned ids,
which is one generation script over type sources that already exist; and the conformance
kit, which is packaging fixtures that already exist. Everything after that waits on a
producer nobody here controls. The two candidates available inside this build are a
control plane publishing its release documents through a publisher credential, and a
go-to-market system emitting entity dossiers the same way.

**Donation to a foundation is considered only after two outside producers exist.** That
is a deliberate order: a standard donated before it has users is a document with a
governance process attached, and the case study is the reason the order is written down
rather than left to judgement.

## 6. What a reader should take from this document

If you are writing documents: write to `cuppy-document`, which in practice means
writing to the front-matter contract in `reference/standard/hub-standard.md`. That is
the whole of conformance for an author.

If you are building a tool that reads or writes hubs: the four producer rules and the
three consumer rules above are the contract, and the extension rule is the one that
decides whether your tool and someone else's can hold the same document without
destroying each other's fields.

If you are deciding whether to depend on this standard: read section 5 first. One
producer, one consumer and one owner is where it stands, and it is stated here rather
than discovered later.

## Next reads

- `reference/standard/hub-standard.md` — the spine and the front-matter contract the
  document spec is drawn from.
- `guides/sdk-and-transport.md` — the client libraries and the two protocol eras, and
  what is built versus specified.
- `guides/skill-packs.md` — what a hub compiles out of its documents, and the manifest
  that makes a silent run auditable.
- `reference/cuppy/tool-naming-standard.md` — the naming rules on the product side of
  the line this document draws.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 18 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/cuppy/
<!-- /cuppy -->