schema

package
v0.48.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 13, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source
const RootSchemaKey = "_schema"

RootSchemaKey is the field stored on content payloads to track schema versions.

Variables

View Source
var (
	ErrUnsupportedKeyword   = errors.New("schema: unsupported keyword")
	ErrOverlayPathNotFound  = errors.New("schema: overlay path not found")
	ErrInvalidSchemaVersion = errors.New("schema: invalid schema version")
)

Functions

func ApplyMetadata

func ApplyMetadata(schema map[string]any, meta Metadata) map[string]any

ApplyMetadata updates the schema metadata object with the provided fields.

func DownlevelForValidation

func DownlevelForValidation(schema map[string]any) map[string]any

DownlevelForValidation converts Draft 2020-12 constructs to Draft-07 equivalents.

func FieldPaths added in v0.29.0

func FieldPaths(schema map[string]any) map[string]struct{}

FieldPaths returns the set of schema field paths derived from a JSON schema. The schema should be normalized (see validation.NormalizeSchema) before use.

func RegisterProjections

func RegisterProjections(ctx context.Context, registry Registry, projections []*Projection) error

RegisterProjections registers projections in the provided registry.

func ValidateSchemaSubset

func ValidateSchemaSubset(schema map[string]any) error

ValidateSchemaSubset ensures the schema only uses supported keywords.

Types

type BlockAvailability

type BlockAvailability struct {
	Allow []string
	Deny  []string
}

BlockAvailability defines allow/deny rules for block types.

func (BlockAvailability) Allows

func (b BlockAvailability) Allows(value string) bool

func (BlockAvailability) Empty

func (b BlockAvailability) Empty() bool

type BlockSchema

type BlockSchema struct {
	Name   string
	Schema map[string]any
}

BlockSchema captures a named block schema for projection.

type BreakingChange added in v0.23.0

type BreakingChange struct {
	Type        string
	Field       string
	Description string
}

BreakingChange describes a breaking schema update.

type ChangeLevel added in v0.23.0

type ChangeLevel int

ChangeLevel captures the semantic impact of a schema update.

const (
	ChangeNone ChangeLevel = iota
	ChangePatch
	ChangeMinor
	ChangeMajor
)

func (ChangeLevel) String added in v0.23.0

func (c ChangeLevel) String() string

type CompatibilityResult added in v0.23.0

type CompatibilityResult struct {
	Compatible      bool
	ChangeLevel     ChangeLevel
	BreakingChanges []BreakingChange
	Warnings        []string
}

CompatibilityResult summarizes compatibility of a schema change.

func CheckSchemaCompatibility added in v0.23.0

func CheckSchemaCompatibility(oldSchema, newSchema map[string]any) CompatibilityResult

CheckSchemaCompatibility compares schema changes for breaking updates.

type DeliveryPayload

type DeliveryPayload struct {
	Schema   map[string]any    `json:"schema"`
	Overlays []OverlayDocument `json:"overlays,omitempty"`
	Version  string            `json:"version"`
	Metadata Metadata          `json:"metadata"`
}

DeliveryPayload captures the schema output returned to admin clients.

func BuildDeliveryPayload

func BuildDeliveryPayload(ctx context.Context, schema map[string]any, opts NormalizeOptions) (DeliveryPayload, error)

BuildDeliveryPayload normalizes a schema and bundles overlays for delivery.

type FSOverlayResolver

type FSOverlayResolver struct {
	FS fs.FS
}

FSOverlayResolver resolves overlays from an fs.FS.

func (FSOverlayResolver) Resolve

Resolve loads and parses an overlay document from the provided reference.

type Metadata

type Metadata struct {
	Slug              string
	SchemaVersion     string
	UIOverlays        []string
	BlockAvailability BlockAvailability
}

Metadata captures schema-level metadata persisted alongside JSON Schema docs.

func ExtractMetadata

func ExtractMetadata(schema map[string]any) Metadata

ExtractMetadata reads the schema metadata object when present.

type MigrationFunc

type MigrationFunc func(map[string]any) (map[string]any, error)

MigrationFunc transforms a payload between schema versions.

type MigrationStep

type MigrationStep struct {
	From  string
	To    string
	Apply MigrationFunc
}

MigrationStep describes a single migration hop.

type Migrator

type Migrator struct {
	// contains filtered or unexported fields
}

Migrator manages ordered migration steps per schema slug.

func NewMigrator

func NewMigrator() *Migrator

NewMigrator constructs an empty migrator registry.

func (*Migrator) Migrate

func (m *Migrator) Migrate(slug, from, to string, payload map[string]any) (map[string]any, error)

Migrate applies migration steps until the target version is reached.

func (*Migrator) Register

func (m *Migrator) Register(slug, from, to string, fn MigrationFunc) error

Register adds a migration step for a slug.

type NormalizeOptions

type NormalizeOptions struct {
	Slug              string
	OverlayResolver   OverlayResolver
	OverlayDocuments  []OverlayDocument
	FailOnUnsupported bool
}

NormalizeOptions configures schema normalization.

type NormalizedSchema

type NormalizedSchema struct {
	Schema   map[string]any
	Metadata Metadata
	Overlays []OverlayDocument
	Version  Version
}

NormalizedSchema captures the normalized schema and associated metadata.

func NormalizeContentSchema

func NormalizeContentSchema(ctx context.Context, schema map[string]any, opts NormalizeOptions) (NormalizedSchema, error)

NormalizeContentSchema normalizes a content type schema and merges UI overlays.

type OverlayDocument

type OverlayDocument struct {
	Schema    string            `json:"$schema"`
	Overrides []OverlayOverride `json:"overrides"`
}

OverlayDocument defines UI metadata overrides applied to a schema.

type OverlayOverride

type OverlayOverride struct {
	Path     string         `json:"path"`
	XFormgen map[string]any `json:"x-formgen,omitempty"`
	XAdmin   map[string]any `json:"x-admin,omitempty"`
	UI       map[string]any `json:"ui,omitempty"`
}

OverlayOverride targets a schema path and applies UI metadata.

type OverlayResolver

type OverlayResolver interface {
	Resolve(ctx context.Context, ref string) (OverlayDocument, error)
}

OverlayResolver resolves overlay references into documents.

type Projection

type Projection struct {
	Name     string
	Document *openapi.Document
}

Projection contains an OpenAPI document projection.

func ProjectToOpenAPI

func ProjectToOpenAPI(contentSlug string, contentName string, schema map[string]any, version Version, blocks []BlockSchema) (*Projection, error)

ProjectToOpenAPI builds an OpenAPI document for the content type and blocks.

type Registry

type Registry interface {
	Register(ctx context.Context, name string, doc map[string]any) error
}

Registry represents a destination for OpenAPI schema documents.

type Version

type Version struct {
	Slug   string
	SemVer string
}

Version identifies a schema revision for a content type or block.

func BumpVersion added in v0.23.0

func BumpVersion(base Version, level ChangeLevel) (Version, error)

BumpVersion increments a semantic version by the provided change level.

func DefaultVersion

func DefaultVersion(slug string) Version

DefaultVersion builds the initial schema version for a slug.

func EnsureSchemaVersion

func EnsureSchemaVersion(schema map[string]any, slug string) (map[string]any, Version, error)

EnsureSchemaVersion ensures the schema metadata contains a valid schema_version.

func ParseVersion

func ParseVersion(value string) (Version, error)

ParseVersion parses a "<slug>@vMAJOR.MINOR.PATCH" string.

func RootSchemaVersion

func RootSchemaVersion(payload map[string]any) (Version, bool)

RootSchemaVersion reads the _schema value from a payload.

func (Version) String

func (v Version) String() string

String returns the canonical string format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL