Documentation
¶
Overview ¶
Package schema derives JSON Schema documents from the Go types that define AICR's published artifacts.
Artifact schemas are one of the four surfaces ROADMAP section 1 freezes at v1 (issue #2113). Integrators need a machine-readable description of what a Snapshot or RecipeResult contains, and the project needs a baseline it can diff to catch a field being removed or narrowed.
Why reflection rather than a schema library ¶
A generator has to compile against the types, so it cannot be a pinned binary the way oasdiff is for the REST contract. Importing a schema library would put it in the module graph, and therefore in the SBOM and vulnerability surface of the shipped binaries, for something that only ever runs at build time. tools/api-diff and tools/openapi-diff both avoid that; this follows.
The tradeoff is that this file is hand-written, so it is deliberately narrow. It covers the shapes the artifact types actually use — structs, embedded structs, pointers, slices, maps, strings, integers, booleans and any — and FAILS on anything else rather than emitting a plausible guess. A schema that silently describes an unsupported type incorrectly is worse than no schema, because the diff gate would then protect the wrong shape.
Index ¶
Constants ¶
const Draft = "https://json-schema.org/draft/2020-12/schema"
Draft is the JSON Schema dialect the generated documents declare.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// Title is the artifact kind, e.g. "RecipeResult".
Title string
// Description explains what the artifact is, for integrators reading the
// generated file without the Go source at hand.
Description string
// ID is the canonical URI for the schema.
ID string
// Enums supplies allowed values for named types, keyed by the type's
// package-qualified name (e.g. "recipe.CriteriaServiceType"). A type with
// no entry is described only by its kind.
Enums map[string][]string
// Authored marks an artifact a human writes rather than one AICR emits,
// which changes what "required" means.
//
// For an emitted artifact the encoder's behavior is the contract: a field
// without omitempty is always written, so a consumer may rely on it. For an
// authored one it is not. ComponentRef.Source carries no omitempty, so the
// encoder always writes it -- but only 17 of the 110 committed overlays set
// it, and marking it required published a schema that rejected the other 93.
Authored bool
}
Options controls generation for one artifact kind.
type Schema ¶
type Schema struct {
Schema string `json:"$schema,omitempty"`
ID string `json:"$id,omitempty"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Type string `json:"-"`
Enum []string `json:"enum,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
Items *Schema `json:"items,omitempty"`
// ContentEncoding describes a string that carries encoded bytes, which is
// how encoding/json writes a []byte.
ContentEncoding string `json:"contentEncoding,omitempty"`
// AdditionalProperties is a *bool so that "false" is emitted and "unset"
// is not. A plain bool would make every closed object indistinguishable
// from one that never declared the constraint.
AdditionalProperties *bool `json:"additionalProperties,omitempty"`
// PropertyNames constrains map keys; nil for objects with fixed fields.
PropertyNames *Schema `json:"propertyNames,omitempty"`
// Nullable records that the encoder can write JSON null here, which
// happens for any nil-able Go type whose tag lacks omitempty.
Nullable bool `json:"-"`
}
Schema is a JSON Schema node.
Field order matches the marshaled output, and every collection field is omitempty so a scalar node does not carry empty objects.
func Generate ¶
Generate derives a JSON Schema from a Go type.
It returns an error rather than emitting a partial document: a schema that omits a field it could not model would be a baseline that silently stops protecting it.
func (Schema) MarshalJSON ¶
MarshalJSON writes the node, expressing nullability the JSON Schema 2020-12 way: as a type array rather than the OpenAPI 3.0 `nullable` keyword, which this dialect does not define.
Field order is explicit rather than inherited from struct order, because these documents are committed and compared byte-for-byte.
Source Files