Documentation
¶
Overview ¶
Package configschema derives the published JSON Schema (schema/apic-config.schema.json) from the generator's config model, and validates JSON/YAML configs against it. It is build-time tooling: tests and tools/configschema.go call it; nothing at runtime does.
Index ¶
- Constants
- Variables
- func Build() (doc map[string]any, err error)
- func BuildJSON() (out []byte, err error)
- func BuildJSONWithSourceRoot(sourceRoot string) (out []byte, err error)
- func Check(root string) (inspected []string, err error)
- func CheckWithSourceRoot(root, sourceRoot string) (inspected []string, err error)
- func CorpusFiles(root string) (jsonFiles, yamlFiles []string, err error)
- func ModuleRoot() string
- func SourcePath(yamlRel string) (string, error)
- func ToYAMLTwin(jsonData []byte) ([]byte, error)
- func TwinPath(jsonRel string) (string, error)
- func Write(root string) (changed []string, err error)
- func WriteWithSourceRoot(root, sourceRoot string) (changed []string, err error)
- type Validator
Constants ¶
const ( // SchemaPath is where the committed schema lives, relative to ModuleRoot. SchemaPath = "schema/apic-config.schema.json" // SchemaID is the schema's $id. SchemaID = "https://devnw.dev/apic/schema/apic-config.schema.json" // Draft is the JSON Schema dialect the generated schema declares. Draft = "https://json-schema.org/draft/2020-12/schema" )
const ( // ConfigsDir is the fixture corpus root, relative to ModuleRoot. ConfigsDir = "configs" // YAMLDir contains the deterministic YAML representations. YAMLDir = "configs/yaml" )
Variables ¶
var ErrBuild = errors.New("configschema: build")
ErrBuild wraps schema construction failures.
var ErrSchemaViolation = errors.New("configschema: config violates schema")
ErrSchemaViolation wraps a config that does not conform to the schema (or cannot be parsed as JSON at all).
var ErrTwin = errors.New("configschema: yaml twin")
ErrTwin wraps YAML-twin path and conversion failures.
Functions ¶
func Build ¶
Build returns the JSON Schema (draft 2020-12) for the apic config as a generic document. Reflection over generator.Config supplies the structure (json tags, embedded-struct promotion with outer-shadows-embedded precedence, pointer nullability, additionalProperties:false everywhere to mirror the generator's RejectUnknownMembers decode); Go doc comments supply descriptions; overlay.go supplies enums and required members.
func BuildJSON ¶
BuildJSON renders Build() deterministically: sorted keys, two-space indent, trailing newline — the exact bytes committed at SchemaPath.
func BuildJSONWithSourceRoot ¶ added in v0.19.0
BuildJSONWithSourceRoot builds the deterministic schema using only the explicitly supplied metadata source checkout. The source root is distinct from any config corpus or output root and is opened exactly once.
func Check ¶
Check inspects the schema then sorted source/twin paths using actual on-disk fragments. It never repairs or mutates on success or failure and aggregates drift, ownership, strict-reader, representation and real resolution errors.
func CheckWithSourceRoot ¶ added in v0.19.0
CheckWithSourceRoot performs the read-only Check using an explicit metadata source checkout, kept separate from the config corpus root.
func CorpusFiles ¶
CorpusFiles returns all JSON and YAML config documents below ConfigsDir. It retains the current public inventory surface independently of the stricter canonical-source/owned-twin enumeration used by artifact planning.
func ModuleRoot ¶
func ModuleRoot() string
ModuleRoot returns the apic checkout root derived only from this source file's compiled absolute location. An unavailable or trimpath-relative location returns ""; callers that build schema metadata must then use an explicit source-root API. It never falls back to the working directory.
func SourcePath ¶
SourcePath is the byte-exact inverse of TwinPath within the dedicated tree.
func ToYAMLTwin ¶
ToYAMLTwin returns deterministic YAML body bytes, retaining exact JSON scalar tokens and presence. Only direct root.schemas.<name>.$ref file imports change.
func TwinPath ¶
TwinPath maps an exact portable canonical JSON path to its owned YAML path. Invalid spellings are refused, never cleaned into an accepted source name.
func Write ¶
Write fully validates the canonical corpus, planned twins and ownership before any mutation. It returns sorted actually updated or removed artifact paths, including completed operations if an operational failure interrupts apply.
func WriteWithSourceRoot ¶ added in v0.19.0
WriteWithSourceRoot performs Write using an explicit metadata source checkout, kept separate from the config corpus/output root.
Types ¶
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator validates config documents against one compiled schema.
func LoadValidator ¶
LoadValidator compiles the committed schema (SchemaPath) under root.
func (*Validator) Validate ¶
Validate checks one JSON config document (bytes as returned by configfile.ReadFile / ToJSON) against the schema.
func (*Validator) ValidateFile ¶
ValidateFile reads a JSON or YAML config and validates it. Cross-file "$ref" stubs are validated as written (the schema permits them); resolution is not needed for shape checking.
Source Files