diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 0590286e59..9c61c888e5 100644 --- a/local-antora-playbook.yml +++ b/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: DOC-1812-Document-Cloud-Feature-Schema-Registry-Contexts-Serverless-etc - url: https://github.com/redpanda-data/redpanda-labs branches: main start_paths: [docs,'*/docs'] diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index f6cdd63007..36118d2ef7 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -205,6 +205,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] diff --git a/modules/manage/pages/schema-reg/schema-reg-contexts.adoc b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc new file mode 100644 index 0000000000..8502d6c392 --- /dev/null +++ b/modules/manage/pages/schema-reg/schema-reg-contexts.adoc @@ -0,0 +1,739 @@ += Schema Registry Contexts +:description: Use Schema Registry contexts to create isolated namespaces for schemas, subjects, and configuration—enabling multi-tenant and multi-team deployments without separate Schema Registry instances. +:page-tags: [Schema Registry, contexts, multi-tenant, Confluent compatibility] +// Learning objectives: +// - Understand what Schema Registry contexts are and when to use them. +// - Understand the qualified subject syntax (::). +// - Enable the feature using the cluster configuration property (requires broker restart). +// - Configure contexts, including per-context mode and compatibility settings. +// - Apply ACLs to control access at the context level. +// - Identify updated metrics and the new cluster configuration property. +// - Resolve common issues related to upgrade, schema ID lookups, and subject naming. + +// Single-sourcing tags: Cloud-only content is wrapped in ifdef::env-cloud[] ... endif::[] +// Self-managed-only content is wrapped in ifndef::env-cloud[] ... endif::[] + +// tag::single-source[] +Schema Registry contexts are namespaces that isolate schemas, subjects, and configuration from one another within a single Schema Registry instance. +Each context maintains its own schema ID counter, mode settings, and compatibility settings. +Unqualified subjects continue to work unchanged in the implicit default context. + +Schema Registry contexts is compatible with the Confluent Schema Registry Contexts API and requires no enterprise license. + +== When to use contexts + +Contexts are most useful in the following scenarios: + +* *Multi-team deployments on a shared cluster*: Teams can register schemas independently under their own contexts without risking naming collisions or configuration drift. +* *Schema migration from Confluent Schema Registry*: Confluent Schema Registry uses contexts to namespace schemas. If your existing workflows or tooling rely on contexts, Redpanda's compatible implementation lets you migrate without restructuring your schema layout. +* *Multi-cluster schema syncing and disaster recovery*: Dedicated namespaces reduce schema ID collision risk when syncing schemas across clusters. + +ifdef::env-cloud[] +NOTE: On Serverless clusters, Redpanda uses contexts internally for per-tenant isolation. Contexts are not exposed to end users on Serverless. On BYOC and Dedicated clusters, contexts are available and user-configurable. +endif::env-cloud[] + +== Prerequisites + +Before using Schema Registry contexts, ensure that: + +* You are running Redpanda v26.1 or later. +* The `schema_registry_enable_qualified_subjects` cluster configuration property is set to `true`. ++ +[IMPORTANT] +==== +The `schema_registry_enable_qualified_subjects` property defaults to `false`, so you must explicitly enable it. After changing it, you must restart your brokers for the change to take effect. If qualified subjects are still being treated as literal names after enabling the flag, a broker restart is the most likely cause. +==== ++ +* If you use Schema Registry ACLs, ensure the principal interacting with a context has the appropriate permissions. See <>. + +== Limitations + +* *Console and rpk*: Native support for context management operations (listing, creating, and deleting contexts) in the Redpanda Console UI and `rpk` CLI is not available. Use the Schema Registry HTTP API directly. See <>. +* *Non-Java SerDe clients*: Non-Java serializer/deserializer clients do not natively support qualified subjects. Instead, point these clients at the `/contexts/{context}/...` base URL path prefix. See <>. +* *Server-side schema ID validation*: Schema ID validation using Kafka record headers does not support contexts. +* *Iceberg topics*: Context-aware schema IDs are not surfaced in Iceberg topic integration. +* *`referencedby` endpoint*: `GET /subjects/{subject}/versions/{version}/referencedby` returns a list of bare schema IDs with no context information. When references span contexts, it is not possible to determine which context each returned ID belongs to. +* *Cross-context isolation*: Contexts provide organizational and ID-space isolation, but do not prevent cross-context schema references. There is no mechanism to block schemas in one context from referencing schemas in another context. +* *Default context cannot be deleted*: You cannot delete the default context (`.`). +* *Breaking change on upgrade*: After enabling `schema_registry_enable_qualified_subjects`, any existing subject whose name matches the qualified subject pattern (for example, `:.staging:user-value`) is reinterpreted as subject `user-value` in context `.staging` rather than as a literal subject name in the default context. See <>. + + +== How Schema Registry contexts work + +=== Schema ID isolation + +Before contexts, the Schema Registry maintained a single global ID counter. All schemas shared one ID space, and a given schema ID pointed to exactly one schema across the entire registry. + +After enabling contexts, *each context has its own independent ID counter*. This means schema ID `1` in `.staging` and schema ID `1` in `.production` are different schemas. As a result, `GET /schemas/ids/{id}` searches the *default context only* by default. To retrieve a schema by ID from a non-default context, you must pass the `subject` query parameter to scope the lookup: + +[source,bash] +---- +GET /schemas/ids/1?subject=:.staging:my-topic +---- + +See also <>. + +=== Configuration resolution order + +Before contexts, mode and compatibility settings resolved as: + +---- +Subject → Global → Built-in defaults +---- + +After enabling contexts, a context layer sits between subject and global: + +---- +Subject → Context → Global (.:.__GLOBAL:) → Built-in defaults +---- + +For example, setting the `.staging` context to `IMPORT` mode means all subjects in `.staging` inherit `IMPORT` unless they have a subject-level override, even if the global mode is `READWRITE`. + +Use `defaultToGlobal=true` on `GET /config` and `GET /mode` requests to see the effective value after full fallback resolution. + +=== Qualified subject syntax + +Wherever the Schema Registry API accepts a subject, you can supply a qualified subject instead of a bare subject name: + +[cols="2,1,2", options="header"] +|=== +| Input | Context | Subject + +| `user-events-value` +| `.` (default) +| `user-events-value` + +| `:.staging:user-events-value` +| `.staging` +| `user-events-value` + +| `:.:user-events-value` +| `.` (default) +| `user-events-value` + +| `:.staging:` +| `.staging` +| (empty — used for context-level config/mode operations) +|=== + +=== `GET /subjects` behavior change + +After enabling the flag, `GET /subjects` (with no `subjectPrefix`) returns subjects across *all* contexts. Non-default context subjects appear with their qualified names — for example, `:.staging:my-topic`. This is a behavioral change from the previous flat list of bare subject names. + +=== Cross-context schema references + +Contexts do not enforce isolation of schema references. Schemas can reference schemas in any other context. Unqualified references in schema definitions resolve within the same context as the root schema, not the default context. Qualified references can reach any context explicitly (for example, `:.shared:CommonType`). + +== Enable Schema Registry contexts + +ifndef::env-cloud[] +To enable contexts on a self-managed cluster, set the `schema_registry_enable_qualified_subjects` cluster configuration property to `true`: + +[source,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +---- + +[IMPORTANT] +==== +This property requires a broker restart. The change does not take effect until all brokers have restarted. +==== + +To verify the current setting: + +[source,bash] +---- +rpk cluster config get schema_registry_enable_qualified_subjects +---- +endif::env-cloud[] + +ifdef::env-cloud[] +NOTE: On BYOC and Dedicated clusters, contact Redpanda support or use the cluster configuration API to enable `schema_registry_enable_qualified_subjects`. This property requires a broker restart. +endif::env-cloud[] + +== Configure Schema Registry contexts + +=== Register a schema in a context + +To register a schema in a named context, use the qualified subject form in the `POST /subjects/{subject}/versions` request: + +[source,bash] +---- +curl -s -X POST \ + http://localhost:8081/subjects/:.staging:my-topic/versions \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"schema": "{\"type\":\"string\"}"}' +---- + +The schema ID returned is unique within the `.staging` context and independent of schema IDs in other contexts. + +=== List contexts + +To list all materialized contexts (those that have had at least one schema registered), use `GET /contexts`: + +[source,bash] +---- +curl -s http://localhost:8081/contexts +---- + +Example response: + +[source,json] +---- +[".","staging","production"] +---- + +NOTE: A context is only listed after at least one schema has been registered in it. Pre-configuring mode or compatibility alone does not cause a context to appear in this list. The default context (`.`) is always included. + +=== List subjects using subject prefix filtering + +The `subjectPrefix` query parameter on `GET /subjects` lets you scope subject listings precisely. The following table shows supported patterns: + +[cols="2,3", options="header"] +|=== +| Prefix | Matches + +| `my-` +| Subjects starting with `my-` in the default context only + +| `:.staging:` +| All subjects in the `.staging` context + +| `:.staging:my-` +| Subjects starting with `my-` in the `.staging` context + +| `:*:` +| All subjects in all contexts + +| `:*:my-` +| Subjects starting with `my-` across all contexts +|=== + +[source,bash] +---- +# All subjects in the .staging context +curl -s "http://localhost:8081/subjects?subjectPrefix=:.staging:" + +# All subjects across all contexts +curl -s "http://localhost:8081/subjects?subjectPrefix=:*:" +---- + +You can also list subjects within a context using the `/contexts/{context}/subjects` path: + +[source,bash] +---- +curl -s http://localhost:8081/contexts/.staging/subjects +---- + +=== Set context-level mode + +Mode can be set at the context level by specifying a qualified subject with an empty subject name (`::`): + +[source,bash] +---- +# Set the .staging context to IMPORT mode +curl -s -X PUT \ + http://localhost:8081/mode/:.staging: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"mode": "IMPORT"}' + +# Get the mode for the .staging context +# Use defaultToGlobal=true to see the effective value after fallback resolution +curl -s "http://localhost:8081/mode/:.staging:?defaultToGlobal=true" +---- + +=== Set context-level compatibility + +[source,bash] +---- +# Set compatibility for the .staging context +curl -s -X PUT \ + http://localhost:8081/config/:.staging: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"compatibility": "BACKWARD"}' + +# Get compatibility for a specific subject within a context +# Use defaultToGlobal=true to see the effective value after fallback +curl -s "http://localhost:8081/config/:.staging:my-topic?defaultToGlobal=true" +---- + +=== Set the global context fallback + +The `.:.__GLOBAL:` context provides the lowest-priority fallback for all contexts and subjects that do not have their own explicit setting: + +[source,bash] +---- +# Get the current global mode +curl -s http://localhost:8081/mode/:.__GLOBAL: + +# Set global default compatibility +curl -s -X PUT \ + http://localhost:8081/config/:.__GLOBAL: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"compatibility": "FULL"}' +---- + +NOTE: `.__GLOBAL` is a reserved context name and cannot be used as a regular context name. + +=== Retrieve schema references with qualified names + +Use `referenceFormat=qualified` on `GET /subjects/{subject}/versions/{version}` to return references with context-qualified subject names instead of bare names: + +[source,bash] +---- +curl -s "http://localhost:8081/subjects/:.staging:my-topic/versions/1?referenceFormat=qualified" +---- + +This is useful when schemas span multiple contexts and you need to disambiguate reference targets. + +=== Use a context as the client base URL + +You can point a Schema Registry client at a specific context by setting the client's Schema Registry URL to `${host}/contexts/{context}`. Redpanda rewrites requests under this path prefix to operate within the specified context. This is the recommended workaround for non-Java SerDe clients that do not yet support qualified subject syntax natively: + +---- +# All requests to this base URL operate within the .staging context +http://localhost:8081/contexts/.staging +---- + +=== Pre-configure a context before registering schemas + +You can set mode or compatibility on a context before any schemas are registered in it: + +[source,bash] +---- +curl -s -X PUT \ + http://localhost:8081/mode/:.new-team: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"mode": "READONLY"}' +---- + +Schema registrations in `:.new-team:` will be rejected until the mode is changed to `READWRITE`. + +=== Cross-context schema references + +Schemas can reference schemas in other contexts using qualified subject names in the `references` field: + +[source,json] +---- +{ + "schema": "...", + "references": [ + { + "name": "CommonType", + "subject": ":.shared:CommonType", + "version": 1 + } + ] +} +---- + +Unqualified references in schema definitions resolve to the same context as the root schema, not the default context. + +=== Delete a context + +A context can only be deleted when it contains no subjects. Soft-deleted subjects still count — you must hard-delete all subjects before the context can be removed. Attempting to delete a non-empty context returns a `context_not_empty` error. + +[NOTE] +==== +The default context (`.`) cannot be deleted. +==== + +[source,bash] +---- +# Hard-delete all subjects in the context first +curl -s -X DELETE "http://localhost:8081/subjects/:.staging:my-topic?permanent=true" + +# Then delete the empty context +curl -s -X DELETE http://localhost:8081/contexts/.staging +---- + +== Cluster configuration property + +`schema_registry_enable_qualified_subjects`:: ++ +[cols="1,3"] +|=== +| Type | Boolean +| Default (26.1) | `false` +| Default (26.2) | `true` +| Removed in | 26.3 (always enabled) +| Restart required | Yes +|=== ++ +When `false`, subjects are treated as literal strings (existing behavior). When `true`, subjects matching the `::` pattern are parsed as context-qualified subjects. ++ +[IMPORTANT] +==== +This is not a dynamic property. Broker restart is required after changing this value. +==== ++ +ifndef::env-cloud[] +[source,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +---- +endif::env-cloud[] + +== rpk commands + +[NOTE] +==== +Native `rpk` commands for context management operations (listing, creating, and deleting contexts) are not yet available. Use the Schema Registry HTTP API directly for context-level operations. See <>. +==== + +Existing `rpk registry` commands that accept a subject name support qualified subject syntax once `schema_registry_enable_qualified_subjects` is enabled. Pass a qualified subject wherever a `--subject` flag is accepted: + +[source,bash] +---- +# Register a schema in a named context +rpk registry schema create \ + --subject ":.staging:my-topic" \ + --schema my-schema.avsc \ + --type avro + +# List schemas for a subject in a named context +rpk registry schema list \ + --subject ":.staging:my-topic" + +# Get a specific schema version from a context +rpk registry schema get \ + --subject ":.staging:my-topic" \ + --version 1 + +# Check compatibility for a subject in a context +rpk registry schema check-compatibility \ + --subject ":.staging:my-topic" \ + --schema my-schema-v2.avsc + +# Get the compatibility level for a context +rpk registry compatibility-level get \ + --subject ":.staging:" + +# Set the compatibility level for a context +rpk registry compatibility-level set \ + --subject ":.staging:" \ + --level BACKWARD + +# Get the mode for a context +rpk registry mode get \ + --subject ":.staging:" + +# Set the mode for a context +rpk registry mode set \ + --subject ":.staging:" \ + --mode READONLY + +# Delete a subject within a context (soft delete) +rpk registry subject delete \ + --subject ":.staging:my-topic" + +# List all subjects (returns qualified names for non-default contexts) +rpk registry subject list + +# Grant read access to all subjects in a context (prefix ACL) +rpk security acl create \ + --registry-subject ":.staging:" \ + --resource-pattern-type prefixed \ + --operation read \ + --allow-principal User:alice +---- + +For full reference documentation on these commands, see: + +* xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-list.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-get.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-schema-check-compatibility.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-mode-get.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-mode-set.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-subject-delete.adoc[] +* xref:reference:rpk/rpk-registry/rpk-registry-subject-list.adoc[] + +== Client integration status + +[#client-integration-status] + +[cols="2,1,3", options="header"] +|=== +| Client | Status | Notes + +| Schema Registry API (all operations) +| Full support +| Use qualified subjects directly in any endpoint. + +| Java SerDe (Confluent) +| Supported +| Requires a custom `ContextNameStrategy`. See the Confluent SerDe documentation for details. + +| Non-Java SerDe +| Not yet supported (26.1) +| Planned in a 26.1.x patch release. Workaround: set the client's Schema Registry base URL to `http://:8081/contexts/{context}`. + +| rpk +| In progress +| Context management commands not yet available. Qualified subjects work in existing `rpk registry` commands. + +| Redpanda Console +| In progress +| Not available in 26.1. + +| Server-side schema ID validation +| Not supported +| Out of scope for this release. +|=== + +== ACL authorization + +[#acl-authorization] + +Contexts use the existing `sr_subject` and `sr_registry` ACL resource types. No new resource types are needed. + +[cols="2,2,2", options="header"] +|=== +| Operation | ACL resource | Permission required + +| Context-level config/mode (`PUT /config/::`, `PUT /mode/::`) +| `sr_registry` +| `alter_configs` + +| Read context-level config/mode +| `sr_registry` +| `describe_configs` + +| List subjects / list contexts +| `sr_subject` (results filtered to accessible subjects) +| `describe` + +| Delete a context (`DELETE /contexts/{context}`) +| `sr_registry` +| `delete` + +| Schema CRUD on a subject +| `sr_subject` on the specific subject +| `read` / `write` / `delete` + +| Subject-level config/mode +| `sr_subject` on the specific subject +| `alter_configs` / `describe_configs` +|=== + +=== Grant access to all subjects in a context + +Use a prefix ACL on `sr_subject` with `--resource-pattern-type prefixed` to grant access to all current and future subjects within a context: + +[source,bash] +---- +rpk security acl create \ + --registry-subject ":.staging:" \ + --resource-pattern-type prefixed \ + --operation read \ + --allow-principal User:alice \ + --brokers +---- + +=== Audit log format + +When Schema Registry ACLs are enabled, audit log entries include the fully qualified subject name for non-default context operations: + +[source,json] +---- +{ + "resources": [ + { + "name": ":.staging:my-topic", + "type": "subject" + } + ] +} +---- + +Default context subjects are logged with their unqualified name (no change from existing behavior). + +== Metrics + +The following Schema Registry metrics have been updated to include a `context` label, enabling per-context monitoring: + +[cols="2,2", options="header"] +|=== +| Metric | Change + +| `*_schema_registry_cache_schema_count` +| New `context` label added. + +| `*_schema_registry_cache_subject_count` +| New `context` label added. + +| `*_schema_registry_cache_subject_version_count` +| New `context` label added. +|=== + +The count of non-default contexts is also included in Redpanda's phone-home telemetry. + +For the full metrics reference, see xref:reference:public-metrics-reference.adoc[]. + +== Upgrade considerations + +[#upgrade-considerations] + +[IMPORTANT] +==== +*Breaking change*: When `schema_registry_enable_qualified_subjects` is enabled, any existing subject whose name matches the qualified subject pattern — for example, `:.staging:user-value` — is reinterpreted as subject `user-value` in context `.staging`, rather than as a literal subject name in the default context. Subjects without a `:.` prefix are unaffected. + +This edge case is expected to be rare. No automatic migration is provided. +==== + +To audit your existing subjects for affected names before enabling the feature: + +ifndef::env-cloud[] +[source,bash] +---- +rpk registry subject list | grep '^\.' +---- +endif::env-cloud[] + +ifdef::env-cloud[] +[source,bash] +---- +curl -s http://:8081/subjects | jq '.[] | select(startswith(":."))' +---- +endif::env-cloud[] + +If affected subjects are found, rename them before enabling the property, or plan to re-register them under the reinterpreted context structure after enabling. + +In 26.2, if you need additional time to migrate, you can temporarily set `schema_registry_enable_qualified_subjects` to `false` to restore literal behavior while you complete the migration. This option is removed in 26.3, after which contexts are always enabled. + +[IMPORTANT] +==== +Remember that changing `schema_registry_enable_qualified_subjects` requires a broker restart in both directions (enabling and disabling). +==== + +== Troubleshooting + +[#schema-id-lookup-fails] +=== Schema ID lookup returns 404 or wrong schema + +*Symptom*: `GET /schemas/ids/{id}` returns a 404 or returns the wrong schema after registering a schema in a non-default context. + +*Cause*: `GET /schemas/ids/{id}` searches the *default context only*. A schema registered in `:.staging:my-topic` (returning ID `1`) is not found by `GET /schemas/ids/1` without a context hint. + +*Resolution*: Pass the `subject` query parameter to scope the lookup to the correct context: + +[source,bash] +---- +curl -s "http://localhost:8081/schemas/ids/1?subject=:.staging:my-topic" +---- + +=== Qualified subjects not recognized (treated as literal names) + +*Symptom*: Subjects with the `:.` prefix are stored as literal subject names in the default context instead of being parsed as context-qualified subjects. + +*Cause 1*: `schema_registry_enable_qualified_subjects` is set to `false` (the 26.1 default for self-managed clusters). + +*Cause 2*: The property was set to `true` but the brokers have not yet been restarted. This property is not dynamic and requires a full broker restart to take effect. + +*Resolution*: + +ifndef::env-cloud[] +[source,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +# Then restart all brokers +---- +endif::env-cloud[] + +=== Schema registration fails after upgrading to 26.1 + +*Symptom*: A `POST /subjects/{subject}/versions` request returns an unexpected error after upgrading and enabling the flag. + +*Cause*: An existing subject whose name begins with `:.` has been reinterpreted as a context-qualified subject. If the inferred context was pre-configured in `READONLY` mode, new registrations are rejected. + +*Resolution*: Check for affected subject names: + +ifndef::env-cloud[] +[source,bash] +---- +rpk registry subject list | grep '^\.' +---- +endif::env-cloud[] + +Rename affected subjects or change the inferred context's mode: + +[source,bash] +---- +curl -s -X PUT http://localhost:8081/mode/:.affected-context: \ + -H "Content-Type: application/vnd.schemaregistry.v1+json" \ + -d '{"mode": "READWRITE"}' +---- + +=== Context cannot be deleted + +*Symptom*: `DELETE /contexts/{context}` returns a `context_not_empty` error even though all subjects appear to have been deleted. + +*Cause*: Soft-deleted subjects still count toward the non-empty check. Subjects must be hard-deleted (permanently deleted) before the context can be removed. Also note that the default context (`.`) cannot be deleted under any circumstances. + +*Resolution*: Hard-delete all subjects in the context, then retry: + +[source,bash] +---- +# Soft-delete (if not already done) +curl -s -X DELETE "http://localhost:8081/subjects/:.staging:my-topic" + +# Hard-delete (permanent) +curl -s -X DELETE "http://localhost:8081/subjects/:.staging:my-topic?permanent=true" + +# Retry context deletion +curl -s -X DELETE http://localhost:8081/contexts/.staging +---- + +=== `GET /contexts` does not list my context + +*Symptom*: A context that you believe exists does not appear in `GET /contexts`. + +*Cause*: A context is only materialized (and returned by `GET /contexts`) after at least one schema has been registered in it. Pre-configuring mode or compatibility does not create a listed context. + +*Resolution*: Register at least one schema in the context to materialize it, or verify that at least one subject exists under the context. + +=== Cross-context reference resolution fails + +*Symptom*: A schema registration that includes references to subjects in another context fails with a subject-not-found error. + +*Cause*: Unqualified references in schema definitions resolve within the same context as the root schema, not in the default context. + +*Resolution*: Use fully qualified references in the schema definition: + +[source,json] +---- +{ + "references": [ + { + "name": "CommonType", + "subject": ":.shared:CommonType", + "version": 1 + } + ] +} +---- + +=== `referencedby` returns IDs with no context information + +*Symptom*: `GET /subjects/{subject}/versions/{version}/referencedby` returns schema IDs, but you cannot determine which context each ID belongs to. + +*Cause*: This is a known limitation of the `referencedby` endpoint. It returns bare schema IDs with no context metadata. When references span contexts, the returned IDs are ambiguous. + +*Resolution*: There is no workaround in 26.1. To identify which schema an ID belongs to, try resolving the ID against each relevant context using `GET /schemas/ids/{id}?subject=::`. + +== Related topics + +* xref:manage:schema-reg/schema-reg-overview.adoc[] +* xref:manage:schema-reg/schema-reg-api.adoc[] +* xref:manage:schema-reg/schema-reg-authorization.adoc[] +* xref:reference:public-metrics-reference.adoc[] +ifndef::env-cloud[] +* xref:reference:cluster-properties.adoc[] +endif::env-cloud[] +ifdef::env-cloud[] +* xref:reference:properties/cluster-properties.adoc[] +endif::env-cloud[] +// end::single-source[]