Register schema under a subject
POST/subjects/:subject/versions
Register a new schema under the specified subject. If successfully registered, this returns the unique identifier of this schema in the registry. The returned identifier should be used to retrieve this schema from the schemas resource and is different from the schema's version which is associated with the subject. If the same schema is registered under a different subject, the same identifier will be returned. However, the version of the schema may be different under different subjects. A schema should be compatible with the previously registered schema or schemas (if there are any) as per the configured compatibility level. The configured compatibility level can be obtained by issuing a GET http:get:: /config/(string: subject). If that returns null, then GET http:get:: /config When there are multiple instances of Schema Registry running in the same cluster, the schema registration request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed.
Request
Responses
- 200
- 400
- 401
- 403
- 409
- 422
- 429
- 500
Schema successfully registered.
Bad Request
Unauthorized
Forbidden
Conflict. Incompatible schema.
Unprocessable entity. Error code 42201 indicates an invalid schema or schema type.
Rate Limit Exceeded
Response Headers
X-Request-Id
The unique identifier for the API request.
X-RateLimit-Limit
The maximum number of requests you're permitted to make per time period.
X-RateLimit-Remaining
The number of requests remaining in the current rate limit window.
X-RateLimit-Reset
The relative time in seconds until the current rate-limit window resets.
Important: This differs from Github and Twitter's same-named header which uses UTC epoch seconds. We use relative time to avoid client/server time synchronization issues.
Retry-After
The number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.
Internal Server Error. Error code 50001 indicates a failure in the backend data store. Error code 50002 indicates operation timed out. Error code 50003 indicates a failure forwarding the request to the primary.
OpenAPI definition (YAML)
paths:
/subjects/{subject}/versions:
post:
tags:
- Subjects (v1)
description: 'Register a new schema under the specified subject. If successfully registered, this
returns the unique identifier of this schema in the registry. The returned identifier should be
used to retrieve this schema from the schemas resource and is different from the schema''s version
which is associated with the subject. If the same schema is registered under a different subject,
the same identifier will be returned. However, the version of the schema may be different under
different subjects.
A schema should be compatible with the previously registered schema or schemas (if there are any)
as per the configured compatibility level. The configured compatibility level can be obtained
by issuing a GET http:get:: /config/(string: subject). If that returns null, then GET http:get::
/config
When there are multiple instances of Schema Registry running in the same cluster, the schema registration
request will be forwarded to one of the instances designated as the primary. If the primary is
not available, the client will get an error code indicating that the forwarding has failed.'
operationId: register
parameters:
- name: subject
in: path
description: Name of the subject
required: true
schema:
type: string
- name: normalize
in: query
description: Whether to register the normalized schema
schema:
type: boolean
- name: format
in: query
description: 'Desired output format, dependent on schema type. For AVRO schemas, valid values
are: " " (default) or "resolved". For PROTOBUF schemas, valid values are: " " (default), "ignore_extensions",
or "serialized" (The parameter does not apply to JSON schemas.)'
schema:
type: string
default: ''
requestBody:
description: Schema
content:
application/vnd.schemaregistry.v1+json:
schema:
type: object
properties:
version:
type: integer
description: Version number
format: int32
id:
type: integer
description: Globally unique identifier of the schema
format: int32
schemaType:
type: string
description: Schema type
references:
type: array
description: References to other schemas
items:
type: object
properties:
name:
type: string
description: Reference name
example: io.confluent.kafka.example.User
subject:
type: string
description: Name of the referenced subject
example: User
version:
type: integer
description: Version number of the referenced subject
format: int32
example: 1
description: Schema reference
title: SchemaReference
schema:
type: string
description: Schema definition string
metadata:
description: User-defined metadata
nullable: true
properties:
tags:
additionalProperties:
items:
type: string
type: array
uniqueItems: true
type: object
properties:
additionalProperties:
type: string
type: object
sensitive:
items:
type: string
type: array
uniqueItems: true
type: object
title: Metadata
ruleSet:
description: Schema rule set
nullable: true
properties:
migrationRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
domainRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
type: object
title: RuleSet
schemaTagsToAdd:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
schemaTagsToRemove:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
propagateSchemaTags:
type: boolean
description: Schema register request
title: RegisterSchemaRequest
application/vnd.schemaregistry+json:
schema:
type: object
properties:
version:
type: integer
description: Version number
format: int32
id:
type: integer
description: Globally unique identifier of the schema
format: int32
schemaType:
type: string
description: Schema type
references:
type: array
description: References to other schemas
items:
type: object
properties:
name:
type: string
description: Reference name
example: io.confluent.kafka.example.User
subject:
type: string
description: Name of the referenced subject
example: User
version:
type: integer
description: Version number of the referenced subject
format: int32
example: 1
description: Schema reference
title: SchemaReference
schema:
type: string
description: Schema definition string
metadata:
description: User-defined metadata
nullable: true
properties:
tags:
additionalProperties:
items:
type: string
type: array
uniqueItems: true
type: object
properties:
additionalProperties:
type: string
type: object
sensitive:
items:
type: string
type: array
uniqueItems: true
type: object
title: Metadata
ruleSet:
description: Schema rule set
nullable: true
properties:
migrationRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
domainRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
type: object
title: RuleSet
schemaTagsToAdd:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
schemaTagsToRemove:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
propagateSchemaTags:
type: boolean
description: Schema register request
title: RegisterSchemaRequest
application/json:
schema:
type: object
properties:
version:
type: integer
description: Version number
format: int32
id:
type: integer
description: Globally unique identifier of the schema
format: int32
schemaType:
type: string
description: Schema type
references:
type: array
description: References to other schemas
items:
type: object
properties:
name:
type: string
description: Reference name
example: io.confluent.kafka.example.User
subject:
type: string
description: Name of the referenced subject
example: User
version:
type: integer
description: Version number of the referenced subject
format: int32
example: 1
description: Schema reference
title: SchemaReference
schema:
type: string
description: Schema definition string
metadata:
description: User-defined metadata
nullable: true
properties:
tags:
additionalProperties:
items:
type: string
type: array
uniqueItems: true
type: object
properties:
additionalProperties:
type: string
type: object
sensitive:
items:
type: string
type: array
uniqueItems: true
type: object
title: Metadata
ruleSet:
description: Schema rule set
nullable: true
properties:
migrationRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
domainRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
type: object
title: RuleSet
schemaTagsToAdd:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
schemaTagsToRemove:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
propagateSchemaTags:
type: boolean
description: Schema register request
title: RegisterSchemaRequest
application/octet-stream:
schema:
type: object
properties:
version:
type: integer
description: Version number
format: int32
id:
type: integer
description: Globally unique identifier of the schema
format: int32
schemaType:
type: string
description: Schema type
references:
type: array
description: References to other schemas
items:
type: object
properties:
name:
type: string
description: Reference name
example: io.confluent.kafka.example.User
subject:
type: string
description: Name of the referenced subject
example: User
version:
type: integer
description: Version number of the referenced subject
format: int32
example: 1
description: Schema reference
title: SchemaReference
schema:
type: string
description: Schema definition string
metadata:
description: User-defined metadata
nullable: true
properties:
tags:
additionalProperties:
items:
type: string
type: array
uniqueItems: true
type: object
properties:
additionalProperties:
type: string
type: object
sensitive:
items:
type: string
type: array
uniqueItems: true
type: object
title: Metadata
ruleSet:
description: Schema rule set
nullable: true
properties:
migrationRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
domainRules:
items:
description: Rule
properties:
name:
description: Rule name
type: string
doc:
description: Rule doc
type: string
kind:
description: Rule kind
enum:
- TRANSFORM
- CONDITION
type: string
mode:
description: Rule mode
enum:
- UPGRADE
- DOWNGRADE
- UPDOWN
- WRITE
- READ
- WRITEREAD
type: string
type:
description: Rule type
type: string
tags:
description: The tags to which this rule applies
items:
description: The tags to which this rule applies
type: string
type: array
uniqueItems: true
params:
additionalProperties:
description: Optional params for the rule
type: string
description: Optional params for the rule
type: object
expr:
description: Rule expression
type: string
onSuccess:
description: Rule action on success
type: string
onFailure:
description: Rule action on failure
type: string
disabled:
description: Whether the rule is disabled
type: boolean
type: object
title: Rule
type: array
type: object
title: RuleSet
schemaTagsToAdd:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
schemaTagsToRemove:
type: array
items:
type: object
properties:
schemaEntity:
type: object
properties:
entityPath:
type: string
entityType:
type: string
enum:
- sr_record
- sr_field
title: SchemaEntity
tags:
type: array
items:
type: string
title: SchemaTags
propagateSchemaTags:
type: boolean
description: Schema register request
title: RegisterSchemaRequest
required: true
responses:
'200':
description: Schema successfully registered.
content:
application/vnd.schemaregistry.v1+json:
schema:
type: object
properties:
id:
type: integer
description: Globally unique identifier of the schema
format: int32
example: 100001
description: Schema register response
title: RegisterSchemaResponse
application/vnd.schemaregistry+json; qs=0.9:
schema:
type: object
properties:
id:
type: integer
description: Globally unique identifier of the schema
format: int32
example: 100001
description: Schema register response
title: RegisterSchemaResponse
application/json; qs=0.5:
schema:
type: object
properties:
id:
type: integer
description: Globally unique identifier of the schema
format: int32
example: 100001
description: Schema register response
title: RegisterSchemaResponse
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
example:
error_code: 400
message: Bad Request
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
example:
error_code: 401
message: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
example:
error_code: 403
message: Forbidden
'409':
description: Conflict. Incompatible schema.
content:
application/vnd.schemaregistry.v1+json:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
application/vnd.schemaregistry+json; qs=0.9:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
application/json; qs=0.5:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
'422':
description: 'Unprocessable entity. Error code 42201 indicates an invalid schema or schema type. '
content:
application/vnd.schemaregistry.v1+json:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
application/vnd.schemaregistry+json; qs=0.9:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
application/json; qs=0.5:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
'429':
description: Rate Limit Exceeded
headers:
X-Request-Id:
schema:
type: string
description: The unique identifier for the API request.
X-RateLimit-Limit:
schema:
type: integer
description: The maximum number of requests you're permitted to make per time period.
X-RateLimit-Remaining:
schema:
type: integer
description: The number of requests remaining in the current rate limit window.
X-RateLimit-Reset:
schema:
type: integer
description: "The relative time in seconds until the current rate-limit window resets. \
\ \n \n**Important:** This differs from Github and Twitter's same-named header which\
\ uses UTC epoch seconds. We use relative time to avoid client/server time synchronization\
\ issues."
Retry-After:
schema:
type: integer
description: The number of seconds to wait until the rate limit window resets. Only sent
when the rate limit is reached.
'500':
description: Internal Server Error. Error code 50001 indicates a failure in the backend data
store. Error code 50002 indicates operation timed out. Error code 50003 indicates a failure
forwarding the request to the primary.
content:
application/vnd.schemaregistry.v1+json:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
application/vnd.schemaregistry+json; qs=0.9:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
application/json; qs=0.5:
schema:
type: object
properties:
error_code:
type: integer
description: The error code
format: int32
message:
type: string
description: The error message
description: Error message of this operation
title: ErrorMessage
security:
- resource-api-key: []
- external-access-token: []
servers:
- url: https://psrc-00000.region.provider.confluent.cloud
description: Confluent Cloud Schema Registry Endpoint.
jsonRequestBodyExample:
version: 0
id: 0
schemaType: string
references:
- name: io.confluent.kafka.example.User
subject: User
version: 1
schema: string
metadata:
tags: {}
properties: {}
sensitive:
- string
ruleSet:
migrationRules:
- name: string
doc: string
kind: TRANSFORM
mode: UPGRADE
type: string
tags:
- string
params: {}
expr: string
onSuccess: string
onFailure: string
disabled: true
domainRules:
- name: string
doc: string
kind: TRANSFORM
mode: UPGRADE
type: string
tags:
- string
params: {}
expr: string
onSuccess: string
onFailure: string
disabled: true
schemaTagsToAdd:
- schemaEntity:
entityPath: string
entityType: sr_record
tags:
- string
schemaTagsToRemove:
- schemaEntity:
entityPath: string
entityType: sr_record
tags:
- string
propagateSchemaTags: true