schema

func ApplyDefaults ¶

func ApplyDefaults(target map[string]any, structural *apiextschema.Structural) map[string]any

ApplyDefaults applies schema default values to a target object using Kubernetes defaulting logic.

This function walks the structural schema and target object in parallel, filling in default values for missing fields. The defaulting algorithm follows the same rules as Kubernetes API server defaulting for CustomResourceDefinitions.

Behavior:

• Missing fields with defaults are added
• Existing fields are not overwritten (even if they differ from the default)
• Nested objects are defaulted recursively

The target map is modified in place and also returned for convenience.

Example:

Schema: {replicas: {type: "integer", default: 1}, image: {type: "string"}}
Input:  {image: "nginx"}
Output: {image: "nginx", replicas: 1}

func ToJSONSchema ¶

func ToJSONSchema(def Definition) (*extv1.JSONSchemaProps, error)

ToJSONSchema converts a schema definition into an OpenAPI v3 JSON schema.

This is the primary entry point for converting ComponentType and Trait schemas from the shorthand format into standard JSON Schema that can be used for validation.

Process:

1. Merge all schema maps (parameters, envOverrides, trait config) into one
2. Convert from shorthand syntax to full JSON Schema via extractor
3. Sort required fields for deterministic output

Example input (shorthand):

schemas: [{replicas: "integer | default=1"}, {environment: "string"}]

Example output (JSON Schema):

{type: "object", properties: {replicas: {type: "integer", default: 1}, environment: {type: "string"}}}

func ToStructural ¶

func ToStructural(def Definition) (*apiextschema.Structural, error)

ToStructural converts the definition into a Kubernetes structural schema.

Structural schemas are a stricter variant of JSON Schema used by Kubernetes for:

1. Server-side validation of CRD instances
2. Defaulting field values based on schema defaults
3. Pruning unknown fields during admission

The conversion process:

1. Convert to standard JSON Schema (OpenAPI v3)
2. Convert from v1 to internal API version
3. Validate and convert to structural format (enforces additional constraints)

Structural schema constraints include:

• All objects must have explicit type: "object"
• All arrays must specify item schema
• No x-kubernetes-* extensions in certain contexts

This is primarily used with ApplyDefaults to populate default values.

func ValidateAgainstSchema ¶ added in v0.5.0

func ValidateAgainstSchema(values map[string]any, structural *apiextschema.Structural) error

ValidateAgainstSchema validates that provided values conform to the expected schema structure.

This function checks that all fields in the provided values exist in the schema definition and reports any unknown fields that are not defined in the schema.

Parameters:

• values: The developer-provided values to validate (typically from Component.Spec.Workflow.Schema)
• structural: The structural schema to validate against (typically from Workflow.Spec.Schema)

Returns:

• error: nil if validation passes, or an error describing which fields are invalid

Validation rules:

1. All top-level fields in values must exist in the schema properties
2. Nested object validation is performed recursively
3. Unknown fields (not defined in schema) are reported as errors

Example:

Schema defines: {repository: {url: string}, version: integer}
Valid input:    {repository: {url: "..."}, version: 1}
Invalid input:  {repository: {url: "..."}, unknownField: "x"}  // unknownField not in schema