docmeta:core:1.0.0-proposal.3

Proposal under review

Part of the metadata vocabularies proposal, open for community review. Draft schema: docs/proposals/0023/schemas/core/1.0.0-proposal.3.json. Review round 6 took core from proposal.1 to proposal.2 by moving authors to stewardship. Round 8 took it to proposal.3 by adding locale beside language.

The question it answers: what is this page? Core is the minimum every page meets: a title and a sentence. It works in any repo, with no content strategy, no review process, and no tooling. The whole family is intended for docmeta’s default set, and core is the only part of it that requires anything.

Fields

Field	Type	Required	Notes
title	string, non-empty	yes	A single non-empty string. An array is rejected
description	string, non-empty	yes	One full sentence. It becomes the search snippet and is the first thing retrieval reads
id	string, non-empty	no	A stable identifier that does not change when the file moves. related-pages, prerequisites, and replaced-by point at it
type	string, non-empty	no	What kind of content this is. Taxonomy schemas (Diátaxis, TGDP) narrow it; kg.type holds the same fact in iiRDS terms
keywords	string or list of non-empty strings	no	Search words. A comma-separated string is the AsciiDoc form Antora reads
language	string, non-empty	no	The natural language the text is written in, as one BCP 47 tag, region and script subtags included (pt-BR, zh-Hant-TW). Recommended, not enforced. The same fact lang and dc:language carry
locale	string, non-empty	no	The international preferences the content follows: how its dates, numbers, currency, calendar and sorted lists are written. One Unicode locale identifier (en-IN, th-TH-u-ca-buddhist), recommended, not enforced. Set only where it differs from what language implies

Examples

The minimum:

---
title: Install the operator on Kubernetes
description: Deploy the operator with Helm and verify the rollout.
---

Everything core knows about:

---
title: Install the operator on Kubernetes
description: Deploy the operator with Helm and verify the rollout.
id: install-operator-k8s
type: how-to
keywords: [helm, operator, kubernetes]
language: en
locale: en-GB
---

Design decisions

• Every string is non-empty, and five fields take one value. title, description, type, language, and locale are single strings, and no string core defines may be empty. This is stricter than the loosest schemas that share these keys: Docusaurus permits an empty title, and Dublin Core allows repeated elements. These are the only exceptions to the family’s compatibility rule, under which a document valid under another built-in schema stays valid here. The automated compatibility check records each exception as an expected rejection, so an exception that is not on this list fails CI.
• Core describes content, never rendering. There is no slug, layout, image, or tags here. Rendering keys stay with your generator. Core describes what the page is.
• language and locale are two facts, split where the W3C splits them. The Language Tags and Locale Identifiers spec defines a language tag as an identifier for a language. It defines a locale as an identifier for a set of international preferences. Those are a language, usually a region, and the calendar, numbering system and collation that formatting needs. language is the first. It says what the text is written in, the same fact that lang, xml:lang, hreflang and dc:language carry. locale is the second. It says which conventions the content follows. An English page whose dates and amounts follow German conventions is language: en with locale: de-DE, and a single tag cannot record both. A language tag can serve as a locale on its own, so leave locale out wherever it would only repeat language. Rendering is still not claimed. Which site tree a page renders in, its text direction, and how a generator formats the values it computes all stay with the generator. locale records only what is already in the text. The recommended value is a Unicode locale identifier: a BCP 47 tag with optional -u- extension keywords, in hyphen form. Open Graph’s og:locale spells it en_US, and that key belongs to Open Graph.
• No stored copy of a value the vocabulary derives. There is no date key here, and no stored review deadline. last-reviewed plus review-interval give that deadline, so a stored copy could only agree with them or lie. The document’s own dates are a different case, and they live in stewardship. Review round 9 added created and last-updated there, because git’s timestamps describe the path rather than the document.
• People are in stewardship. authors was a core field until review round 6. It now sits with owner, stakeholders, and reviewed-by in the stewardship vocabulary. Core answers what the page is. Who wrote it belongs with the question of whether the page is cared for. Moving it makes attribution one adoption decision together with the other people fields, instead of a seventh field in the minimum every page meets.

What reviewers should poke at

Four questions. Is requiring title and description on unconfigured runs the right default? Is the non-empty rule worth the recorded exception against Docusaurus’s documented tolerance for empty titles? Does moving authors to stewardship match where you would look for it? Docusaurus and MyST both keep it next to title, so this is the one place the family reads differently from the generators it composes with. And should locale enforce the hyphen form and reject en_US, where language enforces nothing about its value?