Kernel Subsystems — Core Engines
Docs » Kernel Subsystems — Core Engines » Validation Package
Raw .md

Validation Package

This package provides object validation for zqk: instance validation (schema, lifecycle, semantic types), ID validation (prefixes and patterns), and async validation with a queue and worker pool.

Overview

  • Validator interface: Pluggable validators (Go, SHACL, custom) via Validator, ValidatorRegistry, ValidationOptions, and ValidationResult.
  • Go validator: SHACL-inspired Go-based validator (go_validator.go, field_validators.go, type_validator.go) used by default.
  • ID validator: Validates object IDs against configurable prefixes and patterns; loads config from file or graph (id_validator*.go, id_prefixes_config.go, namespaces_config.go).
  • Instance validator: Lifecycle and state transition validation (instance_validator.go).
  • Async validator: Queue-based validation with workers, cache, and configurable timeouts (async_validator*.go, validation_timeout_config.go).
  • Tier and timeout config: Validation tiers and per-object timeouts via config/zqk.yaml (validation_tier_config.go, validation_timeout_config.go).
  • Ontology and namespace: Registry and discovery for ontologies and namespaces (ontology_registry.go, namespace_registry.go, namespace_discovery.go).

Usage

import "github.com/zqk-os/zqk/pkg/validation"

// Sync validation via registry
registry := validation.NewValidatorRegistry()
v, _ := registry.Get("go")
result, err := v.Validate(ctx, obj, kind, validation.DefaultValidationOptions())

// ID validation (global instance)
idVal := validation.GetIDValidator()
err := idVal.ValidateID(ctx, id, kind, nil)

// Async validation (enqueue and process via scheduler/coordinator)
asyncVal := validation.GetAsyncValidator()
asyncVal.Enqueue(ctx, task)

Validation patterns

  • Pluggable validators: Implement Validator and register via ValidatorRegistry; use ValidationOptions and ValidationResult for consistent results.
  • Shared field helpers (field_validators.go): Use ValidateRequiredField (required + optional empty-collection check) and ValidateEnumField (allowed values, case-insensitive for strings) so all validators behave consistently.
  • Sync vs async: Use sync validation (registry + Validate) for inline checks (e.g. CLI, single object); use async validator (Enqueue + workers) for batch or storage-layer validation with timeouts and caching.
  • Instance + ID: Instance validator handles lifecycle/state; ID validator handles prefixes/patterns from config. Both are used by storage on write.

Configuration

  • ID prefixes and namespaces: .zqk/specs/configs/id_prefixes_config.yaml, namespaces config; see id_prefixes_config.go, namespaces_config.go.
  • Validation tiers: validation_tier_config.go; tier overrides per kind.
  • Per-object timeout: config/zqk.yaml validation.per_object_timeout (default_seconds 5, empty kind_overrides by default — fail-fast); see validation_timeout_config.go. stuck_timeout_seconds default 30.
  • Async validator timeouts and buffer: AsyncValidatorConfig in async_validator_config.go — WorkerStopTimeout (default 60s), CacheSaveTimeout (default 20s), ProgressChannelSize (default 10000). Pass as optional last arg to NewAsyncValidator(..., opts...) to override.