Documentation
¶
Overview ¶
Package schema is the kernel's single source of truth for OPM schema-side knowledge: CUE paths and the OCI-backed schema loader.
Schema is unversioned at the package level. The library consumes exactly one OPM CUE schema package, opmodel.dev/core at the release DefaultSchemaModule pins, resolved through CUE's module system against CUE_REGISTRY. There is no in-tree schema mirror.
Path inventory ¶
CUE paths are exported as package-level cue.Path variables; the comment on the var block lists every path and its readers. Callers use schema.X verbatim — there is no Paths() accessor, no struct, no lookup. The inventory is exactly what Go code reads: matching and execution happen inside the render build, in CUE, and read nothing by path from Go.
The decoded metadata records are not here: each is declared once, in the package of the artifact it describes (module.ModuleMetadata, module.InstanceMetadata, platform.PlatformMetadata, catalog.CatalogMetadata).
Schema loader and cache ¶
Loader is the strategy interface for resolving the schema; OCILoader is the sole public implementation, fetching DefaultSchemaModule through CUE's module system, and its PinnedVersion reports the exact release the identifier names with no load. Cache memoizes a single Loader.Load per instance (sync.Once-guarded) and exposes ResolvedVersion for diagnostics.
Long-running consumers attach the Cache to a Kernel (via kernel.WithSchemaLoader) and reuse the kernel-owned cache via kernel.SchemaCache(). The library auto-applies no CUE_REGISTRY default; callers opt in by setting CUE_REGISTRY to schema.PublicRegistry (or to a private mirror) before the first Cache.Get.
Index ¶
Constants ¶
const DefaultSchemaModule = "opmodel.dev/core@v2.0.0-beta.4"
DefaultSchemaModule is the module identifier used by OCILoader.Load when OCILoader.Module is empty.
It names an exact core release, never the floating "opmodel.dev/core@v2" major: the release the kernel's render glue, fixtures and parity oracle were verified against. The constant's value below names that release, and doc comments cite it by the constant's name. Core 2.0.0-alpha.13 is the first release reporting contract collisions on the derived #Platform.#contracts inventory (`collisions` and `collidingEntries`, with `routable` false while any exist, and `defined` and `definedBy` folding only keys with exactly one enabled definer), on top of the per-registry-entry provider count (`providedBy`, with `overSubscribed`, `unfulfilled` and `routable` recounted from it), the comparable-predicate report (`comparable` and `discriminated`; 0015:D5, 0015:OQ9), the 0015:D1/D2/D18 inventory, the 0019:D5 registry shape (a #Platform.#registry entry embeds its catalog by import and derives `version` from it) and the 0019:D12 transformer-context projection.
The default is not the render floor: Kernel.Render and Platform.Contracts accept every core from ProvidedBySince on, and a platform pinning a release between the floor and 2.0.0-alpha.13 decodes an absent collision report as no collision (such a core cannot evaluate a colliding platform at all). The constant advances only by a deliberate change that re-verifies the glue and the fixtures against the new release; a default that floats ahead of the glue breaks every synthesized artifact on a cold cache.
const ProvidedBySince = "2.0.0-alpha.12"
ProvidedBySince is the first core release deriving #Platform.#contracts.providedBy, without the "v" prefix: the oldest core a platform module may pin for Kernel.Render and Platform.Contracts, named in their PlatformCoreTooOldError.
const ProvidesSince = "2.0.0-beta.3"
ProvidesSince is the first core release deriving #Catalog.provides (CatalogProvides), without the "v" prefix. It decides which path (*catalog.Catalog).Provides takes for a catalog whose committed core pin is known, and tests use it. It is never a floor: a catalog built against an older core is answered through the deprecated fold, not refused.
const PublicRegistry = "opmodel.dev=ghcr.io/open-platform-model,registry.cue.works"
PublicRegistry is the documented CUE_REGISTRY mapping for resolving the OPM core schema from its canonical GHCR location with a fallback to registry.cue.works. The library does NOT auto-apply this value as a default; callers opt in by setting CUE_REGISTRY=schema.PublicRegistry (or by passing it via OCILoader.Registry).
Operators in restricted environments may set CUE_REGISTRY to a mirror or to an inline configuration without touching this constant.
Variables ¶
var ( // Metadata is the `metadata` field at the root of every artifact. Metadata = cue.ParsePath("metadata") // Module is #ModuleInstance.#module, the instance's reference to its // source #Module. Module = cue.MakePath(cue.Def("module")) // CatalogProvides is #Catalog.provides: the provider-fulfilled // contracts the catalog implements, sorted and deduplicated, derived by // core since [ProvidesSince]. (*catalog.Catalog).Provides decodes it. CatalogProvides = cue.ParsePath("provides") )
The CUE paths a consumer reads on an OPM artifact Package, where no artifact accessor gives the field. Every other path the kernel's Go code reads is internal to the library (opm/internal/corepath) and reached through an accessor: Instance.Components, Instance.Values, Instance.ConfigSchema, Module.ConfigSchema, Module.DebugValues, Platform.Contracts and Catalog.Provides. Each path's readers are:
- Metadata: metadata decoding of every artifact kind (including the module metadata Instance.ModuleMetadata decodes), instance processing and the registry loader's identity read.
- Module: Instance.ConfigSchema, Instance.ModuleMetadata and values checking at acquire and synthesis.
- CatalogProvides: Catalog.Provides.
Matching and execution read nothing by path from Go: the render build imports the instance and the platform as packages and the generated glue reads `components`, `#composedTransformers` and `#contracts` in CUE (0019:D9/D10).
Definition fields (those starting with "#" in CUE) use cue.MakePath with cue.Def selectors; concrete fields use cue.ParsePath. The two forms are not interchangeable — definition paths constructed with ParsePath do not resolve on closed structs.
Treat these variables as constants: assigning to one changes what every kernel in the process reads.
Functions ¶
func DefaultSchemaVersion ¶
func DefaultSchemaVersion() string
DefaultSchemaVersion returns the exact core release DefaultSchemaModule pins, in the canonical "v"-prefixed form a cue.mod dependency carries (the version suffix of the identifier, "v" included). It is the version a generated platform module pins core at by default (opm/helper/platformmodule): the release the render glue was verified against is the release a generated platform must embed.
Types ¶
type Cache ¶
type Cache struct {
// Loader is the strategy used to resolve and build the schema value.
// Required.
Loader Loader
// contains filtered or unexported fields
}
Cache memoizes a single Loader.Load invocation per instance and exposes the resolved schema module version for diagnostics. It owns no goroutines and no I/O of its own; the Loader carries those concerns.
The first Cache.Get invocation creates a private cue.Context and runs Loader.Load into it through sync.Once; every subsequent Get (including the one that loses the race) returns the same cached value or the same cached error. Errors are cached too — the load is never retried. A schema that loads but does not build is memoised as an error, never as an errored value, whichever Loader produced it: OCILoader reports it as an error itself, and Get refuses an errored value any other Loader returns with a nil error. To force a re-fetch, construct a fresh Cache with a fresh Loader. A memoized load error keeps its classification: an OCILoader fetch failure the registry may get past later still matches opm/errors' ErrTransient, but Get on the same Cache returns it again, so a retry needs a fresh Cache (a fresh Kernel).
Each Cache instance owns its own memoization and its own context. The context is the one long-lived evaluation state a Kernel holds, and no accessor exposes it: a caller that must compile a value against the schema takes the returned value's Context. The library MUST NOT expose a package-level Cache singleton; long-running consumers attach the Cache to a Kernel (or equivalent lifetime anchor) and keep that anchor alive across operations. Two Caches, in one process or in two, share CUE's on-disk module cache ($CUE_CACHE_DIR) and never the in-process value: each loads once, and a release already in the disk cache is not downloaded again.
func (*Cache) Get ¶
Get returns the schema cue.Value, invoking the underlying Loader at most once per Cache instance. Concurrent first-call invocations are serialized via sync.Once; the call that wins creates the cache's private context, runs Loader.Load with it, and the rest observe the cached result. The context lives as long as the cached value does and is reachable only through that value.
Returns the zero cue.Value and a non-nil error if Loader.Load fails or returns, with a nil error, a value that is unusable: one whose build failed, or the zero cue.Value (whose Err is "undefined value"). The error wraps the value's own and calls the loaded schema unusable; it is cached and subsequent calls return it without re-invoking the Loader.
func (*Cache) ResolvedVersion ¶
ResolvedVersion returns the schema module version that the underlying Loader resolved during the first successful Cache.Get (e.g. the version suffix of DefaultSchemaModule when the loader used the default).
Returns the empty string before the first successful Get, after a failed Get, or when the Loader does not surface a resolved version. The value is diagnostic-only: callers SHOULD log it but MUST NOT branch behavior on it.
type Loader ¶
Loader resolves the OPM core CUE schema and returns it as a built cue.Value. Implementations MUST return a value whose definitions (#Module, #ModuleInstance, #Platform, #Resource, #Trait, #ComponentTransformer, …) are reachable via LookupPath.
The library exposes exactly one Loader implementation: OCILoader. Any other Loader satisfying the interface is internal-only and MUST NOT appear in the public API surface.
type OCILoader ¶
type OCILoader struct {
// Module is the schema module identifier. Empty means
// [DefaultSchemaModule], the pinned core release.
//
// A bare major form ("…@v0") is automatically expanded to "…@v0.latest"
// before calling [load.Instances]; CUE's standalone-package loader
// requires either a fully qualified version, "@latest", or
// "<major>.latest" outside a module context.
Module string
// Registry overrides CUE_REGISTRY for this load. Empty inherits from
// the process environment.
Registry string
// CacheDir overrides CUE_CACHE_DIR for this load. Empty inherits from
// the process environment (or CUE's default ~/.cache/cuelang/).
CacheDir string
}
OCILoader resolves the OPM core schema through CUE's module system. It is the canonical and only public Loader implementation.
The zero value is a valid Loader: empty fields resolve via process environment (CUE_REGISTRY, CUE_CACHE_DIR) and the DefaultSchemaModule identifier. Explicit field values override environment values.
OCILoader.Load does not mutate process state (no os.Setenv); env overrides are plumbed into load.Config.Env for the single load call.
func (OCILoader) PinnedVersion ¶
PinnedVersion reports, without any I/O, the exact core release the loader's module identifier names: the version suffix of OCILoader.Module (or of DefaultSchemaModule when Module is empty) and true when that suffix is a full release ("v2.0.0-beta.1"), or ("", false) when the identifier names a bare major ("opmodel.dev/core@v2", resolved to ".latest" only by a load) or is not a module identifier at all.
A kernel whose loader pins a release reads the core release its synthesized instances import from here instead of loading the schema; a bare-major loader resolves it through the schema cache.
Source Files