projectfile specification

A stack- and vendor-agnostic software project specification.

One file at the root of every project — projectfile.yaml (RECOMMENDED) or projectfile.json (TOML is also a permitted encoding) — that carries identity, license, authorship, technical stack, dependencies, and vendor-specific configuration, replacing the dozen-plus metadata files that accumulate in the root of a modern software project.

• Canonical home: https://projectfile.org/
• Specification (v1): spec/v1.md
• JSON Schema (v1): spec/schema/v1.json — served at https://projectfile.org/schema/v1.json.
• Examples: spec/examples/ (every example ships in .yaml and .json form)
• Extension registry (non-normative): spec/registry.yaml

What it looks like

$schema: https://projectfile.org/schema/v1.json

identity:
  namespace: org.example
  name: cool-widget
  title: { en: "Cool Widget" }
  urls:
    homepage: https://example.org/cool-widget
    repository: { url: https://github.com/example/cool-widget }

license:
  spdx: Apache-2.0

technologies: [typescript, node, react]

requirements:
  runtime: { node: ">=24" }

dependencies:
  runtime: [ "pkg:npm/react@^19" ]

# Vendor-specific: nested-mapping reverse-DNS namespace.
# Unknown namespaces are ignored, not rejected.
com:
  example:
    build:
      type: standard
      image: "ubuntu:24.04"

The same document encodes identically in JSON, and in TOML (where the discriminator is the #:schema magic comment plus spec_version = "1").

Design principles

• Reuse existing standards — Schema.org, SPDX, package-url, SemVer, BCP 47. Don’t reinvent.
• Format choice without semantic split — TOML, YAML, and JSON encode the same document; tooling MUST be format-agnostic.
• Extensibility without a committee — any reverse-DNS actor can claim a namespace (org.example.my-tool as a nested mapping path) and ship tooling against it. Consumers MUST preserve unknown namespaces on round-trip.
• Typo safety — unknown reserved (single-segment) keys are rejected. Unknown extension (multi-segment, reverse-DNS) namespaces are preserved. This is the single load-bearing rule.
• Schema discriminator — TOML files use the #:schema magic comment + spec_version = "1"; YAML and JSON use $schema:. All three give editors and language servers free schema-driven validation.

Tooling

The format-conversion + multi-file detector tool lives in the sibling projectfile/cli/ project (planned, not yet written). The spec repository holds no implementation.

Contributing

• Spec changes — open a PR modifying spec/v1.md. Substantive changes bump the revision date in the document header. Breaking changes are deferred to a future v2 document.
• Technology tags — open a PR modifying spec/technologies.yaml. One-line rationale in the commit message; no committee review.
• Extension registry entries — open a PR modifying spec/registry.yaml. Inclusion is advisory, not an endorsement.

Licensing

• Specification text (this readme, spec/v1.md): CC-BY-4.0.
• JSON Schema, examples, and any code: MIT.

See LICENSE for the MIT text and LICENSES/CC-BY-4.0.txt for the CC-BY-4.0 text.