---
title: "Register schema under a subject"
method: POST
path: "/subjects/{subject}/versions"
tags: ["Subjects (v1)"]
---

# 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.

## Path parameters

- `subject` string, required

## Query parameters

- `normalize` boolean
- `format` string

## Request body

- RegisterSchemaRequest — Schema register request
  - `version` integer — Version number
  - `id` integer — Globally unique identifier of the schema
  - `schemaType` string — Schema type
  - `references` SchemaReference[] — References to other schemas
    - `name` string — Reference name
    - `subject` string — Name of the referenced subject
    - `version` integer — Version number of the referenced subject
  - `schema` string — Schema definition string
  - `metadata` Metadata, nullable — User-defined metadata
    - `tags` object
    - `properties` object
    - `sensitive` string[]
  - `ruleSet` RuleSet, nullable — Schema rule set
    - `migrationRules` Rule[]
      - `name` string — Rule name
      - `doc` string — Rule doc
      - `kind` 'TRANSFORM' | 'CONDITION' — Rule kind
      - `mode` 'UPGRADE' | 'DOWNGRADE' | 'UPDOWN' | 'WRITE' | 'READ' | 'WRITEREAD' — Rule mode
      - `type` string — Rule type
      - `tags` string[] — The tags to which this rule applies
      - `params` object — Optional params for the rule
      - `expr` string — Rule expression
      - `onSuccess` string — Rule action on success
      - `onFailure` string — Rule action on failure
      - `disabled` boolean — Whether the rule is disabled
    - `domainRules` Rule[]
      - `name` string — Rule name
      - `doc` string — Rule doc
      - `kind` 'TRANSFORM' | 'CONDITION' — Rule kind
      - `mode` 'UPGRADE' | 'DOWNGRADE' | 'UPDOWN' | 'WRITE' | 'READ' | 'WRITEREAD' — Rule mode
      - `type` string — Rule type
      - `tags` string[] — The tags to which this rule applies
      - `params` object — Optional params for the rule
      - `expr` string — Rule expression
      - `onSuccess` string — Rule action on success
      - `onFailure` string — Rule action on failure
      - `disabled` boolean — Whether the rule is disabled
  - `schemaTagsToAdd` SchemaTags[]
    - `schemaEntity` SchemaEntity
      - `entityPath` string
      - `entityType` 'sr_record' | 'sr_field'
    - `tags` string[]
  - `schemaTagsToRemove` SchemaTags[]
    - `schemaEntity` SchemaEntity
      - `entityPath` string
      - `entityType` 'sr_record' | 'sr_field'
    - `tags` string[]
  - `propagateSchemaTags` boolean

## Response `200`

Schema successfully registered.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict. Incompatible schema.
- `422` — Unprocessable entity. Error code 42201 indicates an invalid schema or schema type.
- `429` — Rate Limit Exceeded
- `500` — 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.

---

[API](https://skmtc.dev/confluent/apis/confluent-cloud-apis.md) · [All operations](https://skmtc.dev/confluent/apis/confluent-cloud-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/confluent/confluent-cloud-apis/revisions/a6a73f98a698/schema)