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

[mfernest]

Summary

• Adds a table to the "Reference a schema" section explaining what the name field means per schema type:
  • Protobuf: the import path in the .proto file
  • Avro: the fully qualified schema name (namespace + record name)
  • JSON Schema: a URI used in $ref

Resolves DOC-2061.

Test plan

• Deploy preview renders table correctly
• Table appears before the Protobuf example

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	cb6efd1
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/69b9a70fcfdd8000080813d3
😎 Deploy Preview	https://deploy-preview-1613--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

📝 Walkthrough

Walkthrough

The "Reference a schema" section in the schema registration API documentation was expanded to provide more prescriptive guidance on identifying schema references. The changes add explicit field definitions (name, subject, version), introduce a mapping table showing how the reference name field is interpreted differently across schema types (Protobuf, Avro, JSON Schema), and clarify that the semantic meaning of the name field is type-dependent. The existing Protobuf example remains intact.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers the key changes and includes a JIRA reference, but is missing the required template sections like 'Page previews' and 'Checks' checkboxes.	Complete the PR description template by adding the 'Page previews' section with deployment preview links and checking the appropriate 'Checks' box (likely 'Content gap' or 'Small fix').

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: clarifying schema reference name field behavior per schema type.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/doc-2061-schema-reference-name

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@modules/manage/pages/schema-reg/schema-reg-api.adoc`:
- Around line 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.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 818ab3cf-13c1-474e-a77a-b2608584977f

📥 Commits

Reviewing files that changed from the base of the PR and between fe8a357 and cb6efd1.

📒 Files selected for processing (1)

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

[coderabbitai]

⚠️ 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.