Developer Guide
This guide is for developers building MDA-aware tools — validators, loaders, harnesses, graph indexers, signing pipelines. It’s a practical orientation, not a replacement for the spec. Required reading first.- §02 Frontmatter — open-standard floor + MDA-extended fields under
metadata.mda.*. The §02-1.1 frontmatter-extraction algorithm is normative. - §07 Conformance — Levels V (validator) and C (compiler). Cross-field check:
signatures[].payload-digest == integrity.digest. - §08 Integrity — JCS canonicalization, multi-file boundary literal, self-describing
<algorithm>:<hex>digest format. - §09 Signatures — DSSE PAE envelope, Sigstore default,
did:webair-gap fallback. Rekor entry type pinned todsse-v0.0.1. - §11 Implementer’s Guide — informative loader pseudocode and error-vocabulary.
- §12 Sigstore tooling — informative mapping from
sigstore-python/sigstore-goto MDAsignatures[].
apps/cli/ (TypeScript, npm @markdown-ai/cli). Architecture and module layout are documented in apps/cli/IMPL-SPEC.md.
Pipeline at a glance
A consumer or validator runs five steps on every artifact:- Frontmatter extraction. Per §02-1.1: strip optional UTF-8 BOM, normalize CRLF→LF, find the opening
---, find the closing---on its own line (not as a horizontal rule inside the body), parse the YAML 1.2 between them. Empty body and body-only files are explicit cases. - Schema validation. The target schema is selected by the filename literal —
SKILL.md,AGENTS.md,MCP-SERVER.md, orCLAUDE.md. JSON Schema 2020-12 withunevaluatedProperties: false. Unknown top-level fields fail fast. - Cross-field semantic checks. The conformance runner enforces
signatures[].payload-digest == integrity.digestbyte-for-byte and the §02-1.1 edge cases. - Integrity rederivation (if signed). JCS-canonicalize the canonical bytes (with multi-file boundary literal for skills bundling scripts/references/assets), hash, compare to declared
integrity.digest. - Signature verification (if signed and policy-wired). Verify the DSSE PAE envelope. For Sigstore signatures: look up Rekor inclusion, verify the Fulcio certificate chain and signature, then apply the operator trust policy. For
did:web: match the signer domain against policy before fetchingmda-keys.json, then verify the signature against the listed keys.
TypeScript: minimal validator
Validator skeleton — extract frontmatter, pick the target schema, validate, perform the cross-field check.Python: minimal validator
Computing integrity
Theintegrity.digest is a hash over the JCS-canonicalized canonical bytes of the artifact. JCS (RFC 8785) is a deterministic JSON serialization that produces byte-identical output for semantically equal JSON. The §08 algorithm:
- Build the canonical JSON view of the artifact:
{ "frontmatter": <parsed YAML as JSON>, "body": <body string> }. - For multi-file artifacts (skills bundling scripts, references, assets), include each file as
{ "path": <relative path>, "content": <bytes-as-base64> }entries with the multi-file boundary literal documented in §08-3. - JCS-canonicalize the resulting JSON.
- Hash with the declared algorithm. The digest is
<algorithm>:<hex>, e.g.sha256:7f3c8e2b.... - Compare byte-for-byte to the
integrity.digestdeclared in frontmatter.
<algorithm>:<hex> is used in signatures[].payload-digest and depends-on.digest.
Verifying Sigstore signatures
For each entry insignatures[] where signer starts with sigstore-oidc: (§09-4.2):
- Confirm
payload-digest == integrity.digest. The conformance runner enforces this; a verifier should rely on it explicitly, not inherit it from upstream validation. - Look up the entry in Rekor by
rekor-log-idandrekor-log-index. Verify inclusion against the log root. - Verify the Fulcio certificate chain to the Sigstore root of trust.
- Verify the DSSE PAE envelope signature with the leaf certificate public key.
- Apply the operator trust policy to the issuer and subject.
@markdown-ai/cli and the verifier helpers in apps/cli/ glue a JCS helper and DSSE-capable signing/verification helpers. For the create-sign-verify guide with standard hashing and DSSE-capable signing tools, see docs/create-sign-verify-mda.md.
Conformance suite
The fixtures atconformance/manifest.yaml bind spec rules to positive and negative fixtures. Run them locally:
Vendor namespaces
Per-vendor configuration goes undermetadata.<vendor>.*. Loaders read only their own namespace. Consumers MUST NOT reject a document solely because it carries an unregistered kebab-case namespace (§04-5.1). The registry of assigned namespaces, standard requires keys, reserved Sigstore OIDC issuers, and reserved DSSE payload-type values lives at REGISTRY.md.
What v1.0 doesn’t ship
The contract is locked. The consumer-side ecosystem that enforces or routes through it is mostly nascent — no bundled verifier, no shipped resolver, no graph indexer, no shipped harness routing throughmetadata.mda.requires. For the truthful gap, see What v1.0 doesn’t ship. The contract that lets those consumer-side pieces be built without further negotiation is what v1.0 freezes.
Next
- Specification — entry point with every §.
- Create, sign, and verify MDA — hand-author and sign without the reference CLI.
- Reference implementation — TypeScript CLI source.
- IMPL-SPEC — reference-implementation architecture.