From cb6efd106bca811631db77973f8b6dc5b301c66c Mon Sep 17 00:00:00 2001 From: Michael Ernest Date: Tue, 17 Mar 2026 12:09:51 -0700 Subject: [PATCH 1/6] fix(DOC-2061): clarify schema reference name field per schema type Add a table explaining what the `name` field means in schema references for Protobuf (import path), Avro (fully qualified schema name), and JSON Schema (URI used in $ref). Co-Authored-By: Claude Sonnet 4.6 --- .../pages/schema-reg/schema-reg-api.adoc | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 6a8f7546e6..f9c3dfbfb8 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -648,7 +648,23 @@ A successful registration returns the schema's `id`: == Reference a schema -To build more complex schema definitions, you can add a reference to other schemas. The following example registers a Protobuf schema in subject `test-simple` with a message name `Simple`. +To build more complex schema definitions, you can add a reference to other schemas. A reference identifies another schema using a `name`, `subject`, and `version`. The meaning of `name` depends on the schema type: + +[cols="1,2"] +|=== +| Schema type | Reference name + +| Protobuf +| The import path used in the `.proto` file (for example, `import "simple";` uses name `simple`) + +| Avro +| The fully qualified schema name, combining the namespace and record name (for example, `com.example.Address`) + +| JSON Schema +| A URI used in `$ref` to identify the referenced schema +|=== + +The following example registers a Protobuf schema in subject `test-simple` with a message name `Simple`. [tabs] ==== From 05a5b1f028c07c3bd10285b16621247c799ecb6a Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 27 May 2026 16:22:30 -0500 Subject: [PATCH 2/6] Update modules/manage/pages/schema-reg/schema-reg-api.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gellért Peresztegi-Nagy --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index f9c3dfbfb8..8f7d3f856e 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -655,7 +655,7 @@ To build more complex schema definitions, you can add a reference to other schem | Schema type | Reference name | Protobuf -| The import path used in the `.proto` file (for example, `import "simple";` uses name `simple`) +| The import path used in the `.proto` file (for example, `import "simple.proto";` uses name `simple.proto`) | Avro | The fully qualified schema name, combining the namespace and record name (for example, `com.example.Address`) From bba27a74c52cd955e5667ce6ed026711901cff6f Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Wed, 27 May 2026 16:44:17 -0500 Subject: [PATCH 3/6] Update modules/manage/pages/schema-reg/schema-reg-api.adoc Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 8f7d3f856e..b83912fcc7 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -658,7 +658,7 @@ To build more complex schema definitions, you can add a reference to other schem | The import path used in the `.proto` file (for example, `import "simple.proto";` uses name `simple.proto`) | Avro -| The fully qualified schema name, combining the namespace and record name (for example, `com.example.Address`) +| The schema name used by Avro resolution: fully qualified (`namespace.name`) when a namespace is defined, or just the record name when it is not (for example, `com.example.Address` or `Address`) | JSON Schema | A URI used in `$ref` to identify the referenced schema From af400936fa852957ef89c77edf34845e5d8e14e8 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Thu, 28 May 2026 08:37:46 -0400 Subject: [PATCH 4/6] fix(DOC-2061): correct JSON Schema reference scope per @pgellert - Note in the schema-reg-api reference-name table that Redpanda's Schema Registry does not yet support external JSON Schema references (where $ref points to a different subject), and direct readers to the Limitations section for the supported alternatives. - Rewrite the JSON Schema Limitations section in schema-reg-overview to distinguish internal references and bundled $id schemas (supported) from external references (not supported). The previous wording implied any use of $ref or $defs would be rejected, which overstates the constraint. Co-Authored-By: Claude Opus 4.7 --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 +- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 9 ++------- 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index b83912fcc7..1dd35e8499 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -661,7 +661,7 @@ To build more complex schema definitions, you can add a reference to other schem | The schema name used by Avro resolution: fully qualified (`namespace.name`) when a namespace is defined, or just the record name when it is not (for example, `com.example.Address` or `Address`) | JSON Schema -| A URI used in `$ref` to identify the referenced schema +| Used to identify the referenced schema in `$ref`. Redpanda's Schema Registry does not yet support external JSON Schema references (where `$ref` points to a schema registered under a different subject). To structure complex JSON schemas, define referenced types within the same schema document using `definitions` / `$defs` or bundled `$id` schemas. See xref:manage:schema-reg/schema-reg-overview.adoc#limitations[JSON Schema limitations]. |=== The following example registers a Protobuf schema in subject `test-simple` with a message name `Simple`. diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index c8a6485899..3d757a79bc 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -146,14 +146,9 @@ All CRUD operations are supported for the JSON Schema (`json-schema`), and Redpa Schemas are held in subjects. Subjects have a compatibility configuration associated with them, either directly specified by a user, or inherited by the default. See `PUT /config` and `PUT/config/\{subject}` in the link:/api/doc/schema-registry/[Schema Registry API]. -If you have inserted a second schema into a subject where the compatibility level is anything but `NONE`, then any JSON Schema containing the following items are rejected: +JSON Schema supports internal references (`$ref` using JSON Pointer fragments such as `#/definitions/...` or `#/$defs/...`) and bundled schemas (sub-schemas with their own `$id` defined within the same document). These work correctly with all compatibility levels. -* `$ref` -* `$defs` (`definitions` prior to draft 2019-09) -* `dependentSchemas` / `dependentRequired` (`dependencies` prior to draft 2019-09) -* `prefixItems` - -Consequently, you cannot https://json-schema.org/understanding-json-schema/structuring[structure a complex schema^] using these features. +External references, where `$ref` points to a schema registered under a different subject, are not supported. To https://json-schema.org/understanding-json-schema/structuring[structure complex JSON schemas^], define referenced types within the same schema document using `definitions` / `$defs` or bundled `$id` schemas. ifndef::env-cloud[] Additionally, you cannot have xref:manage:schema-reg/schema-id-validation.adoc#about-schema-id-validation[schema ID validation] with JSON schemas if the xref:manage:schema-reg/schema-id-validation.adoc#set-subject-name-strategy-per-topic[subject name strategy] _is not_ `TopicNameStrategy`. From 0c3d926cd6debbadea31ff099efc83f98bbc777a Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Fri, 29 May 2026 13:58:39 -0500 Subject: [PATCH 5/6] Update modules/manage/pages/schema-reg/schema-reg-api.adoc Co-authored-by: Michele Cyran --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index 1dd35e8499..bad2638983 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -658,7 +658,7 @@ To build more complex schema definitions, you can add a reference to other schem | The import path used in the `.proto` file (for example, `import "simple.proto";` uses name `simple.proto`) | Avro -| The schema name used by Avro resolution: fully qualified (`namespace.name`) when a namespace is defined, or just the record name when it is not (for example, `com.example.Address` or `Address`) +| The schema name used by Avro resolution: fully qualified (`namespace.name`) when a namespace is defined, or just the record name when it is not (for example, `com.example.Address` or `Address`). | JSON Schema | Used to identify the referenced schema in `$ref`. Redpanda's Schema Registry does not yet support external JSON Schema references (where `$ref` points to a schema registered under a different subject). To structure complex JSON schemas, define referenced types within the same schema document using `definitions` / `$defs` or bundled `$id` schemas. See xref:manage:schema-reg/schema-reg-overview.adoc#limitations[JSON Schema limitations]. From 586c10d5fdc0b43b8aa86996c29ca742020b621b Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Fri, 29 May 2026 13:59:04 -0500 Subject: [PATCH 6/6] Update modules/manage/pages/schema-reg/schema-reg-api.adoc Co-authored-by: Michele Cyran --- modules/manage/pages/schema-reg/schema-reg-api.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-api.adoc b/modules/manage/pages/schema-reg/schema-reg-api.adoc index bad2638983..952f464811 100644 --- a/modules/manage/pages/schema-reg/schema-reg-api.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-api.adoc @@ -655,7 +655,7 @@ To build more complex schema definitions, you can add a reference to other schem | Schema type | Reference name | Protobuf -| The import path used in the `.proto` file (for example, `import "simple.proto";` uses name `simple.proto`) +| The import path used in the `.proto` file (for example, `import "simple.proto";` uses name `simple.proto`). | Avro | The schema name used by Avro resolution: fully qualified (`namespace.name`) when a namespace is defined, or just the record name when it is not (for example, `com.example.Address` or `Address`).