feat: add ReleaseSet, Fingerprint, ConfigSource, TokenDoor, GitRefBuild schemas by Copilot · Pull Request #73 · SourceOS-Linux/sourceos-spec

Copilot · 2026-04-30T18:00:34Z

Adds canonical v2 JSON Schema definitions and conforming examples for five SourceOS lifecycle types adjacent to NLBoot, consumed by sourceos-boot, release tooling, Homebrew taps, and the control plane.

New schemas

Schema	URN prefix	Purpose
`ReleaseSet`	`urn:srcos:release-set:`	Assigned software + boot artifacts for target devices
`Fingerprint`	`urn:srcos:fingerprint:`	Point-in-time device state observation + compliance verdict
`ConfigSource`	`urn:srcos:config-source:`	Typed config reference (git/http/oci/inline/bundle) with integrity binding
`TokenDoor`	`urn:srcos:token-door:`	Token-gated access gate for boot/provisioning phases with quota + expiry
`GitRefBuild`	`urn:srcos:git-ref-build:`	Build provenance record linking a Git commit to output artifacts

All schemas follow existing v2 conventions: $schema, $id, title, additionalProperties: false, id/type/specVersion required fields, URN-pattern id, camelCase properties.

Validation

tools/validate_nlboot_examples.py extended with all 5 new pairs; now covers 9 schema/example pairs total.
Fixed a pre-existing ValueError crash in tools/validate_control_plane_examples.py where Path.with_name() rejected ./-prefixed $ref values (./release-set.schema.json). Fix: use (schema_path.parent / legacy_ref).resolve().
Removed ReleaseSet and Fingerprint from the control-plane validator's legacy-schema pairs — the canonical validator now owns those.
examples/release_set.json and examples/fingerprint.json migrated from snake_case legacy format to v2 camelCase to conform to the new canonical schemas.

Catalog updates

schemas/README.md and examples/README.md updated with new "Recent additions" sections and quick-reference table rows.

…ld schemas and examples Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-spec/sessions/d3049a4c-d0a8-45a9-ac88-d65006ae8627 Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>

mdheller · 2026-04-30T18:19:36Z

@copilot Scope appears aligned with issue #72, but this PR is still draft and no workflow run is visible. Please mark it ready for review when complete, retain validation evidence for make validate, and keep scope limited to schemas/examples/validation/catalog updates.

Copilot · 2026-04-30T18:21:24Z

@copilot Scope appears aligned with issue #72, but this PR is still draft and no workflow run is visible. Please mark it ready for review when complete, retain validation evidence for make validate,...

Scope is bounded to schemas, examples, validation tooling, and catalog updates only — no runtime code touched.

make validate output (commit 5c93a46):

python3 tools/validate_control_plane_examples.py
{"checks": {"boot_release_set.json": true, "enrollment_token.json": true}, "ok": true}

python3 tools/validate_nlboot_examples.py
{"checks": {"apple_silicon_adapter_evidence.json": true, "artifact_cache_record.json": true, "boot_proof_record.json": true, "config_source.json": true, "fingerprint.json": true, "git_ref_build.json": true, "nlboot_plan.json": true, "release_set.json": true, "token_door.json": true}, "ok": true}

OK: validate

All 9 schema/example pairs pass. The agent environment doesn't have permission to call markPullRequestReadyForReview via GraphQL (403) — please mark it ready from the GitHub UI.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/graphql
- Triggering command: /usr/bin/gh gh pr ready 73 --repo SourceOS-Linux/sourceos-spec (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Copilot

Pull request overview

Adds canonical v2 JSON Schemas and conforming examples for five release/build lifecycle contract types, and wires them into the repository’s schema/example validation and catalog docs.

Changes:

Introduce new v2 schemas + examples: ReleaseSet, Fingerprint, ConfigSource, TokenDoor, GitRefBuild.
Extend tools/validate_nlboot_examples.py to validate the new schema/example pairs; adjust the control-plane validator to resolve ./ $refs and drop legacy pairs now owned by the canonical validator.
Update schema and example catalogs (schemas/README.md, examples/README.md) with a “Recent additions” section and quick-reference rows.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/validate_nlboot_examples.py	Adds the 5 new schema/example pairs to the canonical validator set.
tools/validate_control_plane_examples.py	Fixes legacy `$ref` resolution for wrapper schemas; removes ReleaseSet/Fingerprint legacy validation pairs.
schemas/ReleaseSet.json	New v2 schema defining assigned release sets and artifact references.
schemas/Fingerprint.json	New v2 schema defining point-in-time device observations and compliance verdicts.
schemas/ConfigSource.json	New v2 schema defining typed config source references (git/http/oci/inline/bundle).
schemas/TokenDoor.json	New v2 schema defining token-gated access boundaries with quota/expiry fields.
schemas/GitRefBuild.json	New v2 schema defining build provenance from git ref/commit to produced artifacts.
schemas/README.md	Documents the new lifecycle schemas and adds them to the quick reference table.
examples/release_set.json	Migrates legacy snake_case example to v2 camelCase and new fields.
examples/fingerprint.json	Migrates legacy snake_case example to v2 camelCase and new structure.
examples/config_source.json	Adds v2 example for ConfigSource.
examples/token_door.json	Adds v2 example for TokenDoor.
examples/git_ref_build.json	Adds v2 example for GitRefBuild.
examples/README.md	Documents the new lifecycle examples and updates “Recent additions” sections.

Copilot · 2026-04-30T19:01:43Z

+    "uri": {
+      "type": ["string", "null"],
+      "description": "URI of the configuration source. Required for git, http, and oci kinds."
+    },


The uri field description says it's required for git, http, and oci sourceKind, but the schema does not enforce that (it allows uri: null and does not conditionally require it). Either enforce this with if/then (or oneOf) keyed on sourceKind, or update the description to avoid stating a requirement the schema doesn't validate.

Copilot · 2026-04-30T19:01:43Z

    legacy_ref = schema.get("allOf", [{}])[0].get("$ref")
-    validation_schema_path = schema_path.with_name(legacy_ref) if legacy_ref else schema_path
+    validation_schema_path = (schema_path.parent / legacy_ref).resolve() if legacy_ref else schema_path
    validation_schema = json.loads(validation_schema_path.read_text(encoding="utf-8"))


legacy_ref is read from schema content and is now joined/resolved into a filesystem path. This allows absolute paths or ../ traversal to escape schemas/control-plane/ and make the validator read arbitrary files when run in CI. Consider restricting legacy_ref to a relative path under schema_path.parent (e.g., reject absolute paths, reject .., and after resolve() assert it is_relative_to(schema_path.parent.resolve())).

mdheller

Approved. Scope matches issue #72: ReleaseSet, Fingerprint, ConfigSource, TokenDoor, and GitRefBuild schemas/examples/validation/catalog updates. This remains schema/spec-only and does not introduce runtime behavior. No workflow run is visible, but the PR body reports make validate coverage and the changes are bounded to normative contracts and validators.

Initial plan

640be62

Copilot AI assigned Copilot and mdheller Apr 30, 2026

Copilot started work on behalf of mdheller April 30, 2026 18:00 View session

Copilot AI linked an issue Apr 30, 2026 that may be closed by this pull request

Agent task: add SourceOS release and build object schemas #72

Closed

feat: add ReleaseSet, Fingerprint, ConfigSource, TokenDoor, GitRefBui…

5c93a46

…ld schemas and examples Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-spec/sessions/d3049a4c-d0a8-45a9-ac88-d65006ae8627 Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add SourceOS release and build object schemas~~ feat: add ReleaseSet, Fingerprint, ConfigSource, TokenDoor, GitRefBuild schemas Apr 30, 2026

Copilot finished work on behalf of mdheller April 30, 2026 18:09

Copilot AI requested a review from mdheller April 30, 2026 18:09

Copilot started work on behalf of mdheller April 30, 2026 18:19 View session

Copilot finished work on behalf of mdheller April 30, 2026 18:22

mdheller marked this pull request as ready for review April 30, 2026 18:57

mdheller requested a review from Copilot April 30, 2026 18:57

Copilot started reviewing on behalf of mdheller April 30, 2026 18:57 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

mdheller approved these changes Apr 30, 2026

View reviewed changes

mdheller merged commit cdc47c3 into main Apr 30, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add ReleaseSet, Fingerprint, ConfigSource, TokenDoor, GitRefBuild schemas#73

feat: add ReleaseSet, Fingerprint, ConfigSource, TokenDoor, GitRefBuild schemas#73
mdheller merged 2 commits intomainfrom
copilot/add-sourceos-schemas

Copilot AI commented Apr 30, 2026 •

edited

Loading

Uh oh!

mdheller commented Apr 30, 2026

Uh oh!

Copilot AI commented Apr 30, 2026 •

edited

Loading

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

Copilot AI Apr 30, 2026

Uh oh!

mdheller left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New schemas

Validation

Catalog updates

Uh oh!

mdheller commented Apr 30, 2026

Uh oh!

Copilot AI commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

mdheller left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 30, 2026 •

edited

Loading

Copilot AI commented Apr 30, 2026 •

edited

Loading