ONT OpenAPI JSON Schema: v1alpha1

The versioned, importable community standard for the ONT platform API surface. Published at ontai.dev/schema/v1alpha1.

---

What This Is

This repository contains the ONT OpenAPI JSON Schema specification: a complete, versioned definition of every CRD and reusable type in the ONT platform stack.

The schema covers four layers:

• shared: Reusable types embedded in CRD specs (SealedCausalChain, BindingStability, PhaseModel, RationaleField, GovernanceEvent, KubernetesMetadata).
• domain-core: Layer 0 abstract domain primitives under core.ontai.dev (DomainIdentity, DomainBoundary, DomainPolicy, DomainRelationship, DomainEvent, DomainWorkflow, DomainResource, DomainAudit, DomainSemanticNameService).
• seam-core: Infrastructure domain CRDs under infrastructure.ontai.dev (InfrastructureLineageIndex, InfrastructureTalosCluster, InfrastructureRunnerConfig, InfrastructurePackReceipt, InfrastructureClusterPack, InfrastructurePackExecution, InfrastructurePackInstance, InfrastructurePackBuild, DriftSignal, InfrastructurePolicy, InfrastructureProfile, SeamMembership, DSNSZone). Supersedes infra.ontai.dev (ClusterPack, PackExecution, PackInstance, PackBuild), runner.ontai.dev (RunnerConfig, PackReceipt), and platform.ontai.dev/TalosCluster. Migration complete Phase 2B, 2026-04-25.
• app-core: Application layer CRDs under app.ontai.dev (AppBoundary, AppIdentity, AppPolicy, AppTopology, AppEventSchema, AppWorkflow, AppResourceProfile, AppAuditPolicy, AppProfile).

This is a publication artifact, not an implementation artifact. Community operators import individual schemas or the full index to validate instances, generate clients, or declare compatibility.

---

How to Import

Import a single schema

Reference any schema by its $id URI in another JSON Schema document:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "domainIdentityRef": {
      "$ref": "https://schema.ontai.dev/v1alpha1/domain-core/DomainIdentity.json"
    }
  }
}

Import the full index

The index document is not a JSON Schema; it is a registry of all schemas in this release. Load it to enumerate available schemas and resolve file paths:

GET https://schema.ontai.dev/v1alpha1/index.json

The index has the following shape:

{
  "version": "v1alpha1",
  "publishedAt": "2026-04-18",
  "stability": "alpha",
  "layers": {
    "shared": [ { "kind": "...", "file": "...", "stability": "...", "description": "...", "dependsOn": [] } ],
    "domain-core": [ ... ],
    "seam-core": [ ... ],
    "app-core": [ ... ]
  }
}

Each file path is relative to v1alpha1/.

---

Layer Overview

Layer	API Group	Description
shared	(reusable types)	Embedded types used by CRDs in all layers
domain-core	core.ontai.dev/v1alpha1	Layer 0 abstract domain primitives, no controllers
seam-core	infrastructure.ontai.dev/v1alpha1	All cross-operator CRDs managed by Seam operators (Decision G). Supersedes infra.ontai.dev and runner.ontai.dev.
app-core	app.ontai.dev/v1alpha1	Application layer CRDs for community operators

Cross-layer references always follow the dependency direction:

app-core -> seam-core -> domain-core -> shared
                      ^
                      domain-core

No schema may reference a layer above itself in this hierarchy.

---

Stability Policy

Every schema carries an x-ont-stability extension field:

Value	Meaning
alpha	Schema is under active development. Breaking changes may occur.
beta	Schema is feature-complete. Breaking changes require deprecation notice.
stable	Schema is production-ready. No breaking changes without a major version.
deprecated	Schema is superseded. Consumers must migrate before the next major.

All schemas in v1alpha1 carry "x-ont-stability": "alpha".

---

Contribution Model

Community operators that wish to register a new domain CRD schema follow this process:

1. Fork this repository.
2. Create a new schema file under the appropriate layer directory following the structure defined in the existing schemas. Every schema must include:
   • $schema, $id, title, description
   • x-ont-layer, x-ont-stability, x-ont-depends-on
   • type: object with required, properties, and additionalProperties: false
   • A metadata property using $ref to shared/KubernetesMetadata.json
3. Reference only schemas that exist in this release. No forward references.
4. Add an entry to v1alpha1/index.json in the appropriate layer array.
5. Validate every new and modified schema file against JSON Schema Draft 2020-12 using ajv --spec=draft2020 or equivalent before submitting.
6. Submit a pull request. The pull request requires sign-off from a senior engineer in the ONT platform team validation framework before merge.

New rationale vocabulary values for SealedCausalChain.creationRationale require a Pull Request to the seam-core repository (pkg/lineage/rationale.go) and Platform Governor review. The vocabulary in this schema is generated from that enumeration and updated in sync.

---

Versioning Policy

• Schema versions follow the Kubernetes API versioning convention: v1alpha1, v1beta1, v1.
• A new version directory (v1beta1/) is introduced when any schema reaches beta stability.
• Within a version, new optional fields may be added without a version bump.
• Any field removal, type change, or required field addition requires a new version.
• The index.json at each version root is the stable entry point for that version.

License

Apache License 2.0. See LICENSE for the full text.

You may use, modify, and distribute these schemas for any purpose including commercial use. You must include the original copyright notice and state any changes you make. You may not use the ONT project name or contributors names to endorse derived products.

Versioning Policy

Schemas marked x-ont-stability: "alpha" may change without notice between patch releases. Pin to a specific git commit if you need stability.

When a schema advances to "beta", changes require a deprecation notice in CHANGELOG.md at least one release before removal.

When a schema advances to "stable", changes require a new version directory (v1beta1, v1) and the previous version is maintained for at least six months.

Community

ONT is open source under the Apache 2.0 license. To contribute a schema for a new domain CRD:

1. Fork this repository
2. Add your schema file under v1alpha1/{your-layer}/
3. Follow the four-part schema structure defined in this README
4. Reference only existing shared/ and domain-core/ schemas
5. Add your schema to v1alpha1/index.json
6. Include a senior engineer sign-off in the pull request description confirming the schema correctly represents the domain knowledge
7. Submit a pull request

Community schemas that represent real production domains are the highest-value contributions. See the ONT Operator Validation Framework at ontai.dev for the sign-off process.

Schema Browser

Visit https://schema.ontai.dev to browse the schema index in a human-readable format.