About this specification

This document defines projectfile, a single declarative file that carries a software project’s identity, legal, authorship, technical, and vendor-specific metadata in one place. The goal is one authoritative source that the other metadata files are generated from or checked against, while remaining open to tools the spec authors never imagined.

It reuses established standards — Schema.org, SPDX, SemVer, BCP 47 — for well-trodden concerns, and defines a reverse-DNS extension mechanism for everything else.

The document may be encoded as YAML (RECOMMENDED), TOML, or JSON; the on-disk filename identifies the encoding (projectfile.yaml, projectfile.toml, projectfile.json).

Published. Version 1 of this specification is stable. The reserved field set is stable in intent; individual field shapes MAY change in minor revisions dated after this document’s revision header. Breaking changes will spawn a separate “version 2” document; version 1 will remain readable indefinitely.

This document is published at https://projectfile.org/spec/v1. The JSON Schema derived from this document is served at https://projectfile.org/schema/v1.json.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 when, and only when, they appear in all capitals, as shown here. RFC 8174 clarifications apply.

This specification defines three conformance roles; an implementation MAY claim several.

• A conformant validator parses a document per §3.3, resolves its includes per §4.9 when it supports them, and evaluates the published schema against the result — v1.json for a document, v1-fragment.json for a fragment. It also applies the rules the schema cannot express: the per-encoding discriminator (§3.4, §4.1), the single-file rule (§3.5) and path traversal (§8). It accepts every document under spec/examples/ and rejects every document under spec/examples/negative/ in the specification repository.
• A conformant consumer reads a document under the handling rule (§3.7): it never rejects a document for an unknown reserved key, an unknown extension namespace or a construct it does not implement, and it observes §8. Includes (§4.9) and interpolation (§3.8) are optional capabilities; a consumer that implements one MUST implement it as specified, and an interpolating consumer MUST produce the outputs of the vectors under spec/conformance/interpolation/.
• A conformant producer obeys §6.4 and preserves what it does not own (§3.7).

An extension MAY publish its own conformance vectors (spec/conformance/ci/, spec/conformance/image/); conformance to an extension is claimed separately from conformance to this document.

This document is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). The JSON Schema referenced by this document, and any code or example files in the specification repository, are licensed under the MIT License. Downstream implementers MAY copy schema and example snippets without attribution.