Register a new schema version

After you create a subject, you can add new versions to it. This process is known as registering a new schema version. Each new version represents an evolution of the schema associated with that subject.

A subject can have multiple versions. Versions within a subject follow configurable compatibility rules to ensure safe schema evolution. For example, a subject can require that all changes be backwards-compatible. An example of a backwards-compatible change is adding an optional field. Adding a required field would be considered a backwards-incompatible change; if your subject is configured for backwards compatibility, this change is not allowed. However, if your subject is configured for forwards-compatibility, adding a required field would be acceptable.

Compatibility checks are not retroactive. If compatibility rules are changed for a subject or schema registry, versions already existing within the subject are not re-validated against the new rules. For more information about compatibility, see About compatibility type.

Required roles and permissions

To get the permissions that you need to register a schema version for a subject, ask your administrator to grant you the Managed Kafka Schema Registry Editor (roles/managedkafka.schemaRegistryEditor) IAM role on your project or the specific schema registry and subject. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to register a schema version for a subject. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to register a schema version for a subject:

  • Grant this permission on the parent context or the default context: managedkafka.versions.create

You might also be able to get these permissions with custom roles or other predefined roles.

The higher-level Managed Kafka Schema Registry Admin (roles/managedkafka.schemaRegistryAdmin) role also includes these permissions.

For more information about the predefined roles available for Managed Service for Apache Kafka, see the Access control documentation.

Register a new schema version

You register a new schema version when a subject already exists.

Console

  1. In the Google Cloud console, go to the Schema registries page.

    Go to schema registries

    A list of schema registries in your project is displayed.

  2. Click the name of the schema registry for which you want to register a new schema version for the subject.

    The Schema registry details page opens.

  3. Under Subjects in this schema registry, click the subject ID for which you want to register the schema version.

    The Subject details page opens.

  4. Click Create version.

    The Create version page opens.

  5. In the Schema definition text area, enter or paste your new schema version.

    If the schema definition is valid and passes the subject's compatibility checks, a success notification appears, and the new version is added to the subject.

    Do not include sensitive information such as personally identifiable information (PII) or security data in your schema field names.

    The schema definition must be in Avro or Protocol Buffer format.

  6. (Optional) If your new schema version references other schemas, click Add Schema reference and provide the reference name, subject, and version for each reference. Click Done for each reference.
  7. Click Create.
  8. After the schema version is created, you can view the differences between any two versions by selecting the versions and clicking the View diff link on the Subject details page.

REST

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token.

To register a new schema version for a subject within the default context, make a POST request to the specific URI using the projects.locations.schemaRegistries.subjects.versions.create method:

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Alternatively, if using a specific context, include the context in the versions collection URI and use the projects.locations.schemaRegistries.contexts.subjects.versions.create method.

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Replace the following:

  • PROJECT_ID (required): your Google Cloud project ID.
  • LOCATION (required): the Google Cloud region where the schema registry exists.
  • REGISTRY_ID (required): the ID of the target schema registry.
  • CONTEXT_ID (optional): the ID of the context containing the subject. Use . (a single period) for the default context if you wish to be explicit, otherwise omit /contexts/CONTEXT_ID to use the default context implicitly.
  • SUBJECT_ID (required): the ID of the subject under which to create the new version.

Request Body:

Include a JSON object in the request body specifying the schema details:

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF" | "JSON", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

Replace the following:

  • YOUR_SCHEMA_DEFINITION_STRING (required): a string containing the actual schema definition payload.
  • schemaType (optional, within schema object): the type of the schema. Can be AVRO or PROTOBUF. Defaults to AVRO if omitted.
  • references (optional, within schema object): an array of objects defining any schemas referenced by this schema.
    • REFERENCE_NAME: the name used to reference the other schema within this schema's definition.
    • REFERENCED_SUBJECT_ID: the fully qualified subject name of the schema being referenced. Example—projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject.
    • REFERENCED_VERSION_NUMBER: the specific version number (integer) of the referenced subject's schema.
  • versionId, schemaId: optional fields usually handled by the service. When registering the schema version, the service assigns the next available version number.

If the request is successful, the API returns a 200 OK status code and a response body containing the schema ID.

For more information, see the REST API documentation.

Apache Kafka® is a registered trademark of The Apache Software Foundation or its affiliates in the United States and/or other countries.