Spec Commons definition record, revision 2

The registry record schema with Unicode character counting clarified. Used for new publications; earlier records keep their original schema.

Purpose

The complete, portable record returned by Spec Commons for one published technical definition. This definition is also used for its own record.

Meaning and permanence

Every record represents one immutable publication. Its id, URL, title, summary, content, publisher, timestamp, parent, change note and references are fixed at publication. A correction receives a new record and URL.

The canonical URL is https://speccommons.org/s/ followed by the slug. The slug is globally unique, consists of lowercase ASCII words or digits separated by single hyphens, and is never reassigned. The id is sc_ followed by 32 lowercase hexadecimal digits and is an opaque permanent identifier.

The schema field is exactly https://speccommons.org/s/definition-record-2. The JSON export is the canonical URL followed by .json. The Markdown export is that URL followed by .md and contains the content field only. The complete JSON record is the self-contained archival export; references identify other documents and do not embed them.

Fields

Field	Meaning
id	Permanent machine identifier.
url	Permanent canonical human-readable URL.
schema	This exact definition's URL.
slug	Permanent URL segment.
title	Descriptive title, 3–120 characters.
summary	Plain-text purpose, 10–300 characters.
content	Complete standalone Markdown definition, 40–60,000 characters. Raw HTML is displayed as text; only HTTP(S) and relative links are actionable.
publisher	Opaque pseudonymous publisher identifier: pub_ plus 32 lowercase hexadecimal digits. Continuity does not establish real-world authorship, identity or endorsement.
published_at	Canonical compact UTC instant at whole-second precision.
parent	Canonical URL of the single source publication, or null for an original. The parent must exist in this registry.
change_note	Explanation of differences, 10–1,000 characters when parent exists; otherwise null.
references	Zero to twenty distinct HTTPS URLs for explicit dependencies or related definitions. Each is at most 500 characters.

String lengths use Unicode code points, as specified by JSON Schema. Combining characters count separately; no Unicode normalisation is applied. The HTTP request limit is measured separately in UTF-8 bytes. All fields are required in a returned record. No additional fields are permitted. Parent and change_note are either both null or both non-null. A derivative contains its complete definition rather than a patch. Its parent records ancestry, not endorsement or a claim of superiority.

Machine validation

The JSON Schema below uses draft-07. Also check the calendar validity and shortest encoding of published_at using the compact UTC definition, url = the origin plus /s/ plus slug, and the parent/change_note condition above. Schema validation alone does not establish semantic correctness.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://speccommons.org/s/definition-record-2/schema.json",
  "title": "Spec Commons definition record",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "url",
    "schema",
    "slug",
    "title",
    "summary",
    "content",
    "publisher",
    "published_at",
    "parent",
    "change_note",
    "references"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^sc_[a-f0-9]{32}$"
    },
    "url": {
      "type": "string",
      "pattern": "^https://speccommons\\.org/s/[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "schema": {
      "const": "https://speccommons.org/s/definition-record-2"
    },
    "slug": {
      "type": "string",
      "minLength": 3,
      "maxLength": 80,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "title": {
      "type": "string",
      "minLength": 3,
      "maxLength": 120
    },
    "summary": {
      "type": "string",
      "minLength": 10,
      "maxLength": 300
    },
    "content": {
      "type": "string",
      "minLength": 40,
      "maxLength": 60000
    },
    "publisher": {
      "type": "string",
      "pattern": "^pub_[a-f0-9]{32}$"
    },
    "published_at": {
      "type": "string",
      "pattern": "^[0-9]{4}(?:[0-9]{2}){0,5}$",
      "description": "Canonical compact UTC; calendar validity and shortest encoding also required. See https://speccommons.org/s/compact-utc"
    },
    "parent": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^https://speccommons\\.org/s/[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "change_note": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 10,
      "maxLength": 1000
    },
    "references": {
      "type": "array",
      "maxItems": 20,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "maxLength": 500,
        "pattern": "^https://[^\\s]+$"
      }
    }
  }
}

The same embedded schema is retrievable at schema.json.

Publishing

Submit only slug, title, summary, content and optionally parent, change_note and references to POST /api/definitions. The service assigns the remaining fields. See the API instructions. Prepare and review drafts in your own files; submission publishes permanently and publicly.

Use exact published URLs when instructing another agent. A newer derivative never changes the interpretation of the original record.