schema

Documentation

Overview

Package schema validates FXVCS documents against the embedded JSON Schemas (spec/schemas) and the semantic rules a schema cannot express, then decodes them into internal/domain types.

Validation is fail-closed and layered, in this order:

1. envelope (apiVersion/kind) via format.ValidateEnvelope, so a newer or unknown apiVersion is reported as the typed format error rather than as a schema issue;
2. explicit-null guard for activation (YAML null is never a tri-state);
3. JSON Schema draft 2020-12 (unknown fields are rejected everywhere);
4. strict decode into the domain struct (unknown fields rejected again);
5. semantic checks: ordering references, cycles, identity uniqueness, path normalization and containment, discriminated unions, digests.

Every failure is an Issue with a JSON-pointer Path. Nothing here writes.

Index

• Constants
• func Compile() error
• func DetectKind(data []byte) (format.Envelope, error)
• func KnownKinds() []string
• func Load(kind string, data []byte) (any, error)
• func LoadAgentConfig(data []byte) (*domain.AgentConfig, error)
• func LoadAssetIndex(data []byte) (*domain.AssetIndex, error)
• func LoadDocument(kind string, doc any) (any, error)
• func LoadEnvironment(data []byte) (*domain.Environment, error)
• func LoadObjectManifest(data []byte) (*domain.ObjectManifest, error)
• func LoadRelease(data []byte) (*domain.Release, error)
• func LoadRepository(data []byte) (*domain.Repository, error)
• func LoadResourceCatalog(data []byte) (*domain.ResourceCatalog, error)
• func LoadResourceOverrides(data []byte) (*domain.ResourceOverrides, error)
• func LoadRuntimeResourceCatalog(data []byte) (*domain.RuntimeResourceCatalog, error)
• func LoadStack(data []byte) (*domain.Stack, error)
• func LoadTarget(data []byte) (*domain.Target, error)
• func RawSchema(idOrPath string) (map[string]any, error)
• func SchemaFile(kind string) (string, bool)
• func SchemaJSON(kind string) ([]byte, error)
• type Issue
  • func (i Issue) Error() string
  • func (i Issue) Unwrap() error
• type Issues
  • func ParseYAML(data []byte) (any, Issues)
  • func Validate(kind string, data []byte) Issues
  • func ValidateDocument(kind string, doc any) Issues
  • func (is Issues) Error() string
  • func (is Issues) Unwrap() []error
• type PointerDocument

Constants

const (
	KindPointer           = "Pointer"
	KindObjectManifest    = "ObjectManifest"
	KindAssetIndex        = "AssetIndex"
	KindHydrationStateRow = "HydrationStateRow"
	KindPublicationLedger = "PublicationLedger"
)

Kinds of schema-only documents that carry no committed envelope. These version themselves independently of apiVersion.

const InputSourceSchema = "v1alpha1/input-source.schema.json"

InputSourceSchema is the standalone schema file for the hook input union; it is validated as part of Target but exposed for tooling.

Functions

func Compile

func Compile() error

Compile compiles every embedded schema once and reports the first error. Tests call it directly; Validate calls it lazily.

func DetectKind

func DetectKind(data []byte) (format.Envelope, error)

DetectKind returns the envelope of a committed document without validating it. It fails only when the document is not a mapping or lacks the fields.

func KnownKinds

func KnownKinds() []string

KnownKinds returns every kind this package can validate, envelope kinds first, in registration order.

func Load

func Load(kind string, data []byte) (any, error)

Load parses, validates and decodes data. On success it returns a pointer to the domain type for kind (see KnownKinds; schema-only kinds return the generic map). The error, when non-nil, is always Issues.

func LoadAgentConfig

func LoadAgentConfig(data []byte) (*domain.AgentConfig, error)

func LoadAssetIndex

func LoadAssetIndex(data []byte) (*domain.AssetIndex, error)

func LoadDocument

func LoadDocument(kind string, doc any) (any, error)

LoadDocument is Load for an already-parsed generic document.

func LoadEnvironment

func LoadEnvironment(data []byte) (*domain.Environment, error)

func LoadObjectManifest

func LoadObjectManifest(data []byte) (*domain.ObjectManifest, error)

func LoadRelease

func LoadRelease(data []byte) (*domain.Release, error)

func LoadRepository

func LoadRepository(data []byte) (*domain.Repository, error)

func LoadResourceCatalog

func LoadResourceCatalog(data []byte) (*domain.ResourceCatalog, error)

func LoadResourceOverrides

func LoadResourceOverrides(data []byte) (*domain.ResourceOverrides, error)

func LoadRuntimeResourceCatalog

func LoadRuntimeResourceCatalog(data []byte) (*domain.RuntimeResourceCatalog, error)

func LoadStack

func LoadStack(data []byte) (*domain.Stack, error)

func LoadTarget

func LoadTarget(data []byte) (*domain.Target, error)

func RawSchema

func RawSchema(idOrPath string) (map[string]any, error)

RawSchema returns the parsed (uncompiled) schema document for a $id URL or schema path. Used by drift tests to compare Go struct fields with schema properties.

func SchemaFile

func SchemaFile(kind string) (string, bool)

SchemaFile returns the schema path (relative to spec/schemas) for a kind.

func SchemaJSON

func SchemaJSON(kind string) ([]byte, error)

SchemaJSON returns the raw embedded schema bytes for a kind.

Types

type Issue

type Issue struct {
	Path    string `json:"path"`
	Message string `json:"message"`
	Cause   error  `json:"-"`
}

Issue is one validation failure. Path is a JSON pointer into the document ("" for the whole document). Cause carries a typed sentinel when one exists (for example format.ErrNewerAPIVersion) so callers can errors.Is it.

func (Issue) Error

func (i Issue) Error() string

Error formats the issue as "<path>: <message>".

func (Issue) Unwrap

func (i Issue) Unwrap() error

Unwrap exposes the typed cause.

type Issues

type Issues []Issue

Issues is a non-empty list of issues; it implements error and unwraps to its members so errors.Is(err, format.ErrNewerAPIVersion) works.

func ParseYAML

func ParseYAML(data []byte) (any, Issues)

ParseYAML parses one YAML (or JSON) document into the generic JSON-compatible form used by the validators: map[string]any, []any, string, int64, float64, bool, nil. It rejects what canonical JSON cannot represent or what makes a document ambiguous:

• more than one document in the stream;
• non-string mapping keys;
• duplicate mapping keys;
• integers outside int64;
• unresolvable aliases or unknown tags.

Timestamps stay strings (their raw scalar text) so RFC 3339 values are validated by pattern rather than re-formatted.

func Validate

func Validate(kind string, data []byte) Issues

Validate parses data (YAML or JSON) and validates it as kind. kind may be "" for committed documents; it is then taken from the document's envelope.

func ValidateDocument

func ValidateDocument(kind string, doc any) Issues

ValidateDocument validates an already-parsed generic document (map[string]any / []any / string / int64 / bool / nil).

func (Issues) Error

func (is Issues) Error() string

func (Issues) Unwrap

func (is Issues) Unwrap() []error

Unwrap returns the members as errors.

type PointerDocument

type PointerDocument struct {
	Version  int    `json:"version"`
	Domain   string `json:"domain"`
	Encoding string `json:"encoding"`
	Manifest string `json:"manifest"`
	OID      string `json:"oid"`
	Size     int64  `json:"size"`
}

PointerDocument is the decoded field view of a v1 pointer, matching pointer-v1.schema.json. internal/pointer owns the text encoding.