OpenMetadata Data Contracts API

openapi: 3.0.1
info:
  title: OpenMetadata APIs Agent Executions Data Contracts API
  description: Common types and API definition for OpenMetadata
  contact:
    name: OpenMetadata
    url: https://open-metadata.org
    email: openmetadata-dev@googlegroups.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '1.13'
servers:
- url: /api
  description: Current Host
- url: http://localhost:8585/api
  description: Endpoint URL
security:
- BearerAuth: []
tags:
- name: Data Contracts
  description: '`DataContract` defines the schema and quality guarantees for a data asset.'
paths:
  /v1/dataContracts:
    get:
      tags:
      - Data Contracts
      summary: List data contracts
      description: Get a list of data contracts, optionally filtered by query parameters.
      operationId: listDataContracts
      parameters:
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      - name: limit
        in: query
        description: Limit the number of records returned in the response
        schema:
          maximum: 1000000
          minimum: 0
          type: integer
          format: int64
          example: 100
          default: 10
      - name: before
        in: query
        description: Returns list of contracts before this cursor
        schema:
          type: string
      - name: after
        in: query
        description: Returns list of contracts after this cursor
        schema:
          type: string
      - name: include
        in: query
        description: Include all, deleted, or non-deleted entities
        schema:
          type: string
          default: non-deleted
          enum:
          - all
          - deleted
          - non-deleted
      - name: status
        in: query
        description: Filter contracts by status
        schema:
          type: string
          example: Active
      - name: entity
        in: query
        description: Filter contracts by entity id
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of data contracts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContractList'
    put:
      tags:
      - Data Contracts
      summary: Create or update a data contract from YAML
      description: Create a new data contract from YAML, if it does not exist or update an existing data contract.
      operationId: createOrUpdateDataContractFromYaml
      requestBody:
        content:
          application/yaml:
            schema:
              type: string
          text/yaml:
            schema:
              type: string
      responses:
        '200':
          description: The updated data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
    post:
      tags:
      - Data Contracts
      summary: Create a data contract from YAML
      description: Create a new data contract from YAML content.
      operationId: createDataContractFromYaml
      requestBody:
        content:
          application/yaml:
            schema:
              type: string
          text/yaml:
            schema:
              type: string
      responses:
        '200':
          description: The data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '400':
          description: Bad request
  /v1/dataContracts/odcs:
    put:
      tags:
      - Data Contracts
      summary: Create or update data contract from ODCS format
      description: Create or update a data contract from Open Data Contract Standard (ODCS) v3.1.0 JSON format. Use mode=merge (default) to preserve existing fields not in the import. Use mode=replace to fully overwrite the contract while preserving ID and execution history.
      operationId: createOrUpdateDataContractFromODCS
      parameters:
      - name: entityId
        in: query
        description: Entity ID to associate with the contract
        schema:
          type: string
          format: uuid
      - name: entityType
        in: query
        description: Entity Type (table, topic, etc.)
        schema:
          type: string
          example: table
      - name: mode
        in: query
        description: 'Import mode: ''merge'' preserves existing fields, ''replace'' overwrites all fields'
        schema:
          type: string
          default: merge
          enum:
          - merge
          - replace
      - name: objectName
        in: query
        description: Schema object name to import (for multi-object ODCS contracts). If not specified, auto-selects based on entity name or uses first object.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: The created or updated data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '400':
          description: Bad request
    post:
      tags:
      - Data Contracts
      summary: Import data contract from ODCS format
      description: Import a data contract from Open Data Contract Standard (ODCS) v3.1.0 JSON format.
      operationId: importDataContractFromODCS
      parameters:
      - name: entityId
        in: query
        description: Entity ID to associate with the contract
        schema:
          type: string
          format: uuid
      - name: entityType
        in: query
        description: Entity Type (table, topic, etc.)
        schema:
          type: string
          example: table
      - name: objectName
        in: query
        description: Schema object name to import (for multi-object ODCS contracts). If not specified, auto-selects based on entity name or uses first object.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: string
      responses:
        '200':
          description: The imported data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '400':
          description: Bad request
  /v1/dataContracts/odcs/yaml:
    put:
      tags:
      - Data Contracts
      summary: Create or update data contract from ODCS YAML format
      description: Create or update a data contract from Open Data Contract Standard (ODCS) v3.1.0 YAML format. Use mode=merge (default) to preserve existing fields not in the import. Use mode=replace to fully overwrite the contract while preserving ID and execution history.
      operationId: createOrUpdateDataContractFromODCSYaml
      parameters:
      - name: entityId
        in: query
        description: Entity ID to associate with the contract
        schema:
          type: string
          format: uuid
      - name: entityType
        in: query
        description: Entity Type (table, topic, etc.)
        schema:
          type: string
          example: table
      - name: mode
        in: query
        description: 'Import mode: ''merge'' preserves existing fields, ''replace'' overwrites all fields'
        schema:
          type: string
          default: merge
          enum:
          - merge
          - replace
      - name: objectName
        in: query
        description: Schema object name to import (for multi-object ODCS contracts). If not specified, auto-selects based on entity name or uses first object.
        schema:
          type: string
      requestBody:
        content:
          application/yaml:
            schema:
              type: string
          text/yaml:
            schema:
              type: string
      responses:
        '200':
          description: The created or updated data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '400':
          description: Bad request
    post:
      tags:
      - Data Contracts
      summary: Import data contract from ODCS YAML format
      description: Import a data contract from Open Data Contract Standard (ODCS) v3.1.0 YAML format.
      operationId: importDataContractFromODCSYaml
      parameters:
      - name: entityId
        in: query
        description: Entity ID to associate with the contract
        schema:
          type: string
          format: uuid
      - name: entityType
        in: query
        description: Entity Type (table, topic, etc.)
        schema:
          type: string
          example: table
      - name: objectName
        in: query
        description: Schema object name to import (for multi-object ODCS contracts). If not specified, auto-selects based on entity name or uses first object.
        schema:
          type: string
      requestBody:
        content:
          application/yaml:
            schema:
              type: string
          text/yaml:
            schema:
              type: string
      responses:
        '200':
          description: The imported data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '400':
          description: Bad request
  /v1/dataContracts/{id}/results:
    get:
      tags:
      - Data Contracts
      summary: List data contract results
      description: Get a list of all data contract execution results for a given contract.
      operationId: listDataContractResults
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: Limit the number of results (1 to 10000, default = 10)
        schema:
          maximum: 10000
          minimum: 0
          type: integer
          format: int32
          default: 10
      - name: startTs
        in: query
        description: Returns results after this timestamp
        schema:
          type: number
      - name: endTs
        in: query
        description: Returns results before this timestamp
        schema:
          type: number
      responses:
        '200':
          description: List of data contract results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultList'
    put:
      tags:
      - Data Contracts
      summary: Create or update data contract result
      description: Create a new data contract execution result.
      operationId: createOrUpdateDataContractResult
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataContractResult'
          application/yaml:
            schema:
              $ref: '#/components/schemas/DataContractResult'
          text/yaml:
            schema:
              $ref: '#/components/schemas/DataContractResult'
      responses:
        '200':
          description: Successfully created or updated the result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContractResult'
  /v1/dataContracts/{id}:
    get:
      tags:
      - Data Contracts
      summary: Get a data contract by id
      description: Get a data contract by `id`.
      operationId: getDataContractByID
      parameters:
      - name: id
        in: path
        description: Data contract Id
        required: true
        schema:
          type: string
          format: uuid
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      - name: include
        in: query
        description: Include all, deleted, or non-deleted entities
        schema:
          type: string
          default: non-deleted
          enum:
          - all
          - deleted
          - non-deleted
      - name: includeRelations
        in: query
        description: 'Per-relation include control. Format: field:value,field2:value2. Example: owners:non-deleted,followers:all. Valid values: all, deleted, non-deleted. If not specified for a field, uses the entity''s include value.'
        schema:
          type: string
          example: owners:non-deleted,followers:all
      responses:
        '200':
          description: The data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '404':
          description: Data contract for instance {id} is not found
    delete:
      tags:
      - Data Contracts
      summary: Delete a data contract by id
      description: Delete a data contract by `id`.
      operationId: deleteDataContract
      parameters:
      - name: hardDelete
        in: query
        description: Hard delete the entity
        schema:
          type: boolean
          default: false
      - name: recursive
        in: query
        description: Recursively delete this entity and it's children. (Default `false`)
        schema:
          type: boolean
          default: false
      - name: id
        in: path
        description: Data contract Id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
        '404':
          description: Data contract for instance {id} is not found
    patch:
      tags:
      - Data Contracts
      summary: Update a data contract
      description: Update an existing data contract using JsonPatch.
      externalDocs:
        description: JsonPatch RFC
        url: https://tools.ietf.org/html/rfc6902
      operationId: patchDataContract
      parameters:
      - name: id
        in: path
        description: Data contract Id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: JsonPatch with array of operations
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/JsonPatch'
            example: '[{op:remove, path:/a},{op:add, path: /b, value: val}]'
      responses:
        default:
          description: default response
          content:
            application/json: {}
  /v1/dataContracts/async/{id}:
    delete:
      tags:
      - Data Contracts
      summary: Delete a data contract by id asynchronously
      description: Delete a data contract by `id` asynchronously.
      operationId: deleteDataContractAsync
      parameters:
      - name: hardDelete
        in: query
        description: Hard delete the entity
        schema:
          type: boolean
          default: false
      - name: recursive
        in: query
        description: Recursively delete this entity and it's children. (Default `false`)
        schema:
          type: boolean
          default: false
      - name: id
        in: path
        description: Data contract Id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
        '404':
          description: Data contract for instance {id} is not found
  /v1/dataContracts/name/{fqn}:
    get:
      tags:
      - Data Contracts
      summary: Get a data contract by fully qualified name
      description: Get a data contract by `fullyQualifiedName`.
      operationId: getDataContractByFQN
      parameters:
      - name: fqn
        in: path
        description: Fully qualified name of the data contract
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      - name: include
        in: query
        description: Include all, deleted, or non-deleted entities
        schema:
          type: string
          default: non-deleted
          enum:
          - all
          - deleted
          - non-deleted
      - name: includeRelations
        in: query
        description: 'Per-relation include control. Format: field:value,field2:value2. Example: owners:non-deleted,followers:all. Valid values: all, deleted, non-deleted. If not specified for a field, uses the entity''s include value.'
        schema:
          type: string
          example: owners:non-deleted,followers:all
      responses:
        '200':
          description: The data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '404':
          description: Data contract for instance {fqn} is not found
    delete:
      tags:
      - Data Contracts
      summary: Delete a data contract by fully qualified name
      description: Delete a data contract by `fullyQualifiedName`.
      operationId: deleteDataContractByName
      parameters:
      - name: hardDelete
        in: query
        description: Hard delete the entity
        schema:
          type: boolean
          default: false
      - name: recursive
        in: query
        description: Recursively delete this entity and it's children. (Default `false`)
        schema:
          type: boolean
          default: false
      - name: fqn
        in: path
        description: Fully qualified name of the data contract
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
        '404':
          description: Data contract for instance {fqn} is not found
  /v1/dataContracts/{id}/results/{timestamp}:
    delete:
      tags:
      - Data Contracts
      summary: Delete data contract result
      description: Delete a data contract result at a specific timestamp.
      operationId: deleteDataContractResult
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      - name: timestamp
        in: path
        description: Timestamp of the result to delete
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Successfully deleted the result
  /v1/dataContracts/{id}/results/before/{timestamp}:
    delete:
      tags:
      - Data Contracts
      summary: Delete data contract results before timestamp
      description: Delete all data contract results before a specific timestamp.
      operationId: deleteDataContractResultsBefore
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      - name: timestamp
        in: path
        description: Delete results before this timestamp
        required: true
        schema:
          type: number
      responses:
        '200':
          description: Successfully deleted the results
  /v1/dataContracts/{id}/odcs:
    get:
      tags:
      - Data Contracts
      summary: Export data contract to ODCS format
      description: Export a data contract to Open Data Contract Standard (ODCS) v3.1.0 format.
      operationId: exportDataContractToODCS
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      responses:
        '200':
          description: ODCS data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODCSDataContract'
        '404':
          description: Data contract not found
  /v1/dataContracts/name/{fqn}/odcs:
    get:
      tags:
      - Data Contracts
      summary: Export data contract to ODCS format by FQN
      description: Export a data contract to Open Data Contract Standard (ODCS) v3.1.0 format by fully qualified name.
      operationId: exportDataContractToODCSByFQN
      parameters:
      - name: fqn
        in: path
        description: Fully qualified name of the data contract
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      responses:
        '200':
          description: ODCS data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODCSDataContract'
        '404':
          description: Data contract not found
  /v1/dataContracts/{id}/odcs/yaml:
    get:
      tags:
      - Data Contracts
      summary: Export data contract to ODCS YAML format
      description: Export a data contract to Open Data Contract Standard (ODCS) v3.1.0 YAML format.
      operationId: exportDataContractToODCSYaml
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      responses:
        '200':
          description: ODCS data contract in YAML format
          content:
            application/yaml: {}
        '404':
          description: Data contract not found
  /v1/dataContracts/name/{fqn}/odcs/yaml:
    get:
      tags:
      - Data Contracts
      summary: Export data contract to ODCS YAML format by FQN
      description: Export a data contract to Open Data Contract Standard (ODCS) v3.1.0 YAML format by fully qualified name.
      operationId: exportDataContractToODCSYamlByFQN
      parameters:
      - name: fqn
        in: path
        description: Fully qualified name of the data contract
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      responses:
        '200':
          description: ODCS data contract in YAML format
          content:
            application/yaml:
              schema:
                type: string
        '404':
          description: Data contract not found
  /v1/dataContracts/entity:
    get:
      tags:
      - Data Contracts
      summary: Get the effective data contract for an entity
      description: Get the effective data contract for an entity, including inherited contract properties from its data product if applicable.
      operationId: getDataContractByEntityId
      parameters:
      - name: entityId
        in: query
        description: ID of the related Entity
        schema:
          type: string
      - name: entityType
        in: query
        description: Entity Type to get the data contract for
        schema:
          type: string
          example: table
      - name: fields
        in: query
        description: Fields requested in the returned resource
        schema:
          type: string
          example: owners,reviewers,extension
      responses:
        '200':
          description: The effective data contract (may include inherited properties)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '404':
          description: Data contract for instance {id} is not found
  /v1/dataContracts/{id}/results/latest:
    get:
      tags:
      - Data Contracts
      summary: Get latest data contract result
      description: Get the latest execution result for a data contract.
      operationId: getLatestDataContractResult
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Latest data contract result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContractResult'
        '404':
          description: Data contract or result not found
  /v1/dataContracts/{id}/results/{resultId}:
    get:
      tags:
      - Data Contracts
      summary: Get a data contract result by ID
      description: Get a specific data contract execution result by its ID.
      operationId: getDataContractResult
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      - name: resultId
        in: path
        description: Id of the data contract result
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Data contract result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContractResult'
        '404':
          description: Data contract result not found
  /v1/dataContracts/{id}/versions/{version}:
    get:
      tags:
      - Data Contracts
      summary: Get a version of a data contract
      description: Get a version of a data contract by given `id`
      operationId: getDataContractVersion
      parameters:
      - name: id
        in: path
        description: Data contract Id
        required: true
        schema:
          type: string
          format: uuid
      - name: version
        in: path
        description: Data contract version number in the form `major`.`minor`
        required: true
        schema:
          type: string
          example: 0.1 or 1.1
      responses:
        '200':
          description: Data contract
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
        '404':
          description: Data contract for instance {id} and version {version} is not found
  /v1/dataContracts/history:
    get:
      tags:
      - Data Contracts
      summary: List all entity versions within a time range
      description: 'Get a paginated list of all entity versions within a given time range specified by `startTs` and `endTs` in milliseconds since epoch. '
      operationId: listAllEntityVersionsByTimestamp_12
      parameters:
      - name: startTs
        in: query
        description: Start timestamp in milliseconds since epoch
        required: true
        schema:
          type: integer
          format: int64
      - name: endTs
        in: query
        description: End timestamp in milliseconds since epoch
        required: true
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: Limit the number of entity returned (1 to 1000000, default = 10)
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
          default: 10
      - name: before
        in: query
        description: Returns list of entity versions before this cursor
        schema:
          type: string
      - name: after
        in: query
        description: Returns list of entity versions after this cursor
        schema:
          type: string
      responses:
        '200':
          description: List of all versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultList'
  /v1/dataContracts/{id}/versions:
    get:
      tags:
      - Data Contracts
      summary: List all versions of a data contract
      description: Get a list of all the versions of a data contract identified by `id`
      operationId: listDataContractVersions
      parameters:
      - name: id
        in: path
        description: Data contract Id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of data contract versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityHistory'
  /v1/dataContracts/odcs/parse/yaml:
    post:
      tags:
      - Data Contracts
      summary: Parse ODCS YAML and return metadata
      description: Parse an ODCS YAML contract and return metadata including the list of schema objects. Use this to determine available objects for multi-object contracts before importing.
      operationId: parseODCSYaml
      requestBody:
        content:
          application/yaml:
            schema:
              type: string
          text/yaml:
            schema:
              type: string
      responses:
        '200':
          description: Parsed ODCS metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ODCSParseResult'
        '400':
          description: Invalid YAML content
  /v1/dataContracts/restore:
    put:
      tags:
      - Data Contracts
      summary: Restore a soft deleted data contract
      description: Restore a soft deleted data contract.
      operationId: restore_11
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreEntity'
          application/yaml:
            schema:
              $ref: '#/components/schemas/RestoreEntity'
          text/yaml:
            schema:
              $ref: '#/components/schemas/RestoreEntity'
      responses:
        '200':
          description: 'Successfully restored the DataContract '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContract'
  /v1/dataContracts/{id}/validate:
    post:
      tags:
      - Data Contracts
      summary: Validate a data contract
      description: Execute on-demand validation of a data contract including semantic rules, quality tests, and inherited contract properties from data products.
      operationId: validateDataContract
      parameters:
      - name: id
        in: path
        description: Id of the data contract
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContractResult'
        '404':
          description: Data contract not found
  /v1/dataContracts/entity/validate:
    post:
      tags:
      - Data Contracts
      summary: Validate a data contract for an entity
      description: Execute on-demand validation of a data contract for an entity. If the entity only has an inherited contract from a Data Product, an empty contract will be materialized for the entity to store validation results.
      operationId: validateDataContractByEntityId
      parameters:
      - name: entityId
        in: query
        description: ID of the entity
        schema:
          type: string
          format: uuid
      - name: entityType
        in: query
        description: Type of the entity
        schema:
          type: string
      responses:
        '200':
          description: Validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataContractResult'
        '404':
          description: Entity not found or no contract available
  /v1/dataContracts/validate:
    post:
      tags:
      - Data Contracts
      summary: Validate data contract request without creating
      description: Validate a CreateDataContract request against the target entity without cre

# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openmetadata/refs/heads/main/openapi/openmetadata-data-contracts-api-openapi.yml