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.
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:
- Click Add Schema reference.
- Enter the Schema reference name.
- Enter the Subject name of the referenced schema.
- Select the Version of the referenced schema.
- 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 beAVRO
orPROTOBUF
. Defaults toAVRO
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.