Project Schema Contract

A minimal, flat project manifest. Describes what the project is and where it lives — nothing more. Validate payloads against this schema before processing.

Schema URL: https://driftsys.github.io/schemas/project/v1.json

Every project carries a project.yaml (or .toml / .json) that declares its canonical name, version, domain, and optional metadata like category and license. Tools read this manifest to identify the project, resolve dependencies, and configure build pipelines. The schema is intentionally small and flat — no nesting, no tool-specific fields.

Discovery Protocol

Detect a project.yaml, project.toml, or project.json file.
Resolution order: YAML → TOML → JSON (first found wins).
Validate against project/v1.json before reading fields.
Parse required fields (name, version) first.
Parse optional fields second.
Treat the schema as closed (additionalProperties: false).

Schema Index

Schema path	What it describes	Stable key
v1.json	Project manifest	`name`

Validation Contract

Validate early so downstream logic stays predictable.

Validation must happen before any business logic.
Missing required fields (name, version) means hard failure.
Unknown properties must be rejected (schema is closed).
If schema fetch fails, return a schema-unavailable error.

Properties

Path	Type	Required	Description
`name`	string	yes	Reverse-domain project identifier (`^[a-z][a-z0-9.-]*$`)
`version`	string	yes	Canonical version — single source of truth
`category`	string \	string[]	Project classification (see values below)
`description`	string	One-line summary
`license`	string	SPDX license expression
`keywords`	string[]	Discovery tags (free text)
`labels`	string[]	Process-defined labels (validated at compile time)
`authors`	string[]	Authors in `Name` format
`homepage`	string (uri)	Project website or documentation portal URL
`bugs`	string (uri)	Issue tracker URL
`repository`	string (uri)	Source repository URL
`upstream`	string	Upstream repo URL for forks (`#branch` suffix)
`process`	projectRef[]	Process projects this project conforms to
`dependencies`	projectRef[]	Projects this project uses (full traceability expected)
`references`	projectRef[]	Registries and external sources cited (traceability leaf)
`classification`	string	Data classification level (default: `unclassified`)
`metadata`	object	Freeform key-value block for org-specific info

projectRef

Each entry in process, dependencies, and references has this shape:

Path	Type	Required	Description
`url`	string (uri)	yes	Repository or published site URL
`version`	string	Version of the referenced project
`name`	string	Short display name

Category values (examples)

Values are informative and may be defined by a process project. Common values include:

Value	Description
`manifest`	Integration root — assembles components, ships to customer
`specification`	Requirements, features, safety concepts
`application`	Deployable end-user product
`service`	Backend service or API
`library`	Reusable dependency
`tool`	Developer tool, CLI, build plugin (source code)
`binary`	Precompiled executables, firmware, vendor tools
`distribution`	Release artifacts, install packs
`configuration`	Graphic assets, system config, calibration data

Classification values

ISO 27001 / government compatible. Ascending sensitivity:

Value	Sharing scope
`unclassified`	No restrictions (default)
`internal`	Organization only
`confidential`	Named recipients
`restricted`	Need-to-know
`secret`	Cleared personnel
`top-secret`	Compartmented access

Dependency model

Three fields declare project-level relationships:

process — governance. Process projects define entry types, attributes,

constraints, and policies. Multiple processes supported; constraints accumulate (most restrictive wins).

dependencies — consumption. Projects this project needs. The compiler

expects entries to link across the boundary and warns on coverage gaps.

references — citation. External registries and standards. References are

traceability leaves — the compiler resolves links to them but expects no deeper chain.

Failure Modes

unsupported-version — schema version is not recognized. Stop processing.
schema-unavailable — schema URL cannot be fetched. Return error.
validation-failed — payload does not match schema. Reject payload.

Version Policy

Breaking changes create a new major version path (v2.json).
Non-breaking additions stay in the current major version.
Consumers should pin to a major version.

Quick Example

Input: project.yaml\ Schema: project/v1.json

name: io.acme.braking-features
version: "1.0.0"
category: specification
description: Braking system feature requirements
classification: confidential

process:
  - url: https://github.com/acme/process-v2
    version: "2.1"
    name: ACME Process

dependencies:
  - url: https://github.com/acme/abs-component
    version: "0.3"
    name: ABS

references:
  - url: https://driftsys.github.io/refhub
    name: RefHub

Validate payload against schema.
Parse name and version (required).
Parse optional fields (category, description, license, etc.).
Parse process, dependencies, references for dependency resolution.
Reject if unknown properties are present.