Schemas API - Apache Pulsar

Overview

Schemas define the structure of messages in Pulsar topics. The Schemas API allows you to register, retrieve, update, and delete schemas, as well as test schema compatibility. Pulsar supports multiple schema types including Avro, JSON, Protobuf, and more. Base Path: /admin/v2/schemas

Get Schema

Retrieve the current schema for a topic.

GET /admin/v2/schemas/{tenant}/{namespace}/{topic}/schema

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name

topic

string

required

The topic name

Query Parameters

authoritative

boolean

default:"false"

Whether this broker is authoritative for the topic

Response

version

integer

Schema version number

type

string

Schema type (AVRO, JSON, PROTOBUF, etc.)

timestamp

integer

Schema creation timestamp

data

string

Base64-encoded schema definition

properties

object

Additional schema metadata

Example

curl -X GET http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/schema \
  -H "Authorization: Bearer <token>"

Response Example

{
  "version": 0,
  "type": "AVRO",
  "timestamp": 1640000000000,
  "data": "eyJ0eXBlIjogInJlY29yZCIsICJuYW1lIjogIlVzZXIiLCAiZmllbGRzIjogW3sibmFtZSI6ICJpZCIsICJ0eXBlIjogImludCJ9LCB7Im5hbWUiOiAibmFtZSIsICJ0eXBlIjogInN0cmluZyJ9XX0=",
  "properties": {
    "key1": "value1"
  }
}

Get Schema by Version

Retrieve a specific version of a schema.

GET /admin/v2/schemas/{tenant}/{namespace}/{topic}/schema/{version}

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name

topic

string

required

The topic name

version

string

required

Schema version number or “latest”

Example

curl -X GET http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/schema/2 \
  -H "Authorization: Bearer <token>"

Get All Schemas

Retrieve all schema versions for a topic.

GET /admin/v2/schemas/{tenant}/{namespace}/{topic}/schemas

Example

curl -X GET http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/schemas \
  -H "Authorization: Bearer <token>"

Response Example

[
  {
    "version": 0,
    "type": "AVRO",
    "timestamp": 1640000000000,
    "data": "...",
    "properties": {}
  },
  {
    "version": 1,
    "type": "AVRO",
    "timestamp": 1640100000000,
    "data": "...",
    "properties": {}
  }
]

Upload Schema

POST /admin/v2/schemas/{tenant}/{namespace}/{topic}/schema

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name

topic

string

required

The topic name

Request Body

type

string

required

Schema type: AVRO, JSON, PROTOBUF, STRING, BYTES, etc.

schema

string

required

Schema definition (format depends on type)

properties

object

Additional metadata key-value pairs

Example - Avro Schema

curl -X POST http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/schema \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"User\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"name\",\"type\":\"string\"}]}",
    "properties": {
      "owner": "team-a"
    }
  }'

Example - JSON Schema

curl -X POST http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/schema \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "JSON",
    "schema": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"integer\"},\"name\":{\"type\":\"string\"}},\"required\":[\"id\",\"name\"]}",
    "properties": {}
  }'

Response Codes

Code	Description
200	Schema created/updated successfully
307	Current broker doesn’t serve this topic
401	Don’t have permission
403	Don’t have admin permission
404	Tenant/namespace/topic doesn’t exist
409	Incompatible schema
422	Invalid schema data

Response Example

{
  "version": 2
}

Delete Schema

Delete all versions of a schema for a topic.

DELETE /admin/v2/schemas/{tenant}/{namespace}/{topic}/schema

Query Parameters

force

boolean

default:"false"

Force delete even if topic has active producers/consumers

authoritative

boolean

default:"false"

Whether this broker is authoritative

Example

curl -X DELETE http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/schema \
  -H "Authorization: Bearer <token>"

Response Example

{
  "version": 3
}

Test Schema Compatibility

Test if a new schema is compatible with the existing schema.

POST /admin/v2/schemas/{tenant}/{namespace}/{topic}/compatibility

Request Body

type

string

required

Schema type

schema

string

required

Schema definition to test

properties

object

Schema properties

Example

curl -X POST http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/compatibility \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"User\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"email\",\"type\":[\"null\",\"string\"],\"default\":null}]}"
  }'

Response Example

{
  "isCompatibility": true,
  "schemaCompatibilityStrategy": "FORWARD"
}

Get Schema Version

Get the version number for a specific schema definition.

POST /admin/v2/schemas/{tenant}/{namespace}/{topic}/version

Request Body

type

string

required

Schema type

schema

string

required

Schema definition

Example

curl -X POST http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/version \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"User\",\"fields\":[{\"name\":\"id\",\"type\":\"int\"},{\"name\":\"name\",\"type\":\"string\"}]}"
  }'

Response Example

{
  "version": 1
}

Schema Types

Pulsar supports various schema types:

Primitive Types

STRING: UTF-8 encoded strings
BYTES: Raw byte arrays
INT8/INT16/INT32/INT64: Integer types
FLOAT/DOUBLE: Floating point numbers
BOOLEAN: Boolean values

Complex Types

AVRO: Apache Avro schemas with evolution support
JSON: JSON Schema definitions
PROTOBUF: Protocol Buffers schemas
PROTOBUF_NATIVE: Native Protobuf with descriptor

Example - String Schema

curl -X POST http://localhost:8080/admin/v2/schemas/my-tenant/my-namespace/my-topic/schema \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STRING",
    "schema": ""
  }'

Schema Compatibility

Pulsar supports different compatibility strategies:

Compatibility Strategies

ALWAYS_COMPATIBLE: Any schema change is allowed
ALWAYS_INCOMPATIBLE: No schema changes allowed
BACKWARD: New schema can read data written with old schema
FORWARD: Old schema can read data written with new schema
FULL: Both backward and forward compatible
BACKWARD_TRANSITIVE: Backward compatible with all previous versions
FORWARD_TRANSITIVE: Forward compatible with all previous versions
FULL_TRANSITIVE: Full compatibility with all previous versions

Setting Compatibility Strategy

Compatibility is configured at the namespace level:

curl -X POST http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/schemaCompatibilityStrategy \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '"FULL"'

Best Practices

Schema Design

Use Avro or Protobuf for complex data structures
Include default values for optional fields
Document schema fields with descriptions
Version schemas properly

Schema Evolution

Test compatibility before deploying changes
Add new fields as optional with defaults
Never remove required fields
Use appropriate compatibility strategy for your use case

Schema Management

Store schema definitions in version control
Use schema registry for centralized management
Implement schema validation in CI/CD pipelines
Monitor schema usage and versions

Performance

Cache schema information on clients
Use schema versioning to avoid repeated uploads
Choose appropriate schema types for your data
Consider schema size impact on serialization

Error Handling

409 - Incompatible Schema

The new schema is not compatible with existing versions.Solution: Modify schema to maintain compatibility or change the compatibility strategy.

422 - Invalid Schema Data

The schema definition is malformed or invalid.Solution: Validate your schema definition against the type specification.

404 - Schema Not Found

No schema exists for this topic.Solution: Upload a schema first before trying to retrieve it.

Topics API

Manage topics that use schemas

Namespaces API

Configure namespace-level schema policies

REST API

CLI Tools

​Overview

​Get Schema

​Path Parameters

​Query Parameters

​Response

​Example

​Response Example

​Get Schema by Version

​Path Parameters

​Example

​Get All Schemas

​Example

​Response Example

​Upload Schema

​Path Parameters

​Request Body

​Example - Avro Schema

​Example - JSON Schema

​Response Codes

​Response Example

​Delete Schema

​Query Parameters

​Example

​Response Example

​Test Schema Compatibility

​Request Body

​Example

​Response Example

​Get Schema Version

​Request Body

​Example

​Response Example

​Schema Types

​Primitive Types

​Complex Types

​Example - String Schema

​Schema Compatibility

​Compatibility Strategies

​Setting Compatibility Strategy

​Best Practices

​Schema Design

​Schema Evolution

​Schema Management

​Performance

​Error Handling

​Related Resources

Topics API

Namespaces API

Build docs developers (and LLMs) love

Overview

Get Schema

Path Parameters

Query Parameters

Response

Example

Response Example

Get Schema by Version

Path Parameters

Example

Get All Schemas

Example

Response Example

Upload Schema

Path Parameters

Request Body

Example - Avro Schema

Example - JSON Schema

Response Codes

Response Example

Delete Schema

Query Parameters

Example

Response Example

Test Schema Compatibility

Request Body

Example

Response Example

Get Schema Version

Request Body

Example

Response Example

Schema Types

Primitive Types

Complex Types

Example - String Schema

Schema Compatibility

Compatibility Strategies

Setting Compatibility Strategy

Best Practices

Schema Design

Schema Evolution

Schema Management

Performance

Error Handling

Related Resources