Add contexts and sync Schema Registry API spec to source#65
Add contexts and sync Schema Registry API spec to source#65
Conversation
|
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:
📝 WalkthroughWalkthroughThis pull request bumps the Schema Registry API specification from version 1.1.2 to 1.2.0 with two main changes. First, it extends the API documentation with an external docs overlay describing Redpanda's Schema Registry contexts feature (available in v26.1+), explaining context scoping via path parameters and context-qualified subjects. Second, it updates the OpenAPI specification to introduce context management endpoints ( Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 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)
Comment |
🤖 Redpanda/schema-registry API structural change detectedStructural change detailsAdded (3)
Modified (7)
Powered by Bump.sh |
![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
🧹 Nitpick comments (1)
schema-registry/schema-registry.json (1)
469-475: Use one canonical context-qualified subject syntax in docsThe subject-query examples use
"<:.context:...>", while the rest of the spec consistently documents:.<context>:style. Please normalize these descriptions to one format to avoid client confusion.Also applies to: 530-535, 583-588, 646-651
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@schema-registry/schema-registry.json` around lines 469 - 475, Update the "subject" query parameter descriptions to use the canonical context-qualified syntax :.<context>: (and :.<context>:subject when referencing subject-specific lookup) instead of the inconsistent "<:.context:...>" form; edit the "subject" parameter descriptions (the JSON objects with "name": "subject") at the noted occurrences so they consistently show :.<context>: and :.<context>:subject examples and wording throughout the schema-registry.json.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@schema-registry/schema-registry.json`:
- Around line 1693-1698: The schema_metadata_request uses a oneOf inside
additionalProperties which is invalid for OpenAPI 2.0; remove the oneOf and
replace it with a single schema that expresses the allowed primitive types (for
example use "type": ["string","number","boolean"]) under additionalProperties so
the spec validates and SDK/doc tooling can process schema_metadata_request
correctly.
---
Nitpick comments:
In `@schema-registry/schema-registry.json`:
- Around line 469-475: Update the "subject" query parameter descriptions to use
the canonical context-qualified syntax :.<context>: (and :.<context>:subject
when referencing subject-specific lookup) instead of the inconsistent
"<:.context:...>" form; edit the "subject" parameter descriptions (the JSON
objects with "name": "subject") at the noted occurrences so they consistently
show :.<context>: and :.<context>:subject examples and wording throughout the
schema-registry.json.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 03a25645-9d16-46e8-9b50-0e6aa607bd7e
📒 Files selected for processing (2)
schema-registry/overlays/add-external-docs.yamlschema-registry/schema-registry.json
| "additionalProperties": { | ||
| "oneOf": [ | ||
| { "type": "string" }, | ||
| { "type": "number" }, | ||
| { "type": "boolean" } | ||
| ] |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python -m pip install --quiet openapi-spec-validator==0.7.1
python - <<'PY'
import json
import sys
from openapi_spec_validator import validate_spec
path = "schema-registry/schema-registry.json"
with open(path, "r", encoding="utf-8") as f:
spec = json.load(f)
try:
validate_spec(spec)
print("VALID:", path)
except Exception as e:
print("INVALID:", path)
print(type(e).__name__ + ":", e)
sys.exit(1)
PYRepository: redpanda-data/api-docs
Length of output: 953
Remove oneOf from additionalProperties in schema_metadata_request
Lines 1693-1698 use oneOf inside additionalProperties, which violates OpenAPI 2.0 schema constraints and breaks spec validation. This prevents SDK generation and documentation tooling from processing the schema correctly.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@schema-registry/schema-registry.json` around lines 1693 - 1698, The
schema_metadata_request uses a oneOf inside additionalProperties which is
invalid for OpenAPI 2.0; remove the oneOf and replace it with a single schema
that expresses the allowed primitive types (for example use "type":
["string","number","boolean"]) under additionalProperties so the spec validates
and SDK/doc tooling can process schema_metadata_request correctly.
Replace oneOf (string/number/boolean) with type: string in additionalProperties of schema_metadata_request. The oneOf keyword is not part of the Swagger 2.0 spec and breaks SDK generators. Values are converted to strings by the server, so type: string accurately reflects the API behavior. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix version phrasing in overlay: "v26.1 and later" -> "version 26.1 or later"
- Fix comma splice in schema_metadata_request description
- Add missing description to defaultToGlobal on GET /config/{subject}
- Clarify "subject-version" -> "subject-version pairs" in summary
- Make POST /security/acls description add value beyond the summary
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
| "info": { | ||
| "title": "Redpanda Schema Registry API", | ||
| "version": "1.1.2" | ||
| "version": "1.2.0" |
There was a problem hiding this comment.
I assume the changes in schema-registry.json are just a straight copy-paste from the redpanda repo, right? In which case, this looks good to me.
There was a problem hiding this comment.
@pgellert there are a few little patches where this diverges from the source repo
- additionalProperties type: string for schema_metadata_request - Claude flagged
oneOfas valid only in OpenAPI 3 and not Swagger 2 - add description for defaultToGlobal param
- clarification for GET /schemas/ids/{id}/versions and POST /security/acls
Do these still sound good?
There was a problem hiding this comment.
Yeah, all looks good and makes sense, thanks @kbatuigas!
Co-authored-by: Gellért Peresztegi-Nagy <pereszteginagy.gellert@gmail.com>
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
Docs review — findings
Context: reviewed against docs-team-standards and prior review feedback. The rename/refactor and new-endpoint additions land cleanly; below are the items that warrant attention before merge plus two cross-repo impacts worth flagging.
Must fix
Inconsistent context-qualified-subject syntax in 4 query-parameter descriptions
CodeRabbit's remaining unresolved nitpick is worth taking, and I'd rate it higher than "nitpick" — it will confuse API consumers. The new subject query-parameter descriptions use a different placeholder convention than the rest of the spec:
-
New query params (4 occurrences, approx. lines 469–475, 530–535, 583–588, 646–651) currently read:
Optional qualified subject to search for the schema under. Use
<:.context:>for context-only lookup, or<:.context:subject>to also verify the schema is associated with that subject. Defaults to searching the default context if unspecified.Here the entire token is wrapped in
<…>andcontext/subjectare not placeholder variables. -
Everywhere else (every path param,
schema_reference.subject, and the overlay) uses:Use
[:.<context>:]<subject>for context-qualified subjects, or just<subject>for the default context.Here
<context>/<subject>are the variable placeholders and the square brackets mark the optional qualifier.
Suggested rewrite for all four occurrences:
Qualified subject to search for the schema under. Use
:.<context>:for context-only lookup, or:.<context>:<subject>to also verify the schema is associated with that subject. Defaults to searching the default context if unspecified.
Suggestions
1. "Optional" is redundant in the new query-param descriptions
The new subject and referenceFormat descriptions lead with "Optional…", but the parameters are already declared "required": false, and no other optional parameter in this spec opens with the word. Consider dropping "Optional " for consistency with the surrounding spec. Style-only.
2. Parenthetical in overlay parses ambiguously
Current text in schema-registry/overlays/add-external-docs.yaml:
See the Redpanda Cloud (configurable only in BYOC and Dedicated clusters) or Redpanda Self-Managed documentation for details.
The "(configurable only in BYOC and Dedicated clusters)" clause is attached to the Cloud link, but a reader may take it as a condition on the whole feature. Consider moving it into its own sentence, e.g.:
In Redpanda Cloud, contexts are configurable only in BYOC and Dedicated clusters. See the Redpanda Cloud or Redpanda Self-Managed documentation for details.
Impact on other files (not in this PR)
1. Overlay links are currently 404 — coordinate with the docs PRs
The overlay paragraph links to:
https://docs.redpanda.com/current/manage/schema-reg/schema-reg-contexts/https://docs.redpanda.com/redpanda-cloud/manage/schema-reg/schema-reg-contexts/
Both return HTTP 404 at the moment (verified via curl -sI). The source pages live in open PRs:
- redpanda-data/docs#1658 — Doc-1996: Schema Registry Contexts
- redpanda-data/cloud-docs#551 — DOC-1812: Add single-sourced Schema Registry Contexts page
Worth coordinating so this PR merges after both docs PRs publish, or confirming the api-docs publication pipeline realistically trails the docs rollouts.
2. Renamed schema definitions are a breaking change for spec consumers
The refactor renames several top-level definitions:
schema_def→schema_def_request/schema_def_responsestored_schema→stored_schema_request/stored_schema_response- New
post_subject_versions_responseandget_subject_versions_version_response
This is a breaking rename for anyone generating SDKs or referencing these definitions externally. Not an issue in this PR itself, but worth a changelog or release-note entry wherever this spec is published downstream.
|
Status:
|
3 participants
This pull request introduces significant updates to the Schema Registry API documentation and specification, primarily to support and document the new "context" feature, which allows for isolated namespaces for schemas and configuration. It also adds new API endpoints, enhances parameter descriptions, and updates response schemas to improve clarity and usability.
Support for Contexts and Qualified Subjects:
schema-registry.jsonto explain how to use context-qualified subjects (e.g.,[:.<context>:]<subject>) for scoping operations, including for getting, setting, and deleting configs and modes, as well as for subject-related endpoints. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16]subjectPrefixto clarify how context-qualified and wildcard prefixes work.add-external-docs.yamlexplaining contexts and linking to relevant Redpanda documentation.New and Enhanced API Endpoints:
/schemas/ids/{id}/schemato retrieve the raw schema string by ID, with support for context-qualified subject lookup and format options.subject(qualified subject lookup) andreferenceFormat(qualified/unqualified references), improving flexibility when searching or retrieving schemas. [1] [2] [3]Response Schema and Request Body Updates:
schema_def_response,schema_def_request,stored_schema_response,stored_schema_request,post_subject_versions_response,get_subject_versions_version_response) for improved clarity and future extensibility. [1] [2] [3] [4] [5] [6] [7]Versioning:
1.1.2to1.2.0.These changes collectively bring the Schema Registry API documentation up to date with the latest product features and improve its usability for developers working with contexts and qualified subjects.