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

| 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
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
|===

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

[tabs]
====
Expand Down
Loading