header

Overview ¶

Package header provides common header types for AICR data structures.

This package defines the Header type used across recipes, snapshots, and other AICR data structures to provide consistent metadata and versioning information.

Header Structure ¶

The Header contains standard fields for API versioning and metadata:

type Header struct {
    Kind       Kind              `json:"kind,omitempty" yaml:"kind,omitempty"`             // Resource type (Snapshot, Recipe, RecipeResult)
    APIVersion string            `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty"` // API version (e.g., "aicr.run/v1")
    Metadata   map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`     // Free-form string metadata (timestamp, version, etc.)
}

Metadata is a flat map[string]string populated by Init / InitWithTime with the unprefixed keys "timestamp" (RFC3339 UTC) and "version" (when supplied).

Usage ¶

Initialize a header for a recipe via Init:

var h header.Header
h.Init(header.KindRecipe, header.StableGroupVersion, "v1.0.0")
// h.Metadata == map[string]string{"timestamp": "...", "version": "v1.0.0"}

KindRecipe shown here is the legacy input kind, distinct from KindRecipeResult and normalized to it per ADR-022 §2; both sit on the stable artifact track alongside Snapshot, hence StableGroupVersion. An authored catalog RecipeMetadata is colloquially a "recipe" too but sits on the authoring track, and a profile-bearing artifact on its own track, so those emitters pass AuthoringGroupVersion or ProfileGroupVersion instead; see the API Versioning section below.

For reproducible-build callers (SLSA, signed artifacts) inject a fixed timestamp via InitWithTime instead of Init:

var h header.Header
h.InitWithTime(header.KindSnapshot, header.StableGroupVersion, "v1.0.0", buildTime)

Serialization ¶

Headers serialize consistently to JSON and YAML:

{
  "apiVersion": "aicr.run/v1",
  "kind": "Recipe",
  "metadata": {
    "timestamp": "2025-12-30T10:30:00Z",
    "version": "v1.0.0"
  }
}

API Versioning ¶

The APIVersion field enables evolution of data formats. APIGroup derives from Domain. Per ADR-013 the move from the legacy aicr.nvidia.com/v1alpha1 group was a hard break — the old value is rejected, not migrated.

ADR-022 splits artifacts across three schema tracks. An emitter aliases the constant for its track — StableGroupVersion, AuthoringGroupVersion, or ProfileGroupVersion — never GroupVersion directly. The three carried the same value through the reader-first release, so aliasing by value rather than by track compiled and passed tests while emitting the wrong version later. The v0.22 switch (#2416) separated them, which turns that mistake into a visible wrong value instead of a latent one.

Callers should select the gate for the artifact's schema track rather than comparing literals, so the single source of truth in this package stays authoritative. IsSupportedAPIVersion covers the stable artifact track:

if h.APIVersion != "" && !header.IsSupportedAPIVersion(h.APIVersion) {
    return errors.New(errors.ErrCodeInvalidRequest,
        fmt.Sprintf("unsupported apiVersion %q", h.APIVersion))
}

Kind Field ¶

The Kind field is a typed constant identifying the resource:

• KindSnapshot ("Snapshot"): System configuration capture
• KindRecipe ("Recipe"): Configuration recommendations
• KindRecipeResult ("RecipeResult"): Resolved recipe with hydrated values

Custom Metadata ¶

Because Metadata is a flat map[string]string, callers may add their own keys alongside the Init-populated "timestamp" and "version":

h.Metadata["node"] = "gpu-node-1"
h.Metadata["cluster"] = "production"
h.Metadata["environment"] = "staging"

Timestamps ¶

Init writes the timestamp using RFC3339 format in UTC:

h.Init(header.KindRecipe, header.StableGroupVersion, "v1.0.0")
// h.Metadata["timestamp"] == "2025-12-30T10:30:00Z"

Validation ¶

While Header doesn't enforce validation, consumers should verify:

• APIVersion is supported
• Kind is recognized
• Metadata["timestamp"] is reasonable
• Version is a valid semantic version (if present)