The schema registry server can enforce certain compatibility rules when new schemas are registered in a subject. Currently, we support the following compatibility rules.

Backward compatibility (default): A new schema is backward compatible if it can be used to read the data written in all previous schemas. Backward compatibility is useful for loading data into systems like Hadoop since one can always query data of all versions using the latest schema.

Forward compatibility: A new schema is forward compatible if all previous schemas can read data written in this schema. Forward compatibility is useful for consumer applications that can only deal with data in a particular version that may not always be the latest version.

Full compatibility: A new schema is fully compatible if it’s both backward and forward compatible.

No compatibility: A new schema can be any schema as long as it’s a valid Avro.

We recommend keeping the default backward compatibility since it’s common to have all data loaded into Hadoop.

The schema registry REST server uses content types for both requests and responses to indicate the serialization format of the data as well as the version of the API being used. Currently, the only serialization format supported is JSON and the only version of the API is v1. However, to remain compatible with future versions, you should specify preferred content types in requests and check the content types of responses.

The preferred format for content types is application/vnd.schemaregistry.v1+json, where v1 is the API version and json is the serialization format. However, other less specific content types are permitted, including application/vnd.schemaregistry+json to indicate no specific API version should be used
(the most recent stable version will be used), application/json, and application/octet-stream. The latter two are only supported for compatibility and ease of use.

Your requests should specify the most specific format and version information possible via the HTTP Accept header:

Accept:application/vnd.schemaregistry.v1+json

The server also supports content negotiation, so you may include multiple, weighted preferences:

All API endpoints use a standard error message format for any requests that return an HTTP status indicating an error (any 400 or 500 statuses). For example, a request entity that omits a required field may generate the following response:

HTTP/1.1422OKContent-Type:application/vnd.schemaregistry.v1+json{"error_code":422,"message":"schema may not be empty"}

Although it is good practice to check the status code, you may safely parse the response of any non-DELETE API calls and check for the presence of an error_code field to detect errors.

The subjects resource provides a list of all registered subjects in your schema registry. A subject refers to the name under which the schema is registered. If you are using the schema registry for Kafka, then a subject refers to either a “<topic>-key” or “<topic>-value” depending on whether you are registering the key schema for that topic or the value schema.

version (versionId) – Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string “latest”. “latest” returns the last registered schema under the specified subject. Note that there may be a new latest schema that gets registered right after this request is served.

Response JSON Object:

name (string) – Name of the subject that this schema is registered under

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 schemas (if there are any) as per the configured compatibility level. The configured compatibility level can be obtained by issuing a GEThttp:get::/config/(string:subject). If that returns null, then GEThttp: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 master. If the master is not available, the client will get an error code indicating that the forwarding has failed.

Check if a schema has already been registered under the specified subject. If so, this returns the schema string along with its globally unique identifier, its version under this subject and the subject name.

Parameters:

subject (string) – Subject under which the schema will be registered

Response JSON Object:

subject (string) – Name of the subject that this schema is registered under

Test input schema against a particular version of a subject’s schema for compatibility. Note that the compatibility level applied for the check is the configured compatibility level for the subject (http:get::/config/(string:subject)). If this subject’s compatibility level was never changed, then the global compatibility level applies (http:get::/config).

Parameters:

subject (string) – Subject of the schema version against which compatibility is to be tested

version (versionId) – Version of the subject’s schema against which compatibility is to be tested. Valid values for versionId are between [1,2^31-1] or the string “latest”. “latest” checks compatibility of the input schema with the last registered schema under the specified subject

When there are multiple instances of schema registry running in the same cluster, the update request will be forwarded to one of the instances designated as the master. If the master is not available, the client will get an error code indicating that the forwarding has failed.

Request JSON Object:

compatibility (string) – New global compatibility level. Must be one of NONE, FULL, FORWARD, BACKWARD