Report Schema Stability Contract

Scope

This contract applies to machine-readable report outputs generated by bpfcompat and consumed by CI/release-gate integrations.

Primary schema type:

• pkg/schema/report_v0_1.go

Current schema version string:

• v0.1

Compatibility Policy

1. schema_version is mandatory in all report JSON outputs.
2. Patch/minor additions that are backward-compatible:
   • may add new optional fields
   • may add new enum-like values where callers are expected to handle unknown values safely
3. Breaking changes:
   • require a new schema major (v1.x, v2.x, ...)
   • must not silently reuse an older schema version string
4. Existing fields in a published schema major must not change semantic meaning.

Consumer Expectations

Consumers should:

• gate on schema_version
• treat unknown fields as forward-compatible
• treat unknown enum values as non-fatal unless policy explicitly requires strict matching

Change Control

For any schema change:

1. update pkg/schema/* types
2. update this document changelog
3. add/adjust tests for serialization and downstream parsing assumptions
4. note migration implications in release notes/docs

Changelog

Date	Version	Change Type	Notes
2026-05-15	v0.1	Initial	Baseline run/report schema for MVP validation and CI gating
2026-05-19	v0.1	Backward-compatible additive	Added optional targets[].profile, targets[].host, targets[].validation, and targets[].failed_stage fields for richer technical output without breaking existing consumers.