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: title: ContractStatusTransition description: Request body for transitioning the contract lifecycle status. required: - status type: object properties: status: description: 'The target lifecycle status. Valid transitions: DRAFT to STABLE, DRAFT to DEPRECATED, STABLE to DEPRECATED.' type: string enum: - DRAFT - STABLE - DEPRECATED GroupId: description: An ID of a single artifact group. pattern: ^.{1,512}$ type: string example: '"my-group"' SearchedArtifact: description: Models a single artifact from the result set returned when searching for artifacts. required: - owner - createdOn - artifactId - artifactType - groupId - modifiedBy - modifiedOn type: object properties: name: description: '' type: string description: description: '' type: string createdOn: format: date-time description: '' type: string owner: description: '' type: string artifactType: $ref: '#/components/schemas/ArtifactType' description: '' modifiedOn: format: date-time description: '' type: string modifiedBy: description: '' type: string groupId: $ref: '#/components/schemas/GroupId' description: '' artifactId: $ref: '#/components/schemas/ArtifactId' description: '' labels: $ref: '#/components/schemas/Labels' description: '' example: groupId: My-Group artifactId: Procurement-Invoice name: Artifact Name description: Description of the artifact artifactType: AVRO owner: user1 createdOn: '2019-03-22T12:51:19Z' modifiedBy: user2 modifiedOn: '2019-04-01T12:51:19Z' ArtifactType: description: '' type: string example: AVRO x-codegen-package: io.apicurio.registry.types OdcsContractResult: title: OdcsContractResult description: Result of submitting or updating an ODCS contract. type: object properties: contractId: description: The contract artifact ID. type: string version: description: The ODCS contract version. type: string projection: $ref: '#/components/schemas/OdcsProjectionSummary' ArtifactId: description: The ID of a single artifact. pattern: ^.{1,512}$ type: string example: '"example-artifact"' ProblemDetails: title: Root Type for Error description: 'All error responses, whether `4xx` or `5xx` will include one of these as the response body.' required: - title - status type: object properties: detail: description: A human-readable explanation specific to this occurrence of the problem. type: string type: description: A URI reference [RFC3986] that identifies the problem type. type: string title: description: A short, human-readable summary of the problem type. type: string status: format: int32 description: The HTTP status code. type: integer instance: description: A URI reference that identifies the specific occurrence of the problem. type: string name: description: The name of the error (typically a server exception class name). type: string example: status: 500 name: NullPointerException title: An error occurred somewhere. OdcsProjectionSummary: title: OdcsProjectionSummary description: Summary of the projection performed when an ODCS contract is applied. type: object properties: rulesApplied: description: Number of CEL quality rules projected onto the schema artifact. type: integer format: int32 labelsApplied: description: Number of contract.* labels set on the schema artifact. type: integer format: int32 tagsApplied: description: Number of field-tag.* labels set on the schema artifact version. type: integer format: int32 warnings: description: Any warnings encountered during projection. type: array items: type: string EditableContractMetadata: title: EditableContractMetadata description: Editable contract metadata fields. 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 compatibilityGroup: description: Compatibility group for schema evolution scoping. type: string ArtifactSearchResults: description: Describes the response received when searching for artifacts. required: - count - artifacts type: object properties: artifacts: description: The artifacts returned in the result set. type: array items: $ref: '#/components/schemas/SearchedArtifact' count: description: "The total number of artifacts that matched the query that produced the result set (may be \nmore than the number of artifacts in the result set)." type: integer ContractRuleSearchResult: title: ContractRuleSearchResult description: A contract rule with its artifact coordinates, returned by tag search. type: object properties: groupId: description: The group ID of the artifact containing the rule. type: string artifactId: description: The artifact ID containing the rule. type: string globalId: description: The global ID of the version (null for artifact-level rules). type: integer format: int64 ruleCategory: description: The rule category (DOMAIN or MIGRATION). type: string enum: - DOMAIN - MIGRATION rule: $ref: '#/components/schemas/ContractRule' OdcsContractSummary: title: OdcsContractSummary description: Summary of an ODCS contract. type: object properties: contractId: description: The contract artifact ID. type: string name: description: The contract display name. type: string responses: Conflict: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: ConflictExample: value: error_code: 409 message: The artifact content was invalid. description: Common response used when an input conflicts with existing data. NotFound: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: NotFoundExample: value: error_code: 404 message: No artifact with id 'Topic-1/Inbound' could be found. description: Common response for all operations that can return a `404` error. BadRequest: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' description: Common response for all operations that can return a `400` error. ServerError: content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' examples: ErrorExample: value: error_code: 500 message: Lost connection to the database. description: Common response for all operations that can fail with an unexpected server error. securitySchemes: BasicAuth: type: http scheme: basic OAuth2: type: oauth2 flows: clientCredentials: tokenUrl: https://example.com/realms/apicurio/protocol/openid-connect/token scopes: read: Read access write: Write access admin: Admin access x-codegen: suppress-date-time-formatting: true bean-annotations: - io.quarkus.runtime.annotations.RegisterForReflection - annotation: lombok.experimental.SuperBuilder excludeEnums: true - annotation: lombok.AllArgsConstructor excludeEnums: true - annotation: lombok.NoArgsConstructor excludeEnums: true - annotation: lombok.EqualsAndHashCode excludeEnums: true - annotation: lombok.ToString(callSuper = true) excludeEnums: true