Apicurio Contracts API

openapi: 3.1.0
info:
  title: Apicurio Registry Admin Contracts API
  version: 3.1.x
  description: Apicurio Registry is a high-performance, runtime registry for schemas and API designs. It stores and manages OpenAPI, AsyncAPI, Avro, JSON Schema, Protobuf, and other artifact types, providing a REST API for schema management with compatibility checking and content versioning.
  contact:
    name: Apicurio
    url: https://www.apicur.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/apis/registry/v3
  description: Local Apicurio Registry
tags:
- name: Contracts
paths:
  /admin/contracts/ruleset:
    summary: Manage the global contract ruleset.
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractRuleSet'
          description: The global contract ruleset.
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getGlobalContractRuleset
      summary: Get global contract ruleset
      description: Returns the global contract ruleset that applies to all artifacts.
    put:
      tags:
      - Contracts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractRuleSet'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractRuleSet'
          description: The global contract ruleset was set.
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: setGlobalContractRuleset
      summary: Set global contract ruleset
      description: Sets the global contract ruleset that applies to all artifacts.
    delete:
      tags:
      - Contracts
      responses:
        '204':
          description: The global contract ruleset was deleted.
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: deleteGlobalContractRuleset
      summary: Delete global contract ruleset
      description: Deletes the global contract ruleset.
  /search/contract/rules:
    summary: Search for contract rules by tag.
    get:
      tags:
      - Contracts
      parameters:
      - name: tag
        description: The tag value to search for in contract rules.
        schema:
          type: string
        in: query
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContractRuleSearchResult'
          description: A list of contract rules matching the specified tag, with their artifact coordinates.
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: searchContractRulesByTag
      summary: Search contract rules by tag
      description: Returns all contract rules across all artifacts that contain the specified tag.
  /search/contracts:
    summary: Search for contracts.
    get:
      tags:
      - Contracts
      parameters:
      - name: status
        description: Filter by contract status (DRAFT, STABLE, DEPRECATED).
        schema:
          type: string
        in: query
        required: false
      - name: ownerTeam
        description: Filter by owner team.
        schema:
          type: string
        in: query
        required: false
      - name: compatibilityGroup
        description: Filter by compatibility group.
        schema:
          type: string
        in: query
        required: false
      - name: offset
        description: Number of results to skip.
        schema:
          type: integer
          default: 0
        in: query
        required: false
      - name: limit
        description: Maximum number of results to return.
        schema:
          type: integer
          default: 20
        in: query
        required: false
      - name: order
        description: Sort order (asc or desc).
        schema:
          type: string
          enum:
          - asc
          - desc
        in: query
        required: false
      - name: orderby
        description: Field to sort by.
        schema:
          type: string
          enum:
          - name
          - createdOn
          - modifiedOn
        in: query
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactSearchResults'
          description: A paginated list of artifacts that have contract metadata.
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: searchContracts
      summary: Search contracts
      description: Searches for artifacts that have contract metadata labels. Filters by status, owner team, and compatibility group.
  /groups/{groupId}/artifacts/{artifactId}/contract/metadata:
    summary: Manage contract metadata for an artifact.
    parameters:
    - name: groupId
      description: The artifact group ID.
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractMetadata'
          description: The contract metadata for the artifact.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getContractMetadata
      summary: Get contract metadata
      description: Returns the contract metadata for an artifact, projected from its labels.
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditableContractMetadata'
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractMetadata'
          description: The updated contract metadata.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: updateContractMetadata
      summary: Update contract metadata
      description: Creates or updates the contract metadata for an artifact.
  /groups/{groupId}/artifacts/{artifactId}/contract/status:
    summary: Transition the contract lifecycle status.
    parameters:
    - name: groupId
      description: The artifact group ID.
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.
      schema:
        type: string
      in: path
      required: true
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractStatusTransition'
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractMetadata'
          description: The updated contract metadata after the status transition.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: transitionContractStatus
      summary: Transition contract status
      description: 'Transitions the contract status. Valid transitions: DRAFT to STABLE, DRAFT to DEPRECATED, STABLE to DEPRECATED. Reverse transitions are not allowed.'
  /groups/{groupId}/artifacts/{artifactId}/contract/ruleset:
    summary: Manage contract ruleset for an artifact (artifact-level).
    parameters:
    - name: groupId
      description: The artifact group ID.
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractRuleSet'
          description: The contract ruleset for the artifact.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getArtifactContractRuleset
      summary: Get artifact contract ruleset
      description: Returns the contract ruleset for the artifact (artifact-level rules that apply to all versions).
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractRuleSet'
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractRuleSet'
          description: The updated contract ruleset.
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: setArtifactContractRuleset
      summary: Set artifact contract ruleset
      description: Creates or replaces the contract ruleset for the artifact.
    delete:
      tags:
      - Contracts
      responses:
        '204':
          description: The contract ruleset was deleted.
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: deleteArtifactContractRuleset
      summary: Delete artifact contract ruleset
      description: Deletes the contract ruleset for the artifact.
  /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/contract/ruleset:
    summary: Manage contract ruleset for a specific artifact version.
    parameters:
    - name: groupId
      description: The artifact group ID.
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.
      schema:
        type: string
      in: path
      required: true
    - name: versionExpression
      description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern."
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractRuleSet'
          description: The contract ruleset for the version.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getVersionContractRuleset
      summary: Get version contract ruleset
      description: Returns the contract ruleset for a specific artifact version.
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractRuleSet'
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractRuleSet'
          description: The updated contract ruleset.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: setVersionContractRuleset
      summary: Set version contract ruleset
      description: Creates or replaces the contract ruleset for a specific version.
    delete:
      tags:
      - Contracts
      responses:
        '204':
          description: The contract ruleset was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: deleteVersionContractRuleset
      summary: Delete version contract ruleset
      description: Deletes the contract ruleset for a specific version.
  /groups/{groupId}/contracts:
    summary: Manage ODCS data contracts within a group.
    parameters:
    - name: groupId
      description: The group ID.
      schema:
        type: string
      in: path
      required: true
    post:
      requestBody:
        content:
          application/x-yaml:
            schema:
              type: string
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OdcsContractResult'
          description: The contract was created (or updated if it already exists) and projected onto the referenced schema artifact.
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: submitContract
      summary: Submit an ODCS contract
      description: Submits an ODCS v3.1 YAML contract. The contract is parsed, stored as an ODCS_CONTRACT artifact, and its contents are projected onto the referenced schema artifact (labels, rules, field tags).
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OdcsContractSummary'
          description: List of ODCS contracts in the group.
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: listContracts
      summary: List ODCS contracts
      description: Returns ODCS contracts in the specified group with pagination.
      parameters:
      - name: limit
        description: Maximum number of contracts to return (default 20, max 500).
        schema:
          type: integer
          format: int32
        in: query
      - name: offset
        description: Number of contracts to skip (for pagination).
        schema:
          type: integer
          format: int32
        in: query
  /groups/{groupId}/contracts/{contractId}:
    summary: Manage a specific ODCS contract.
    parameters:
    - name: groupId
      description: The group ID.
      schema:
        type: string
      in: path
      required: true
    - name: contractId
      description: The contract ID.
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/x-yaml:
              schema:
                type: string
          description: The ODCS contract YAML.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getContract
      summary: Get an ODCS contract
      description: Returns the ODCS contract YAML for the specified contract.
    put:
      requestBody:
        content:
          application/x-yaml:
            schema:
              type: string
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OdcsContractResult'
          description: The contract was updated and re-projected.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: updateContract
      summary: Update an ODCS contract
      description: Updates an ODCS contract (creates a new version) and re-projects onto the referenced schema artifact.
    delete:
      tags:
      - Contracts
      responses:
        '204':
          description: The contract was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: deleteContract
      summary: Delete an ODCS contract
      description: Deletes the ODCS contract artifact.
  /groups/{groupId}/artifacts/{artifactId}/contract/export:
    summary: Export contract metadata, rules, and field tags as ODCS YAML.
    parameters:
    - name: groupId
      description: The artifact group ID.
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/x-yaml:
              schema:
                type: string
          description: The reconstructed ODCS contract YAML.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: exportContractAsOdcs
      summary: Export as ODCS
      description: Reconstructs an ODCS v3.1 YAML contract from the artifact's current contract.* labels, contract rules, and field-tag.* version labels.
  /groups/{groupId}/artifacts/{artifactId}/contract/promote:
    summary: Promote a contract to the next deployment stage.
    parameters:
    - name: groupId
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      schema:
        type: string
      in: path
      required: true
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                contractId:
                  type: string
                targetStage:
                  type: string
                  enum:
                  - DEV
                  - STAGE
                  - PROD
              required:
              - contractId
              - targetStage
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  stage:
                    type: string
          description: The contract was promoted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: promoteContract
      summary: Promote contract stage
      description: Promotes a contract to the next deployment stage (DEV -> STAGE -> PROD).
  /groups/{groupId}/artifacts/{artifactId}/contract/quality:
    summary: Get quality score for a contract.
    parameters:
    - name: groupId
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  overall:
                    type: number
                    format: float
                  completeness:
                    type: number
                    format: float
                  compliance:
                    type: number
                    format: float
                  stability:
                    type: number
                    format: float
          description: The quality score.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getContractQuality
      summary: Get quality score
      description: Returns the quality score for a contract, with breakdown by completeness, compliance, and stability.
      parameters:
      - name: contractId
        schema:
          type: string
        in: query
        required: true
  /groups/{groupId}/artifacts/{artifactId}/contract/audit:
    summary: Get the contract audit log for an artifact.
    parameters:
    - name: groupId
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      parameters:
      - name: offset
        schema:
          type: integer
          default: 0
        in: query
        required: false
      - name: limit
        schema:
          type: integer
          default: 20
        in: query
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    auditId:
                      type: integer
                    groupId:
                      type: string
                    artifactId:
                      type: string
                    version:
                      type: string
                    action:
                      type: string
                    principal:
                      type: string
                    details:
                      type: string
                    createdOn:
                      type: string
                      format: date-time
          description: The audit log entries.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getContractAuditLog
      summary: Get contract audit log
      description: Returns a paginated audit log of contract operations for the specified artifact.
  /groups/{groupId}/artifacts/{artifactId}/contract/compatibility-group:
    summary: Manage the compatibility group for an artifact's contract.
    parameters:
    - name: groupId
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      schema:
        type: string
      in: path
      required: true
    get:
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  compatibilityGroup:
                    type: string
          description: The compatibility group.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: getCompatibilityGroup
      summary: Get compatibility group
      description: Returns the compatibility group for the artifact's contract.
      parameters:
      - name: contractId
        schema:
          type: string
        in: query
        required: true
    put:
      tags:
      - Contracts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                contractId:
                  type: string
                compatibilityGroup:
                  type: string
              required:
              - contractId
              - compatibilityGroup
        required: true
      responses:
        '204':
          description: Compatibility group updated.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: setCompatibilityGroup
      summary: Set compatibility group
      description: Sets the compatibility group for the artifact's contract.
  /groups/{groupId}/artifacts/{artifactId}/contract/migrate:
    summary: Execute migration rules to transform a record between versions.
    parameters:
    - name: groupId
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      schema:
        type: string
      in: path
      required: true
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fromVersion:
                  type: string
                toVersion:
                  type: string
                record:
                  type: object
                  additionalProperties: true
              required:
              - fromVersion
              - toVersion
              - record
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  passed:
                    type: boolean
                  transformedRecord:
                    type: object
                    additionalProperties: true
                  violations:
                    type: array
                    items:
                      type: object
                      properties:
                        ruleName:
                          type: string
                        message:
                          type: string
                        action:
                          type: string
                  executedRules:
                    type: integer
                  failedRules:
                    type: integer
          description: The migration result.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: migrateContractRecord
      summary: Migrate record between versions
      description: Executes migration rules to transform a record from one schema version to another, chaining transforms across version hops.
  /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/contract/execute:
    summary: Execute contract rules against a data record.
    parameters:
    - name: groupId
      schema:
        type: string
      in: path
      required: true
    - name: artifactId
      schema:
        type: string
      in: path
      required: true
    - name: versionExpression
      schema:
        type: string
      in: path
      required: true
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                  - WRITE
                  - READ
                record:
                  type: object
                  additionalProperties: true
              required:
              - mode
              - record
        required: true
      tags:
      - Contracts
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  passed:
                    type: boolean
                  transformedRecord:
                    type: object
                    additionalProperties: true
                  violations:
                    type: array
                    items:
                      type: object
                      properties:
                        ruleName:
                          type: string
                        message:
                          type: string
                        action:
                          type: string
                  executedRules:
                    type: integer
                  failedRules:
                    type: integer
          description: The rule execution result.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      operationId: executeContractRules
      summary: Execute contract rules
      description: Executes contract rules against a data record and returns the result.
components:
  schemas:
    ContractRuleSet:
      title: ContractRuleSet
      description: A set of contract rules, divided into domain and migration categories.
      type: object
      properties:
        domainRules:
          description: Rules for domain validation.
          type: array
          items:
            $ref: '#/components/schemas/ContractRule'
        migrationRules:
          description: Rules for version migration.
          type: array
          items:
            $ref: '#/components/schemas/ContractRule'
    ContractMetadata:
      title: ContractMetadata
      description: Contract metadata for an artifact.
      type: object
      properties:
        status:
          description: The contract lifecycle status.
          type: string
          enum:
          - DRAFT
          - STABLE
          - DEPRECATED
        ownerTeam:
          description: The team that owns the contract.
          type: string
        ownerDomain:
          description: The domain the contract belongs to.
          type: string
        supportContact:
          description: Support contact email.
          type: string
        classification:
          description: Data classification level.
          type: string
          enum:
          - PUBLIC
          - INTERNAL
          - CONFIDENTIAL
          - RESTRICTED
        stage:
          description: Promotion stage.
          type: string
          enum:
          - DEV
          - STAGE
          - PROD
        stableDate:
          description: ISO-8601 date when contract became stable.
          type: string
        deprecatedDate:
          description: ISO-8601 date when contract was deprecated.
          type: string
        deprecationReason:
          description: Reason for deprecation.
          type: string
        compatibilityGroup:
          description: Compatibility group for schema evolution scoping.
          type: string
    ContractRule:
      title: ContractRule
      description: A single contract rule definition.
      required:
      - name
      - kind
      - type
      - mode
      type: object
      properties:
        name:
          description: The rule name.
          type: string
        kind:
          description: The rule kind.
          type: string
          enum:
          - CONDITION
          - TRANSFORM
        type:
          description: Rule executor type (CEL, CEL_FIELD, ENCRYPT, etc.).
          type: string
        mode:
          description: When the rule is applied.
          type: string
          enum:
          - WRITE
          - READ
          - WRITEREAD
          - UPGRADE
          - DOWNGRADE
        expr:
          description: The rule expression.
          type: string
        params:
          description: Rule parameters.
          type: object
          additionalProperties:
            type: string
        tags:
          description: Tags for categorizing the rule.
          type: array
          items:
            type: string
        onSuccess:
          description: Action on rule success.
          type: string
          enum:
          - NONE
          - ERROR
          - DLQ
        onFailure:
          description: Action on rule failure.
          type: string
          enum:
          - NONE
          - ERROR
          - DLQ
        disabled:
          description: Whether the rule is disabled.
          type: boolean
    Labels:
      description: User-defined name-value pairs. Name and value must be strings.
      type: object
      additionalProperties:
        type: string
      x-codegen-inline: true
      x-codegen-type: StringMap
    ContractStatusTransition:
      titl

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