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., "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, "v1", "v1.0.0")
// h.Metadata == map[string]string{"timestamp": "...", "version": "v1.0.0"}

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

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

Serialization ¶

Headers serialize consistently to JSON and YAML:

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

API Versioning ¶

The APIVersion field enables evolution of data formats:

• v1: Current stable API
• Future versions can add fields with backward compatibility

Tools should check APIVersion before parsing:

if header.APIVersion != "v1" {
    return fmt.Errorf("unsupported API version: %s", header.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, "v1", "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)