Doc-1996: Schema Registry Contexts

local-antora-playbook.yml

@@ -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']

modules/ROOT/nav.adoc

@@ -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]

modules/console/pages/ui/schema-reg.adoc

@@ -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[]

modules/get-started/pages/release-notes/redpanda.adoc

@@ -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:**

modules/manage/pages/schema-reg/schema-reg-api.adoc

@@ -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:
@@ -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`)
@@ -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]