Operator Native Thinking

The ONT
Schema Specification

The versioned, importable community standard that defines the contract surface for every ONT platform layer. OpenAPI JSON Schema Draft 2020-12.

v1alpha1 alpha stability Apache 2.0 JSON Schema Draft 2020-12 v1.9.3‑alpha.1
36
schemas published
4
layers
6+12+9+9
shared + seam + domain + application
Getting Started
How to import
Reference a single schema
// Any JSON Schema $ref field
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "domainIdentityRef": {
      "$ref": "https://schema.ontai.dev/v1alpha1/domain-core/DomainIdentity.json"
    }
  }
}
Fetch the full registry
GET https://schema.ontai.dev/v1alpha1/index.json

// Response shape
{
  "version": "v1alpha1",
  "stability": "alpha",
  "layers": {
    "shared":      [ /* 6 */ ],
    "domain-core": [ /* 9 */ ],
    "seam-core":   [ /* 12 */ ],
    "app-core":    [ /* 9 */ ]
  }
}
Schema index URL
https://schema.ontai.dev/v1alpha1/index.json
View index.json
Cross-schema references use structured objects: {"group":"core.ontai.dev","kind":"DomainIdentity","version":"v1alpha1","name":"..."} Never string URIs or relative paths.
Embedded types
shared
No API group. No controllers. Used as $ref targets by all layers.
6
schemas
KubernetesMetadata
Standard Kubernetes ObjectMeta. Used as a $ref target by all CRD schemas in every layer.
JSON ↗
SealedCausalChain
Immutable causal chain linking a derived object to its root declaration. All fields required and immutable after creation.
JSON ↗
BindingStability
Binding descriptor for cross-operator relationships. SnapshotBinding for point-in-time facts. ContinuousBinding for constraint assertions.
JSON ↗
PhaseModel
Eight-phase lifecycle model: ScopeEstablishment through ProfileCompletion. Used by AppProfile as the completion gate.
JSON ↗
RationaleField
Structured rationale for governance events. Lives in GovernanceEvent only, never in CRD spec fields.
JSON ↗
GovernanceEvent
Layer One and Layer Two change event with actor attribution, changeType, field changed, and optional rationale.
JSON ↗
Foundation primitives
Domain
core.ontai.dev/v1alpha1  |  Abstract domain primitives. No controllers at this layer. Seam-sdk enforces these contracts at compile time for all operators that import it.
9
schemas
DomainIdentity
Named principal with SPIFFE trust domain and ONT web subject. Root anchor for all derivation trees in the domain.
JSON ↗
DomainBoundary
Organizational scope and cluster placement authority for a domain identity. Sets the environment tier.
JSON ↗
DomainPolicy
Ceilings for retry, circuit breaker, rate limit, and cardinality. Guardian validates AppPolicy claims against these ceilings at admission.
JSON ↗
DomainRelationship
Typed directional association: signs, provisions, delegates, governs, observes, depends-on, extends. Every AppTopology wiring must reference one.
JSON ↗
DomainEvent
Event type contract with producer authority, schema version, consumer eligibility rules, and retention policy.
JSON ↗
DomainWorkflow
Lifecycle phase sequence with entry conditions, terminal states, and transition authority declaration.
JSON ↗
DomainResource
Compute and storage ceilings with Kueue resource flavor constraints. AppResourceProfile claims may not exceed these.
JSON ↗
DomainAudit
Minimum granularity floor, retention requirement, and mandatory event types for audit compliance. AppAuditPolicy may not declare below this floor.
JSON ↗
DomainSemanticNameService
DSNS zone declaration with record types and resolution tier registry. Connects the domain topology to the seam.ontave.dev semantic zone.
JSON ↗
Cross-operator schema authority
Seam
seam.ontai.dev/v1alpha1  |  Exclusive schema authority for all cross-operator CRD definitions. No operator defines CRDs that Seam owns (Decision 13, May 2026).
12
schemas
LineageRecord
Sealed causal derivation record. One per root declaration (TalosCluster or PackDelivery). Controller-authored exclusively (Decision 3). Tracks every governed descendant with CreationRationale, SeamOperator, and ActorRef on each descendantRegistry entry.
JSON ↗
TalosCluster
Root declaration for a Talos cluster under Seam governance. Declares mode (bootstrap, CAPI, or import) and role (management or tenant). Carries sealed lineage field and all day2 status conditions: NodeHealthSummary, MachineConfigSynced, VersionUpgradePending.
JSON ↗
RunnerConfig
Runtime configuration generated by Platform for a Conductor agent deployment. Operator-authored exclusively (INV-009). status.capabilities encodes the live T state in KBCL terms: the complete list of actions Conductor is currently authorized and equipped to perform.
JSON ↗
PackDelivery
Root declaration for delivering a pack to a target cluster. Drives the five-gate PackExecution lifecycle. Carries the sealed lineage field; all derived objects trace back to this root. Dispatcher reconciler creates the three-layer OCI artifact and submits delivery.
JSON ↗
PackBuild
Compiler input specification for a single pack component. Declares category (helm, kustomize, raw) and category-specific source fields. Read by Compiler at compile time only. Never applied to a cluster as a CR.
JSON ↗
PackExecution
Runtime execution attempt for a PackDelivery to a target cluster. Conductor performs a four-gate check and submits a pack-deploy Kueue Job. One PackExecution per deployment attempt per target cluster. Phase progresses through Pending, Running, Succeeded, Failed.
JSON ↗
PackInstalled
Delivered state record for a PackDelivery on a target cluster. Created after a successful pack-deploy Job completes. One PackInstalled per logical pack per target cluster. The authoritative source of truth for what is running on a cluster at any moment.
JSON ↗
PackReceipt
Immutable acknowledgement written by the target cluster Conductor. Carries an Ed25519 signature verified against the management Guardian signing key. Spec sealed after first write. phase=Acknowledged only after signature verification passes (INV-026).
JSON ↗
PackLog
Operational history record written by Conductor exec-mode after pack-deploy completes. Tracks RemediationAttempts (failure reason, attempt count, last attempt time) and provides the audit trail for the remediation escalation path defined in RemediationPolicy.
JSON ↗
MachineConfigSync
Reconciliation trigger for applying machineconfig to Talos nodes. Platform creates this CR when machineconfig source-of-truth secrets change. Conductor exec reads the secret, applies config via goclient, injects the ont-controlled node label, and updates sync-status labels on the secret.
SeamMembership
Formal operator join declaration. Declares tier (infrastructure or application) and operator identity. Written on operator startup. Validated by Guardian admission webhook before the operator is permitted to reconcile any cluster resource.
JSON ↗
DSNSZone
Semantic DNS zone with controller-authored A, TXT, SOA, NS records linked to owning resources. Powers the semantic name resolution layer for the Vortex retrieval interface. Zone records reference the lineage chain for provenance.
JSON ↗
Application contracts
Application
app.ontai.dev/v1alpha1  |  Eight-phase CRD lifecycle for community application operators. Each phase gates the next. Guardian validates claims against Domain ceiling definitions at admission.
9
schemas
AppBoundary
Phase 1. Namespace and cluster scope gate. Must reach Ready before AppIdentity creation is permitted. References DomainBoundary.
JSON ↗
AppIdentity
Phase 2. Root anchor for all sibling CRDs. Issues a SPIFFE identity on admission. All other app-core CRDs require AppIdentity to be Ready first.
JSON ↗
AppPolicy
Phase 3. Application policy bounded by DomainPolicy ceilings. Guardian validates retry, circuit breaker, and rate limit claims at admission.
JSON ↗
AppTopology
Phase 4. Named wirings to upstream and downstream services. Every wiring must reference a declared DomainRelationship. Supports SnapshotBinding and ContinuousBinding.
JSON ↗
AppEventSchema
Phase 5. Producer or consumer registration for a DomainEvent type. Schema version compatibility checked against DomainEvent declaration.
JSON ↗
AppWorkflow
Phase 6. Kueue Job bindings per workflow phase with temporal relationship declarations. References DomainWorkflow phase sequence.
JSON ↗
AppResourceProfile
Phase 7. Compute and storage claims bounded by DomainResource ceilings. Immutable after the application reaches Running state.
JSON ↗
AppAuditPolicy
Phase 7. Emitted event types and granularity. Floor enforced by Guardian against DomainAudit minimum. Cannot declare below domain floor.
JSON ↗
AppProfile
Phase 8. Aggregate root composing all eight sibling CRDs. Reaches Ready only after all phase gates complete. Terminal profile declaration for the application domain.
JSON ↗
Versioning
Stability Policy
alpha
Under active development. Breaking changes may occur between releases. Pin to a specific git commit for stability.
beta
Feature-complete. Breaking changes require a deprecation notice in CHANGELOG.md at least one release prior.
stable
Production-ready. No breaking changes without a new version directory (v1beta1, v1). Previous version maintained for six months minimum.
deprecated
Superseded. Consumers must migrate before the next major release. Deprecation listed in CHANGELOG.md with migration guidance.
All schemas in v1alpha1 carry x-ont-stability: "alpha". Contributions follow the Operator Validation Framework: specification before code, senior engineer sign-off required. See README.md for the full contribution and versioning policy.