Skip to content

fix(DOC-2061): clarify schema reference name field per schema type #1613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mfernest wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(DOC-2061): clarify schema reference name field per schema type #1613

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion modules/manage/pages/schema-reg/schema-reg-api.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Copy link
Copy Markdown
Contributor

@pgellert pgellert Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: this would be a more realistic example

Suggested change
| 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`)

Comment on lines +660 to +662
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Avro wording should cover schemas without a namespace.

Current phrasing implies namespace is always present. For Avro records without namespace, the reference name is just the record name. Consider tweaking this sentence to avoid over-constraining users.

Suggested wording tweak 
-| 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`)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| Avro
| The fully qualified schema name, combining the namespace and record name (for example, `com.example.Address`)
| 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`)
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@modules/manage/pages/schema-reg/schema-reg-api.adoc` around lines 660 - 662,
Update the Avro description text under the "Avro" heading so it does not assume
a namespace is always present; change the sentence describing the "fully
qualified schema name" to explain that when a namespace exists it combines
namespace and record name (for example `com.example.Address`), and when no
namespace is defined the reference is just the record name; target the string
"The fully qualified schema name, combining the namespace and record name (for
example, `com.example.Address`)" and replace it with the clarified wording.

| JSON Schema
| A URI used in `$ref` to identify the referenced schema
Copy link
Copy Markdown
Contributor

@pgellert pgellert Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While this is true for Confluent's schema registry, we don't yet support external JSON schema references in redpanda's schema registry like this one.

So I think we should explicitly call this out here that this is not yet supported.

Copy link
Copy Markdown
Contributor

@pgellert pgellert Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related to this, the https://docs.redpanda.com/redpanda-cloud/manage/schema-reg/schema-reg-overview/#limitations page is also slightly incorrectly worded. Could you please reword that section to the following (or equivalent):

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.

External references — where $ref points to a schema registered under a different subject — are not supported. To structure complex JSON schemas, define referenced types within the same schema document using definitions/$defs or bundled $id schemas.

The current wording says that $ref, $defs/definitions, dependentSchemas/dependentRequired, and prefixItems are all rejected when compatibility is not NONE. This is too broad — internal $ref with definitions/$defs and bundled $id schemas all work correctly under BACKWARD compatibility.

|===

The following example registers a Protobuf schema in subject `test-simple` with a message name `Simple`.

[tabs]
====
Expand Down
Loading