Create a subject

When you create a subject for the first time, you are also creating the first version of the schema for that subject.

You can create a subject in one of the following ways:

Implicit (default): the default behavior for many producer and consumer clients is to automatically create a schema that does not exist when the client connects. The subject and version referencing the schema are also automatically created. This is convenient, but can lead to potential inconsistencies in the data if multiple clients create versions concurrently.
Explicit (recommended): in this method, each schema must be created in the registry before a producer or consumer client can use it. You can use Google Cloud console or the Managed Kafka API to do this.

This behavior must be configured in your client settings. Consult your serializer or deserializer client library documentation for the details.

Before you begin

Learn about schema overview.
Create a schema registry if you don't have one already.
Understand schema references.

Required roles and permissions

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

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

Required permissions

The following permissions are required to create 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 the permissions to create and manage subject versions.

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

Create a subject or first version of a schema

When you create a subject, you also create its first version. This first version creates a new schema or is a reference to an existing schema.

Console

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.

Click the name of the schema registry for which you want to create a subject.
The Schema registry details page opens.

Click Create subject.
The Create subject page opens.

For Subject name, enter a unique name for your subject.
The name must start with a letter, and contain only letters, numbers, and the following special characters: dashes -, periods ., underscores _, tildes ~, percents %, or plus signs +. The name of a subject is immutable.
To name a subject, see Subject naming strategies.

Choose or create a Context name.

Contexts act like folders or namespaces to organize your subjects and schemas, providing isolation between different groups.

The context is specified at the end of the schema registry URL. For example—schema.registry.url=https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID.

The default context is selected if you don't select or create a new context. The default context is identified as .

The context name must start with a letter, and contain only letters, numbers, and the following special characters: dashes -, periods ., underscores _, tildes ~, percents %, or plus signs +.

The name of a context is immutable.
Provide a Schema definition in either Avro or Protocol Buffer format.

Do not include sensitive information such as personally identifiable information (PII) or security data in your schema field names.
For Schema reference, if your schema uses or depends on data structures defined in other schemas already registered in the registry, you need to declare these dependencies here. To do so, complete the following steps:
1. Click Add Schema reference.
2. Enter the Schema reference name.
3. Enter the Subject name of the referenced schema.
4. Select the Version of the referenced schema.
5. Click Done.
Click Create.

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.

The following REST API samples create the first version of a subject.

To create a subject within the default context, make a POST request to the specified URI using the projects.locations.schemaRegistries.subjects.versions.create method:

POST https://managedkafka.googleapis.com/v1main/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 subject collection URI using the projects.locations.schemaRegistries.contexts.subjects.versions.create method:

POST https://managedkafka.googleapis.com/v1main/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 . for the default context if you wish to be explicit, otherwise omit /contexts/CONTEXT_ID to use the default context implicitly.
The name must start with a letter, and contain only letters, numbers, and the following special characters: dashes -, periods ., underscores _, tildes ~, percents %, or plus signs +. The name of a context is immutable.
SUBJECT_ID (required): the ID for the new subject under which to create the first version.
The name must start with a letter, and contain only letters, numbers, and the following special characters: dashes -, periods ., underscores _, tildes ~, percents %, or plus signs +. The name of a subject is immutable.

Request Body:

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

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF", // 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.
Do not include sensitive information such as personally identifiable information (PII) or security data in your schema field names.
schemaType (optional): the type of the schema. Can be AVRO or PROTOBUF. Defaults to AVRO if omitted.
references (optional): 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 subject ID of the schema being referenced.
- REFERENCED_VERSION_NUMBER: the specific version number of the referenced subject's schema.
versionId, schemaId: optional fields usually handled by the service. For the first version of a subject, versionId will be "1".

If the request is successful and the schema is valid and passes compatibility checks if configured, the API returns a 200 OK status code. The response body contains the schema ID used by the created version, which is different from the version 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.