Use the registry

Read without authentication. Publish using an instantly issued pseudonymous token. Every successful publication is public and permanent.

Base URL: https://speccommons.org

Retrieve

• GET /api/definitions?limit=25&offset=0 — JSON object with items (complete records) and next_offset (integer or null). Limit 1–50; offset 0–10,000.
• GET /s/{slug} — the permanent readable definition.
• GET /s/{slug}.json — the complete definition record.
• GET /s/{slug}.md — the definition's Markdown content.
• GET /api/definitions/{slug} — the same JSON record.
• GET /api/definitions/{slug}/derivatives?limit=25&offset=0 — direct derivatives as complete records, using the same pagination.
• GET /s/definition-record-2/schema.json — the published record's JSON Schema.

JSON and Markdown representations supply a canonical Link header. JSON responses allow cross-origin reading. Save the complete JSON record to retain its metadata and content independently.

Publish

Draft and review the definition in your own files. Check its title, slug, rules, invalid cases and examples. An unfamiliar implementer should need only the resulting URL.

1. Obtain a publisher token

curl -X POST https://speccommons.org/api/publishers \
  -H 'Content-Type: application/json' -d '{}'

The response is { "publisher": "pub_…", "token": "sc_token_…" }. Store the secret token securely; it is returned once. The publisher identifier is public and pseudonymous. No name, email or registration is required. Reuse the same token to associate your publications. Lost tokens cannot be recovered; published definitions remain accessible.

2. Prepare a JSON file

{
  "slug": "example-convention",
  "title": "Example convention",
  "summary": "The exact convention our application expects integrators to follow.",
  "content": "## Rules\n\nWrite the complete definition here, including valid and invalid examples.",
  "references": ["https://speccommons.org/s/compact-utc"]
}

Replace the example text with a real definition. Slugs use lowercase ASCII letters and digits separated by single hyphens, 3–80 characters. Titles are 3–120 characters, summaries 10–300, and content 40–60,000. The body limit is 70,000 UTF-8 bytes. Unknown fields are rejected. No title, slug or body can change after publication.

3. Publish

curl -X POST https://speccommons.org/api/definitions \
  -H "Authorization: Bearer $SPEC_COMMONS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @definition.json

A new publication returns HTTP 201, its complete record and a Location header. The identifier, publisher and canonical compact UTC timestamp are assigned by the service. An exact retry with the same publisher, slug and payload returns the existing record with HTTP 200. A conflicting slug returns 409. Do not pick a different slug automatically after an uncertain request: retrieve the original first.

Create a derivative

Retrieve the parent's JSON record, then prepare a new complete definition with a fresh slug. Add the exact parent URL and a short explanation of the differences:

{
  "slug": "example-convention-extended",
  "title": "Extended example convention",
  "summary": "A complete standalone alternative for a different application requirement.",
  "content": "## Rules\n\nInclude the entire revised definition here, rather than a patch.",
  "parent": "https://speccommons.org/s/example-convention",
  "change_note": "Explain exactly what changed and why this alternative is useful.",
  "references": []
}

Publish it through the same endpoint. Any publisher can derive from an existing definition. The parent must exist in this registry. Ancestry records a relationship, without implying approval or improvement. The original stays unchanged.

Errors and limits

Errors are JSON: { "error": "code", "message": "Explanation" }.

Publisher creation is limited to 3 requests per minute per IP. Publication is limited to 10 requests per minute per IP and publisher, with a maximum of 100 new definitions per publisher per UTC day. Limits may be tightened to keep this small service usable.

Revoke a token

DELETE /api/token with its Bearer token permanently revokes that token and returns HTTP 204. It does not alter published definitions. To publish again, obtain a new publisher identity. Token sharing and additional tokens can wait until a project needs them.