Supported Schemas

Schema types that ChooChoo validates

ChooChoo validates the following schema types. Each is identified automatically from file content by choochoo validate.

Validation is powered by a subset of datacontract-cli for ODCS/ODPS, plus per-standard validators for OpenAPI, Arazzo, GraphQL, and AsyncAPI.

Schema Examples

ODCS — Open Data Contract Standard

Describes the schema, quality rules, and ownership of a data asset. ChooChoo validates ODCS files when choochoo validate encounters a file with apiVersion: odcs/v3 or when --schema odcs is passed.

Spec: bitol-io.github.io/open-data-contract-standard

apiVersion: odcs/v3
kind: DataContract
metadata:
  name: user-events
  owner: [email protected]
  version: "1.2.0"
spec:
  schema:
    - name: user_id
      type: string
      description: Unique user identifier
      pii: true
    - name: event_type
      type: string
      description: Category of event
  quality:
    - rule: completeness
      column: user_id
      threshold: 1.0

OpenAPI

Describes HTTP API endpoints, request/response shapes, and authentication. ChooChoo validates OpenAPI when a file contains openapi: "3.x" at the root.

Spec: spec.openapis.org/oas

openapi: "3.1.0"
info:
  title: Events API
  version: "1.0.0"
paths:
  /events:
    get:
      summary: List events
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object

AI System Card

Documents an AI agent’s identity, capabilities, limitations, and compliance alignment. ChooChoo validates System Cards when a file contains systemCardSpecification at the root. See Context Compilation for how they are used.

systemCardSpecification: "1.0.0"
info:
  id: code-review-agent
  name: Code Review Agent
  version: "2.0"
  owner: [email protected]
  description: Reviews code changes for correctness and security
intendedUse:
  - Code review and feedback
  - Security vulnerability scanning
limitations:
  - Cannot approve pull requests directly
  - No access to production secrets
compliance:
  frameworks: ["SOC 2"]

ODPS — Open Data Product Standard

Describes a data product including its inputs, outputs, SLAs, and governance metadata. ChooChoo validates ODPS when a file contains apiVersion: odps/v1.

Spec: bitol-io.github.io/open-data-product-standard

apiVersion: odps/v1
kind: DataProduct
metadata:
  name: customer-360
  owner: [email protected]
  version: "1.0.0"
spec:
  description: Unified customer profile combining CRM and event data
  inputPorts:
    - name: crm-events
      contract: contracts/crm-events.yaml
  outputPorts:
    - name: customer-profile
      schema: schemas/customer-profile.yaml
  sla:
    freshness: 1h

Arazzo

Describes multi-step API workflows that chain OpenAPI operations. ChooChoo validates Arazzo when a file contains arazzo: "1.0.0" at the root.

Spec: spec.openapis.org/arazzo

arazzo: "1.0.0"
info:
  title: User Onboarding Workflow
  version: "1.0.0"
sourceDescriptions:
  - name: eventsApi
    url: ./openapi.yaml
    type: openapi
workflows:
  - workflowId: onboard-user
    steps:
      - stepId: create-account
        operationId: $sourceDescriptions.eventsApi#/createUser
        successCriteria:
          - condition: $statusCode == 201

GraphQL SDL

Describes a GraphQL API’s type system, queries, and mutations. ChooChoo validates GraphQL SDL files (.graphql, .gql) automatically.

Spec: spec.graphql.org

type User {
  id: ID!
  email: String!
  events: [Event!]!
}

type Event {
  id: ID!
  type: String!
  timestamp: String!
}

type Query {
  user(id: ID!): User
  events(userId: ID!): [Event!]!
}

AsyncAPI

Describes event-driven APIs — message channels, schemas, and bindings for Kafka, WebSocket, and similar transports. ChooChoo validates AsyncAPI when a file contains asyncapi: "3.0.0" at the root.

Spec: asyncapi.com/docs/reference/specification/v3.0.0

asyncapi: "3.0.0"
info:
  title: User Events
  version: "1.0.0"
channels:
  userSignedUp:
    address: user.signed-up
    messages:
      userSignedUpMessage:
        payload:
          type: object
          properties:
            userId:
              type: string
            timestamp:
              type: string
              format: date-time

Forcing a Schema Type

ChooChoo auto-detects schema type from file content. To force a specific type:

choochoo validate schema.yaml --schema odcs
choochoo validate openapi.yaml --schema openapi
choochoo validate workflow.yaml --schema arazzo

Related

• Glossary — Definitions for ODPS, ODCS, Arazzo, and other terms.
• CLI Reference — Full choochoo validate documentation.
• Configuration — Pin schema versions in choochoo.toml.