fix(DOC-2061): clarify schema reference name field per schema type#1613
Conversation
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 <[email protected]>
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThe "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 | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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
📒 Files selected for processing (1)
modules/manage/pages/schema-reg/schema-reg-api.adoc
|
@mfernest Please add the SME/Reviewer here! |
|
@BenPope please could you confirm if these changes are correct |
Co-authored-by: Gellért Peresztegi-Nagy <[email protected]>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
- 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 <[email protected]>
Feediver1
requested review from
kbatuigas and
pgellert
and removed request for
BenPope
|
@pgellert — thanks for the thorough review back in April. Sorry for the long delay; One scope question on the wording: I went with "not yet support" for external JSON Schema references on both pages, implying it's something on the roadmap rather than an architectural limitation. If that's wrong — i.e., if external cross-subject (Note: |
The "not yet supported" wording makes sense to me. There's no architectural limitation to us supporting it, but I also wouldn't say it's on a near-term committed roadmap. We certainly should support it, but I don't have a timeline for supporting it at the moment. I'll let you decide whether that would fit the "not yet supported" or "do not support" phrasing. :) |
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
please just add the suggested periods!
Co-authored-by: Michele Cyran <[email protected]>
Co-authored-by: Michele Cyran <[email protected]>
6 participants
Summary
Resolves DOC-2061.
Adds a reference-name table to the "Reference a schema" section of
schema-reg-api.adoc, and corrects the JSON Schema Limitations section onschema-reg-overview.adocper@pgellert's review.This PR was originally opened by
@mfernest, who is no longer with the team.@Feediver1is taking it over to land the remaining work after@pgellert's 2026-04-01 review.What changed
schema-reg-api.adoc, explaining what thenamefield means per schema type:.protofile (for example,import "simple.proto";uses namesimple.proto)namespace.name) when a namespace is defined, or just the record name when it is not$ref, with a note that Redpanda's Schema Registry does not yet support external references (where$refpoints to a schema in a different subject), and a link to the limitationsschema-reg-overview.adoc. The previous wording implied any use of$ref,$defs,definitions,dependentSchemas,dependentRequired, orprefixItemswas rejected. Per@pgellert, that overstates the constraint: internal references via JSON Pointer fragments (#/definitions/...,#/$defs/...) and bundled schemas with their own$iddo work; only external references (cross-subject) are unsupported.Review history
@kbatuigasbba27a74@pgellert@JakeSCahill@BenPope, who is no longer at Redpanda; substantive SME is@pgellertPreview pages
Test plan
🤖 Generated with Claude Code