Create a schema for a topic

This document shows you how to create schemas for Pub/Sub topics.

Before you begin

Before you create a schema, complete the following:

Required roles and permissions

To get the permissions that you need to create and manage schemas, ask your administrator to grant you the Pub/Sub Editor (roles/pubsub.editor) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

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

Required permissions

The following permissions are required to create and manage schemas:

  • Create schema: pubsub.schemas.create
  • Attach schema to topic: pubsub.schemas.attach
  • Commit a schema revision: pubsub.schemas.commit
  • Delete a schema or a schema revision: pubsub.schemas.delete
  • Get a schema or schema revisions: pubsub.schemas.get
  • List schemas: pubsub.schemas.list
  • List schema revisions: pubsub.schemas.listRevisions
  • Rollback a schema: pubsub.schemas.rollback
  • Validate a message: pubsub.schemas.validate
  • Get the IAM policy for a schema: pubsub.schemas.getIamPolicy
  • Configure the IAM policy for a schema: pubsub.schemas.setIamPolicy

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

You can grant roles and permissions to principals such as users, groups, domains, or service accounts. You can create a schema in one project and attach it to a topic located in a different project. Ensure that you have the required permissions for each project.

Create a schema

You can create a schema using the Google Cloud console, the gcloud CLI, the Pub/Sub API, or the Cloud Client Libraries.

Before creating a schema, review this important information about schemas.

Console

To create a schema, follow these steps:

  1. In the Google Cloud console, go to the Pub/Sub schemas page.

    Go to Schemas

  2. Click Create schema.

  3. In the Schema ID field, enter an ID for your schema.

    For guidelines to name a schema, see Guidelines to name a topic, subscription, or snapshot.

  4. For Schema type, select either Avro or Protocol Buffer.

    Learn more about schema types.

  5. In the Schema definition field, enter the Avro or Protocol Buffer definition for your schema.

    For example, here's a sample schema in Avro.

    {
  "type": "record",
  "name": "Avro",
  "fields": [
    {
      "name": "ProductName",
      "type": "string",
      "default": ""
    },
    {
      "name": "SKU",
      "type": "int",
      "default": 0
    },
    {
      "name": "InStock",
      "type": "boolean",
      "default": false
    }
  ]
}

  6. Optional: Click Validate definition to check if the schema definition is correct.

    The validation check does not check the compatibility of the schema with the messages to be published. Test messages in the next step.

  7. Optional: You can test if messages with the correct schema get published.

    1. Click Test message.

    2. In the Test message window, select a type of Message encoding.

    3. In the Message body, enter a test message.

    4. Click Test.

      For example, here's a sample message for the test schema. In this example, select the Message encoding as JSON.

      {"ProductName":"GreenOnions", "SKU":34543, "InStock":true}

    5. Exit the test message page.

  8. Click Create to save the schema.

gcloud

gcloud pubsub schemas create SCHEMA_ID \
        --type=SCHEMA_TYPE \
        --definition=SCHEMA_DEFINITION

Where:

  • SCHEMA_TYPE is either avro or protocol-buffer.
  • SCHEMA_DEFINITION is a string containing the definition of the schema, formatted according to the chosen schema type.

You can also specify the schema definition in a file: