Doc-1996: Schema Registry Contexts #1658

pgellert · 2026-04-22T11:58:47Z

This is still WIP, as per https://github.com/redpanda-data/docs/pull/1658/changes#r3123466186

So remove the entire point about the base URL prefix?

@trevpanda @mattschumpert what do you think?

We need to either remove it or call out that it's not yet supported. But from slack I vaguely recall a policy that we don't document future features, so I am leaning removing this for now, yes.

Yes, we should remove until we support

-Original file line number
+Diff line change
@@ Expand Up / @@ -18,7 +18,7 @@ content: @@
       - url: https://github.com/redpanda-data/docs
         branches: [v/*, shared, site-search,'!v-end-of-life/*']
       - url: https://github.com/redpanda-data/cloud-docs
-        branches: 'main'
+        branches: main
       - url: https://github.com/redpanda-data/redpanda-labs
         branches: main
         start_paths: [docs,'*/docs']
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -207,6 +207,7 @@ @@
     **** xref:manage:schema-reg/schema-reg-api.adoc[API]
     **** xref:manage:kubernetes/k-schema-controller.adoc[Kubernetes]
     *** xref:manage:schema-reg/schema-reg-authorization.adoc[Schema Registry Authorization]
+    *** xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry Contexts]
     *** xref:manage:schema-reg/schema-id-validation.adoc[]
     *** xref:console:ui/schema-reg.adoc[Manage in Redpanda Console]
     ** xref:manage:high-availability.adoc[High Availability]
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -101,11 +101,43 @@ include::manage:partial$schema-compatibility.adoc[] @@
     Select a schema to soft-delete a version of it or all schemas of its subject. Schemas cannot be deleted if any other schemas reference it. A soft-deleted schema can be recovered, but a permanently-deleted schema cannot be recovered. Redpanda does not recommend permanently deleting schemas in a production environment.
+    == Schema Registry contexts
+    Schema Registry contexts are namespaces that group subjects and schemas within a single Schema Registry instance. For context configuration details and prerequisites, see xref:manage:schema-reg/schema-reg-contexts.adoc[].
+    ifdef::env-cloud[]
+    NOTE: On Serverless clusters, Redpanda manages contexts internally for per-tenant isolation and does not expose them to end users. On BYOC and Dedicated clusters, contexts are available and user-configurable.
+    endif::env-cloud[]
+    === How Console uses contexts
+    When Schema Registry contexts are enabled in your cluster, Console provides context-aware subject browsing and management.
+    Console lists subjects according to their context, using context-capable APIs to ensure subjects and their versions come from the correct namespace.
+    When you open a subject, Console fetches its schema versions using both the subject name and its context. This avoids ambiguity when the same subject name exists in multiple contexts.
+    Console surfaces Schema Registry mode and compatibility settings and, where supported, lets you adjust them at:
+    * Global level (entire registry)
+    * Subject level (within a specific context)
+    This lets you apply safe defaults globally while fine-tuning behavior for individual subjects in specific contexts.
+    === Automatic feature detection
+    Console automatically detects whether Schema Registry contexts are available:
+    * If contexts are supported, Console shows context-aware UI and uses context-specific APIs.
+    * If contexts are not supported, Console falls back to a standard non-context view, so you can continue working with schemas without errors.
     == Suggested reading
     ifndef::env-cloud[]
     * xref:console:config/deserialization.adoc[]
     endif::[]
     * xref:manage:schema-reg/schema-reg-overview.adoc[]
+    * xref:manage:schema-reg/schema-reg-contexts.adoc[]
-    // end::single-source[]
+    // end::single-source[]

-Original file line number
+Diff line change
@@ Expand Up / @@ -77,6 +77,12 @@ Key characteristics: @@
     See xref:manage:cluster-maintenance/continuous-data-balancing.adoc[] for configuration details.
+    == Schema Registry contexts
+    xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry contexts] are namespaces that isolate schemas, subjects, and configurations within a single Schema Registry instance. Each context maintains its own schema ID counter, mode settings, and compatibility settings, so teams can share a Schema Registry without risking naming collisions or configuration drift.
+    To enable contexts, set xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] to `true` and restart your brokers. Once enabled, you reference schemas using qualified subject syntax, for example `:.staging:my-topic-value`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for configuration examples and limitations.
     == New configuration properties
     **Storage mode:**
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -240,6 +240,49 @@ Curl:: @@
     When you register an evolved schema for an existing subject, the version `id` is incremented by 1.
+    == Use Schema Registry contexts
+    Starting in Redpanda v26.1, you can use contexts to create isolated namespaces for schemas, subjects, and configuration within a single Schema Registry instance.
+    ifndef::env-cloud[]
+    To use contexts, first set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`, then restart the broker. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for setup instructions.
+    endif::env-cloud[]
+    ifdef::env-cloud[]
+    To use contexts on BYOC and Dedicated clusters, xref:manage:cluster-maintenance/config-cluster.adoc[configure the cluster property] `schema_registry_enable_qualified_subjects`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for details.
+    endif::env-cloud[]
+    Contexts are created implicitly when you register a schema using a context-qualified subject. For example, registering a schema with the subject `:.staging:sensor-value` creates the `.staging` context if it does not already exist:
+    [source,bash]
+    ----
+    curl -s -X POST \
+      http://localhost:8081/subjects/:.staging:sensor-value/versions \
+      -H "Content-Type: application/vnd.schemaregistry.v1+json" \
+      -d '{"schema": "{\"type\":\"string\"}"}'
+    ----
+    === Scope API operations to a context
+    You can scope any Schema Registry API operation to a specific context in two ways:
+    * Qualified subjects: Use the `:<context>:<subject>` syntax wherever a subject is accepted. For example, to list subjects in the `.staging` context:
+    +
+    [source,bash]
+    ----
+    curl -s "http://localhost:8081/subjects?subjectPrefix=:.staging:"
+    ----
+    * Base URL prefix: Prefix any endpoint path with `/contexts/{context}/`. The server rewrites the request to operate within that context. This approach is recommended for non-Java SerDe clients that do not support qualified subject syntax:
+    +
+    [source,bash]
+    ----
+    curl -s http://localhost:8081/contexts/.staging/subjects
+    ----
+    Unqualified subjects continue to work and operate in the default context.
+    For the complete endpoint reference, see the link:/api/doc/schema-registry/[Schema Registry API reference].
     == Retrieve a schema
     To retrieve a registered schema from the registry, make a GET request to the `/schemas/ids/\{id}` endpoint:
@@ Expand Down Expand Up / @@ -1188,6 +1231,7 @@ endif::[] @@
     == Suggested reading
     ifndef::env-cloud[]
     * xref:manage:schema-reg/schema-reg-overview.adoc[]
+    * xref:manage:schema-reg/schema-reg-contexts.adoc[]
     * xref:reference:rpk/rpk-registry/rpk-registry.adoc[rpk registry]
     * link:/api/doc/schema-registry/[Schema Registry API]
     * xref:reference:node-configuration-sample.adoc[] (search for `schema_registry`)
@@ Expand All / @@ -1197,6 +1241,7 @@ ifndef::env-cloud[] @@
     endif::[]
     ifdef::env-cloud[]
     * xref:manage:schema-reg/schema-reg-overview.adoc[]
+    * xref:manage:schema-reg/schema-reg-contexts.adoc[]
     * xref:reference:rpk/rpk-registry/rpk-registry.adoc[rpk registry]
     * link:/api/doc/schema-registry/[Schema Registry API]
     * xref:manage:monitoring.adoc#service-level-queries[Monitor Schema Registry service-level metrics]
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc-1996: Schema Registry Contexts #1658

Uh oh!

Diff view

Diff view

There are no files selected for viewing

pgellert Apr 22, 2026

Uh oh!

Feediver1 Apr 22, 2026

Uh oh!

pgellert Apr 22, 2026

Uh oh!

mattschumpert Apr 23, 2026

Uh oh!

Uh oh!

Uh oh!

Doc-1996: Schema Registry Contexts #1658

Are you sure you want to change the base?

Uh oh!

Doc-1996: Schema Registry Contexts #1658

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

pgellert Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Feediver1 Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

pgellert Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

mattschumpert Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!