5. Summary of reserved top-level keys
| Key | Cardinality | Purpose |
|---|---|---|
$schema |
REQUIRED in YAML/JSON | Discriminator; pins spec version. |
spec_version |
REQUIRED in TOML | Discriminator; pins spec version. |
kind |
OPTIONAL | Schema.org type. |
identity |
REQUIRED | Namespace, name, version, title, summary, description, visibility, created/released/modified dates. |
repositories |
OPTIONAL | Source-control clone endpoints with structural attributes (branch, path, role). See §4.3a. |
license |
OPTIONAL | SPDX expression, scope-of-coverage, license file(s). |
copyright |
OPTIONAL | Default copyright year. Holder identities live under people with the copyright role; see §4.4a. |
upstream |
OPTIONAL | Third-party software the project packages or forks, with its version and license. See §4.4b. |
people |
OPTIONAL | Persons (authors, maintainers, contributors — single list, role-tagged). |
organizations |
OPTIONAL | Organizations and non-person entities (role-tagged). See §4.5a. |
keywords |
OPTIONAL | Free-form thematic tags for discovery. |
technologies |
OPTIONAL | Technology tags. |
requirements |
OPTIONAL | Browser targets and runtime version ranges. Platform targeting is §4.8a. |
includes |
OPTIONAL | Documents to deep-merge before reading. See §4.9. |
links |
OPTIONAL | Typed navigational URL sequence (open type vocabulary). See §4.10. |
Concerns that previously appeared as reserved fields in earlier drafts (e.g., health) are deliberately not reserved: they describe deployment or runtime surfaces, not project metadata, and belong in extension namespaces. A non-normative example is sketched in Section 6.5.