Associate a schema with a topic

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

Before you begin

Required roles and permissions

To get the permissions that you need to associate 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 associate and manage schemas. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to associate 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.

Guidelines to associate a schema with a topic

You can associate a schema with a topic when you create or edit a topic. Here are the guidelines for associating a schema with a topic:

  • You can associate a schema with one or more topics.

    After a schema is associated with a topic, every message that the topic receives from the publishers must follow that schema.

  • When you associate a schema with a topic, you must also specify the encoding of the messages to be published as BINARY or JSON. If using JSON with an Avro schema, pay close attention to the encoding rules for unions.

  • If a schema associated with a topic has revisions, messages must match the encoding and validate against a revision within the available range. If they don't validate, the message fails to publish.

    Revisions are tried in reverse chronological order that is based on creation time. To create a schema revision, see Commit a schema revision.

Validation logic for a message schema

When you associate a schema with a topic and if the schema has revisions, you can specify a subset range of revisions to use. If you don't specify a range, the entire range is used for validation.

If you don't specify a revision as First revision allowed, then the oldest existing revision for the schema is used for validation. If you don't specify a revision as Last revision allowed, then the newest existing revision for the schema is used.

Let's take the example of Schema S that is attached to topic T.

Schema S has the revision IDs A,B, C, and D created in order, where A is the first or oldest revision. None of the schemas are identical to each other, or rollbacks of an existing schema.

  • If you only set the First revision allowed field as B, messages conforming only to schema A are rejected, while messages conforming to schemas B, C, and D are accepted.

  • If you only set the Last revision allowed field as C, messages that conform to schemas A, B, and C are accepted, and messages that conform only to schema D are rejected.

  • If you set both fields First revision allowed as B and