{"id":19474828,"url":"https://github.com/speced/spec-dfn-contract","last_synced_at":"2026-06-15T19:31:45.691Z","repository":{"id":48930219,"uuid":"378829383","full_name":"speced/spec-dfn-contract","owner":"speced","description":"Contract for marking up definitions in specifications","archived":false,"fork":false,"pushed_at":"2026-03-23T19:38:09.000Z","size":12,"stargazers_count":4,"open_issues_count":15,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-24T17:49:17.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/speced.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-21T06:29:38.000Z","updated_at":"2026-03-23T19:38:14.000Z","dependencies_parsed_at":"2024-11-10T19:27:20.783Z","dependency_job_id":"79bce001-8b8a-4be7-85a0-66f644f122ba","html_url":"https://github.com/speced/spec-dfn-contract","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/speced/spec-dfn-contract","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speced%2Fspec-dfn-contract","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speced%2Fspec-dfn-contract/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speced%2Fspec-dfn-contract/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speced%2Fspec-dfn-contract/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/speced","download_url":"https://codeload.github.com/speced/spec-dfn-contract/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speced%2Fspec-dfn-contract/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34377872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T19:27:10.096Z","updated_at":"2026-06-15T19:31:45.686Z","avatar_url":"https://github.com/speced.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Definitions Contract\n\nThis document defines the Definitions Contract for technical specifications; known herein as _the contract_.\n\nThe contract standardizes the concept of \"definitions\" provided by certain elements (i.e., `\u003cdfn\u003e` or `h1`-`h6` elements) and the corresponding attributes and values that provide necessary metadata about them.\n\nSpecifications that conform to the contract can unambiguously cross-reference each other's definitions. This is done with the aid of a reference database, which can be built by processing definitions that conform to this document.\n\nA **definition** is composed of:\n* an ID\n* one or more linking texts\n* a type\n* optionally, one or more namespaces\n* optionally, an export specifier\n\n## Some examples\n\nA simple example of a definition:\n\n```HTML\n\u003cdfn id=\"simple-definition\" data-export=\"\" data-dfn-type=\"dfn\"\u003e\n  I'm a simple definition\n\u003c/dfn\u003e\n```\n\nA more complex example:\n\n```HTML\n\u003c!-- Example of defining an abstract operation --\u003e\n\u003cdfn\n  id=\"string-parser\"\n  data-export=\"\"\n  data-lt=\"parse a string\"\n  data-dfn-type=\"abstract-op\"\u003e\n  string parser\n\u003c/dfn\u003e\n\n\u003c!-- Example of defining a WebIDL interface --\u003e\n\u003cdfn\n  data-export=\"\"\n  data-dfn-type=\"interface\"\n  id=\"dom-paymentrequest\"\n  data-dfn-for=\"\"\u003e\n  \u003ccode\u003ePaymentRequest\u003c/code\u003e\n\u003c/dfn\u003e\n```\n\n## Conformance\n\nThis document serves as the canonical source for how definitions are marked-up (automatically by tools or manually by spec editors).\n\nConforming applications to this specification are primarily authoring tools that assist in generating/writing technical specifications.\nHowever, this specification is also here to help people who wish to mark up documents manually - or simply want to understand what various attributes mean and what they do!\n\nExample of authoring tools (or \"generators\") that try to conform to this specification:\n\n- [Bikeshed](http://github.com/speced/bikeshed)\n- [ReSpec](http://github.com/w3c/respec)\n- [Wattsi](https://github.com/whatwg/wattsi)\n\n\u003e [!NOTE]\n\u003e Users of spec-authoring tools like the above might have shorter or implicit ways to indicate some or all of the data required by the dfn contract;\n\u003e this document defines requirements on the output HTML *generated* by the tools.\n\nNote: An accompanying test suite helps assure authoring tools conform to the contract.\n\n## Who consumes these definitions\n\nAside from specifications internally cross-referencing their own terms and terms in other specifications, \"crawlers\" extract terms defined in specifications into structured data.\n\nExamples of definition crawlers include:\n\n- [Reffy](https://github.com/w3c/reffy)\n\nCrawlers structure and categorize extracted terms into files or databases, allowing for the creation of search tools such as:\n\n- \u003chttps://respec.org/xref\u003e\n- Bikeshed's cross-reference search (the `bikeshed refs` command)\n\n## How to get your spec indexed\n\nTo have your specification indexed by a crawler, it needs to be registered with:\n\n- [browser specs](https://github.com/w3c/browser-specs/) - See [criteria for inclusion](https://github.com/w3c/browser-specs/blob/master/README.md#spec-selection-criteria).\n\n## The Contract\n\nThe following sections define the elements, attributes, and attribute values (along with any specific micro-syntax) that constitute the contract.\n\n### Definitions\n\nA \u003cdfn\u003edefinition\u003c/dfn\u003e is:\n\n- a `\u003cdfn\u003e` element.\n- a `h1`-`h6` element.\n\nNo other HTML elements are recognized as defining a term.\n\nAdditionally, a definition must have an `id` attribute unique to the document.\n\n#### `dfn`-based definitions\n\nThe following attributes can be present on a `dfn`-based definitions:\n\n- (optional) `data-dfn-type`, containing one of the recognized type values (see below). If omitted, defaults to \"dfn\".\n- (optional) `data-lt`, containing the official text of the definition (see below). If omitted, defaults to the text content of the element.\n- (optional) `data-export` or `data-noexport`, indicating whether the definition is intended to be public or document-private (see below). If omitted, defaults based on the dfn type.\n- (optional) `data-dfn-for`, namespacing the value relative to some other construct (see below). If omitted, default to the empty string (indicating no namespace).\n\n#### Heading-based definitions\n\nHeading-based definitions are those defined using `h1`-`h6` elements.\n\nThey accept the same set of attributes as `dfn`-based definitions,\nexcept that `data-dfn-type` and `data-lt` are required, rather than optional.\nIf a heading lacks either of these attributes it *does not* define a definition.\n\n### Linking Text (`data-lt`)\n\nA definition can provide its \"linking text\" via a `data-lt` attribute.\nIf specified, it defines a list of `|`-separated values,\nall of which are linking texts for the definition.\nIf omitted, the (single) linking text is the element's text content.\n\nEach linking text is normalized by trimming ASCII whitespace at the start and end,\nand collapsing sequences of ASCII whitespace inside of the text to a single ASCII space.\n\nCapitalization is preserved in linking texts, but is not semantically meaningful.\n\nLinking texts *should* be defined in the most \"neutral\" form possible.\nIn English, for example, \"swipe\" is better than \"swiping\", \"swiped\", \"swipes\", etc.\n\n\u003e [!NOTE]\n\u003e Spec tools are expected to allow these sorts of conjugations in *links*\n\u003e (allowing \"swiped\" to link to the \"swipe\" definition)\n\u003e and it's easier to do if the definition is in a neutral form.\n\n### Namespacing (`data-dfn-for`)\n\nDefinitions can be \"for\" something,\ndifferentiating them from other definitions of the same type and linking text.\nThis is indicated via the `data-dfn-for` attribute,\nwhich contains a `,`-separated list of values.\n\nIf omitted, the definition is in the null namespace,\nsame as the empty string.\n\n#### Expected Namespaces\n\nNamespaces are *technically* opaque, meaningless strings.\nSome definition types, however, have a convention\nof having the namespace refer to another definition;\nfor example, CSS values are namespaced to a property,\nor IDL attributes are namespaced to an interface.\n\n* \"attribute\", \"constructor\", \"method\", \"const\", \"event\", \"serializer\", \"stringifier\", and \"iterator\" definitions must define what interface they’re relative to.\n* \"argument\" definitions must define what method or constructor they’re relative to.\n* \"dict-member\" definitions must define what dictionary they’re relative to.\n* \"enum-value\" definitions must define what enum they’re relative to.\n* \"element-attr\" and \"element-state\" definitions must define what element they’re relative to.\n* \"attr-value\" definitions must define what element and attribute they’re relative to.\n* \"descriptor\" definitions must define what at-rule they’re relative to. (This happens automatically if you add a \"For\" line to the descdef table.)\n* \"value\" definitions must define what property, descriptor, at-rule, type, selector, or function they’re relative to. If a value definition is relative to a descriptor, the namespace must be of the form \"@foo/bar\", where \"@foo\" is the at-rule the \"bar\" descriptor is relative to.\n* \"cddl-key\", \"cddl-value\", and \"cddl-parameter\" definitions must define what CDDL type they’re relative to.\n\n### Types of definitions (`data-dfn-type`)\n\nEvery exported definition has a \"type\", which is identified by the presence of a `data-dfn-type`.\nWhen the `data-dfn-type` is missing, it is assumed to be the \"dfn\" type.\n\nThe valid values for `data-dfn-type` are enumerated below.\n\n#### General Terms\n\n* `dfn` (for defining most general \"terms\", and a catch-all for anything without a more specific type)\n* `abstract-op` (prose algorithm name)\n\n#### WebIDL\n\nWhen exporting WebIDL definitions, the `data-dfn-type` can be one of the following, each corresponding to a concept in WebIDL:\n\n- `argument` (of a method)\n- `attribute` (of an interface)\n- `callback` (legacy callback interface)\n- `const` (of an interface)\n- `constructor` (of an interface)\n- `dict-member` (of a dictionary)\n- `dictionary`\n- `enum`\n- `enum-value` (of an enum)\n- `exception` (for new DOMException names; new exception classes must use `interface`)\n- `extended-attribute` (aka syntaxes like `[Exposed]`)\n- `interface`\n- `iterator` (of an interface)\n- `maplike` (of an interface)\n- `method` (of an interface)\n- `namespace`\n- `serializer` (of an interface)\n- `setlike` (of an interface)\n- `stringifier` (of an interface)\n- `typedef`\n\n#### Events\n\n* `event` (an event name)\n\n#### CSS\n\n- `property`\n- `descriptor` (the things inside at-rules like @font-face)\n- `value` (any value that goes inside of a property, at-rule, etc.)\n- `type` (an abstract type for CSS grammars, like `\u003clength\u003e` or `\u003cimage\u003e`)\n- `at-rule`\n- `function` (like `counter()` or `linear-gradient()`)\n- `selector`\n\n#### Markup Elements\n\n- `element`\n- `element-state` (a spec concept, like `\u003cinput\u003e` being in the \"password state\")\n- `element-attr`\n- `attr-value`\n\n#### URL Schemes\n\n* `scheme`\n\n#### HTTP Headers\n\n- `http-header`\n\n#### Grammars\n\n* `grammar` (for syntax used in defining grammars, like `||` in the CSS value definition grammar)\n\n#### CDDL Definitions\n\n* `cddl-module` (when spec needs to define multiple CDDL modules)\n* `cddl-type` (things like actual types and groups)\n* `cddl-key` (member names in type or group definitions)\n* `cddl-value` (values in an enumeration)\n* `cddl-parameter` (generic parameter names)\n\n#### Browser Permissions\n\n* `permission`\n\n### Exporting definitions (`data-export` and `data-noexport`)\n\nDefinitions can define whether they are *expected* to be referenced from other specifications or not\nby specifying `data-export` or `data-noexport`.\n`data-export` indicates the definition is intended for outside usage;\n`data-noexport` indicates that it's intended for private usage,\nand probably shouldn't be used by other specifications.\n\n\u003e [!NOTE]\n\u003e Spec-authoring tools will generally require additional steps to link a noexport definition,\n\u003e to ensure you *really* intend to be doing so despite it being marked as private.\n\nThese are boolean attributes. The value *should* be omitted or the empty string.\nAuthors must not specify both on the same element.\nIt's not defined what the value of the export flag is if both are specified.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeced%2Fspec-dfn-contract","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspeced%2Fspec-dfn-contract","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspeced%2Fspec-dfn-contract/lists"}