From db82355c7aed9a6e9c36c6b5cd0af3f5334be1f9 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Fri, 1 May 2026 19:13:30 -0400 Subject: [PATCH 01/19] DOC-1790: Document Schema Registry metadata properties Adds a new section covering metadata properties support in Schema Registry, including API usage, rpk flags, inheritance behavior, and Confluent Data Contracts compatibility notes. Co-Authored-By: Claude Sonnet 4.6 --- .../pages/schema-reg/schema-reg-overview.adoc | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 5349bc4ffe..4f7874266e 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -159,6 +159,44 @@ ifndef::env-cloud[] Additionally, you cannot have xref:manage:schema-reg/schema-id-validation.adoc#about-schema-id-validation[schema ID validation] with JSON schemas if the xref:manage:schema-reg/schema-id-validation.adoc#set-subject-name-strategy-per-topic[subject name strategy] _is not_ `TopicNameStrategy`. endif::[] +== Metadata properties + +Schema Registry lets you store and retrieve arbitrary key-value metadata properties alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle. To register a schema with metadata properties, include a `metadata.properties` object in the request body: + +[source,json] +---- +POST /subjects/my-topic-value/versions +{ + "schema": "{\"type\":\"string\"}", + "metadata": { + "properties": { + "owner": "platform-team", + "application.version": "2.1.0" + } + } +} +---- + +Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. Using rpk, pass metadata as `key=value` pairs with `--metadata-properties`, or as a JSON string with `-p`: + +[source,bash] +---- +# key=value pairs +rpk registry schema create my-subject --schema schema.avsc --metadata-properties owner=platform-team + +# JSON string +rpk registry schema create my-subject --schema schema.avsc -p '{"owner":"platform-team","application.version":"2.1.0"}' +---- + +To view metadata on an existing schema, add `--print-metadata` to `rpk registry schema get`. You can also view metadata properties in {ui}. + +When you register a new schema version without a `metadata` field, the new version automatically inherits properties from the most recent version of that subject. To clear inherited metadata, send `"metadata": null`. Registering the same schema definition with different metadata properties creates a new schema version. + +[NOTE] +==== +Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following features are not supported: `metadata.tags`, `ruleSet`, and the `defaultMetadata`, `overrideMetadata`, `defaultRuleSet`, and `overrideRuleSet` configuration options. +==== + == Next steps * xref:manage:schema-reg/schema-reg-api.adoc[] From 179c436f526637bdf2f226bc06b1fa17e16d69fb Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Fri, 1 May 2026 20:01:53 -0400 Subject: [PATCH 02/19] DOC-1790: Fix rpk metadata-properties flag documentation -p is a shorthand for --metadata-properties (single flag, not two). The flag accepts key=value or JSON, and can be passed multiple times. Uses StringArrayVar to avoid comma conflicts with JSON values. Co-Authored-By: Claude Sonnet 4.6 --- .../pages/schema-reg/schema-reg-overview.adoc | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 4f7874266e..683e5c3355 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -177,15 +177,18 @@ POST /subjects/my-topic-value/versions } ---- -Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. Using rpk, pass metadata as `key=value` pairs with `--metadata-properties`, or as a JSON string with `-p`: +Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. Using rpk, set metadata with the `--metadata-properties` flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string, and you can pass it multiple times to set multiple properties: [source,bash] ---- -# key=value pairs -rpk registry schema create my-subject --schema schema.avsc --metadata-properties owner=platform-team - -# JSON string -rpk registry schema create my-subject --schema schema.avsc -p '{"owner":"platform-team","application.version":"2.1.0"}' +# key=value pairs — pass the flag multiple times for multiple properties +rpk registry schema create my-subject --schema schema.avsc \ + --metadata-properties owner=platform-team \ + --metadata-properties env=prod + +# JSON string — useful when values contain special characters +rpk registry schema create my-subject --schema schema.avsc \ + --metadata-properties '{"owner":"platform-team","application.version":"2.1.0"}' ---- To view metadata on an existing schema, add `--print-metadata` to `rpk registry schema get`. You can also view metadata properties in {ui}. From 8c4eadff86d6cee61bc05bd48999fc22f3326e08 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 4 May 2026 09:06:02 -0500 Subject: [PATCH 03/19] Apply suggestions from code review Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com> --- .../manage/pages/schema-reg/schema-reg-overview.adoc | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 683e5c3355..cfb0e80b3c 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -177,7 +177,7 @@ POST /subjects/my-topic-value/versions } ---- -Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. Using rpk, set metadata with the `--metadata-properties` flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string, and you can pass it multiple times to set multiple properties: +Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. Using rpk, set metadata with the `--metadata-properties` flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: [source,bash] ---- @@ -197,7 +197,13 @@ When you register a new schema version without a `metadata` field, the new versi [NOTE] ==== -Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following features are not supported: `metadata.tags`, `ruleSet`, and the `defaultMetadata`, `overrideMetadata`, `defaultRuleSet`, and `overrideRuleSet` configuration options. +Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following configuration options are not supported: +- `metadata.tags` +- `ruleSet` +- `defaultMetadata` +- `overrideMetadata` +- `defaultRuleSet` +- `overrideRuleSet` ==== == Next steps From f38a4524d05522670774e36846e61f6493216b16 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 4 May 2026 09:55:06 -0500 Subject: [PATCH 04/19] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index cfb0e80b3c..9b557d4f99 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -198,6 +198,7 @@ When you register a new schema version without a `metadata` field, the new versi [NOTE] ==== Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following configuration options are not supported: + - `metadata.tags` - `ruleSet` - `defaultMetadata` From 18724122a1912f735b33c284e127005a4e338cfd Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 4 May 2026 09:55:24 -0500 Subject: [PATCH 05/19] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 9b557d4f99..c4da5815bc 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -199,6 +199,7 @@ When you register a new schema version without a `metadata` field, the new versi ==== Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following configuration options are not supported: + - `metadata.tags` - `ruleSet` - `defaultMetadata` From 6a2e5d7998f454207c78c5f812a2467797e00b08 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 4 May 2026 11:55:38 -0400 Subject: [PATCH 06/19] DOC-1790: Add -p/--metadata-properties flag to rpk schema create reference Co-Authored-By: Claude Sonnet 4.6 --- .../rpk-registry/rpk-registry-schema-create.adoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc index 523a0815c2..4ddfed70fa 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc @@ -38,6 +38,20 @@ Create a schema with a specific ID and version in import mode: rpk registry schema create foo --schema /path/to/file.proto --id 42 --schema-version 3 ---- +Create a schema with metadata properties as key=value pairs: + +[,bash] +---- +rpk registry schema create foo --schema /path/to/file.proto --metadata-properties owner=team-a --metadata-properties env=prod +---- + +Create a schema with metadata properties using JSON format: + +[,bash] +---- +rpk registry schema create foo --schema /path/to/file.proto --metadata-properties '{"owner":"team-a","env":"prod"}' +---- + == Usage [,bash] @@ -55,6 +69,8 @@ rpk registry schema create SUBJECT --schema {filename} [flags] |--id |int |Optional schema ID to use when creating the schema in import mode (default `-1`). +|-p, --metadata-properties |stringArray |Schema metadata properties as key=value pairs or JSON (e.g., `{"key":"value"}`). You can pass this flag multiple times. + |--references |string |Comma-separated list of references (name:subject:version) or path to reference file. |--schema |string |Schema filepath to upload, must be `.avro`, `.avsc`, or `.proto`. From 894317777ff2e12a346dd769d03e4cfaa5a4b8bb Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 4 May 2026 10:57:27 -0500 Subject: [PATCH 07/19] Apply suggestion from @Feediver1 --- .../pages/rpk/rpk-registry/rpk-registry-schema-create.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc index 4ddfed70fa..523c2b4049 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc @@ -69,7 +69,7 @@ rpk registry schema create SUBJECT --schema {filename} [flags] |--id |int |Optional schema ID to use when creating the schema in import mode (default `-1`). -|-p, --metadata-properties |stringArray |Schema metadata properties as key=value pairs or JSON (e.g., `{"key":"value"}`). You can pass this flag multiple times. +|-p, --metadata-properties |stringArray |Schema metadata properties as key=value pairs or JSON (for example, `{"key":"value"}`). You can pass this flag multiple times. |--references |string |Comma-separated list of references (name:subject:version) or path to reference file. From a77d4898c57076931e4d8cd9a893fec61e88d463 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 4 May 2026 14:00:25 -0400 Subject: [PATCH 08/19] DOC-1790: Address review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Use [,json]/[,bash] shorthand consistent with file conventions - Move POST method/path to prose; JSON block now contains body only - Fix dangling participial: "Using rpk" → "To set metadata using rpk" - Fix NOTE: remove double blank line, use * list markers, fix trailing whitespace, distinguish schema-level features from config options, add link to Confluent Data Contracts spec - Add line continuation to rpk reference examples for readability Co-Authored-By: Claude Sonnet 4.6 --- .../pages/schema-reg/schema-reg-overview.adoc | 22 ++++++++----------- .../rpk-registry-schema-create.adoc | 7 ++++-- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index c4da5815bc..9756c63088 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -161,11 +161,10 @@ endif::[] == Metadata properties -Schema Registry lets you store and retrieve arbitrary key-value metadata properties alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle. To register a schema with metadata properties, include a `metadata.properties` object in the request body: +Schema Registry lets you store and retrieve arbitrary key-value metadata properties alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle. Send a `POST` request to `/subjects/{subject}/versions` with a `metadata.properties` object in the request body: -[source,json] +[,json] ---- -POST /subjects/my-topic-value/versions { "schema": "{\"type\":\"string\"}", "metadata": { @@ -177,9 +176,9 @@ POST /subjects/my-topic-value/versions } ---- -Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. Using rpk, set metadata with the `--metadata-properties` flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: +Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. To set metadata using rpk, use the `--metadata-properties` flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: -[source,bash] +[,bash] ---- # key=value pairs — pass the flag multiple times for multiple properties rpk registry schema create my-subject --schema schema.avsc \ @@ -197,15 +196,12 @@ When you register a new schema version without a `metadata` field, the new versi [NOTE] ==== -Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following configuration options are not supported: - +Redpanda supports only `metadata.properties` from the https://docs.confluent.io/platform/current/schema-registry/fundamentals/data-contracts.html[Confluent Data Contracts^] specification. The following features are not supported: -- `metadata.tags` -- `ruleSet` -- `defaultMetadata` -- `overrideMetadata` -- `defaultRuleSet` -- `overrideRuleSet` +* `metadata.tags` +* `ruleSet` +* `defaultMetadata` and `overrideMetadata` (configuration options) +* `defaultRuleSet` and `overrideRuleSet` (configuration options) ==== == Next steps diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc index 523c2b4049..28933a71ab 100644 --- a/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc @@ -42,14 +42,17 @@ Create a schema with metadata properties as key=value pairs: [,bash] ---- -rpk registry schema create foo --schema /path/to/file.proto --metadata-properties owner=team-a --metadata-properties env=prod +rpk registry schema create foo --schema /path/to/file.proto \ + --metadata-properties owner=team-a \ + --metadata-properties env=prod ---- Create a schema with metadata properties using JSON format: [,bash] ---- -rpk registry schema create foo --schema /path/to/file.proto --metadata-properties '{"owner":"team-a","env":"prod"}' +rpk registry schema create foo --schema /path/to/file.proto \ + --metadata-properties '{"owner":"team-a","env":"prod"}' ---- == Usage From 3798beec5c8ec014e8480b7ff5559b3e9087fcf8 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 11 May 2026 10:39:06 -0500 Subject: [PATCH 09/19] Update modules/manage/pages/schema-reg/schema-reg-overview.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gellért Peresztegi-Nagy --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 9756c63088..092ab4f710 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -161,7 +161,7 @@ endif::[] == Metadata properties -Schema Registry lets you store and retrieve arbitrary key-value metadata properties alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle. Send a `POST` request to `/subjects/{subject}/versions` with a `metadata.properties` object in the request body: +Schema Registry lets you store and retrieve arbitrary key-value metadata properties alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle. You can register a new schema with associated metadata properties by sending a `POST` request to `/subjects/{subject}/versions` with a `metadata.properties` object in the request body: [,json] ---- From 2c5ba29e53970520e1413da66e4b966a156f9053 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 11 May 2026 10:40:58 -0500 Subject: [PATCH 10/19] Update modules/manage/pages/schema-reg/schema-reg-overview.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gellért Peresztegi-Nagy --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 092ab4f710..598f612553 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -192,7 +192,7 @@ rpk registry schema create my-subject --schema schema.avsc \ To view metadata on an existing schema, add `--print-metadata` to `rpk registry schema get`. You can also view metadata properties in {ui}. -When you register a new schema version without a `metadata` field, the new version automatically inherits properties from the most recent version of that subject. To clear inherited metadata, send `"metadata": null`. Registering the same schema definition with different metadata properties creates a new schema version. +When you register a new schema version without a `metadata` field, the new version automatically inherits properties from the most recent version of that subject. When registering a new schema, if you want to avoid inheriting the previous version's metadata, you can send `"metadata": {}` to register a schema with explicitly no metadata. Registering the same schema definition with different metadata properties creates a new schema version. [NOTE] ==== From 87449c91433f2395f9f0b4717d872d17c4d40aee Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 11 May 2026 10:41:10 -0500 Subject: [PATCH 11/19] Update modules/manage/pages/schema-reg/schema-reg-overview.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Gellért Peresztegi-Nagy --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 598f612553..08f236d3e2 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -202,6 +202,7 @@ Redpanda supports only `metadata.properties` from the https://docs.confluent.io/ * `ruleSet` * `defaultMetadata` and `overrideMetadata` (configuration options) * `defaultRuleSet` and `overrideRuleSet` (configuration options) +* `compatibilityGroup` (configuration option) ==== == Next steps From c65f454b4627b1407120f3a32f30461476a4d5e8 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 11 May 2026 10:41:59 -0500 Subject: [PATCH 12/19] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 08f236d3e2..93d3bb1ae9 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -196,7 +196,7 @@ When you register a new schema version without a `metadata` field, the new versi [NOTE] ==== -Redpanda supports only `metadata.properties` from the https://docs.confluent.io/platform/current/schema-registry/fundamentals/data-contracts.html[Confluent Data Contracts^] specification. The following features are not supported: +Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following features are not supported: * `metadata.tags` * `ruleSet` From 640cbe616e7966ccfa5e2c816bdcdb2bfbe9b429 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 11 May 2026 18:24:16 -0500 Subject: [PATCH 13/19] Update modules/manage/pages/schema-reg/schema-reg-overview.adoc Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 93d3bb1ae9..d73ea8e1e9 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -176,7 +176,7 @@ Schema Registry lets you store and retrieve arbitrary key-value metadata propert } ---- -Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. To set metadata using rpk, use the `--metadata-properties` flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: +Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. To set metadata using rpk, use the xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`--metadata-properties`] flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: [,bash] ---- From 0507a2389ad6791d3b1a85e5a9a56d13ca75c521 Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Mon, 11 May 2026 18:31:44 -0500 Subject: [PATCH 14/19] Update modules/manage/pages/schema-reg/schema-reg-overview.adoc Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com> --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index d73ea8e1e9..7211d8d8b8 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -192,7 +192,7 @@ rpk registry schema create my-subject --schema schema.avsc \ To view metadata on an existing schema, add `--print-metadata` to `rpk registry schema get`. You can also view metadata properties in {ui}. -When you register a new schema version without a `metadata` field, the new version automatically inherits properties from the most recent version of that subject. When registering a new schema, if you want to avoid inheriting the previous version's metadata, you can send `"metadata": {}` to register a schema with explicitly no metadata. Registering the same schema definition with different metadata properties creates a new schema version. +When you register a new schema version without a `metadata` field, the new version automatically inherits properties from the most recent version of that subject. To avoid inheriting the previous version's metadata, you can send `"metadata": {}` to register a schema with explicitly no metadata. Registering the same schema definition with different metadata properties creates a new schema version. [NOTE] ==== From 125341349108d6199fb643d04f05b4ed213fab12 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 11 May 2026 19:37:11 -0400 Subject: [PATCH 15/19] docs: reorder metadata properties section to pair REST and rpk equivalents Co-Authored-By: Claude Sonnet 4.6 --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 7211d8d8b8..156fc34d88 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -176,7 +176,7 @@ Schema Registry lets you store and retrieve arbitrary key-value metadata propert } ---- -Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. To set metadata using rpk, use the xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`--metadata-properties`] flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: +To set metadata using rpk, use the xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`--metadata-properties`] flag (shorthand: `-p`). The flag accepts `key=value` pairs or a JSON string (for example, `{"key":"value"}`), and you can pass it multiple times to set multiple properties: [,bash] ---- @@ -190,7 +190,7 @@ rpk registry schema create my-subject --schema schema.avsc \ --metadata-properties '{"owner":"platform-team","application.version":"2.1.0"}' ---- -To view metadata on an existing schema, add `--print-metadata` to `rpk registry schema get`. You can also view metadata properties in {ui}. +Metadata properties are returned on `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses. To view metadata on an existing schema, add `--print-metadata` to `rpk registry schema get`. You can also view metadata properties in {ui}. When you register a new schema version without a `metadata` field, the new version automatically inherits properties from the most recent version of that subject. To avoid inheriting the previous version's metadata, you can send `"metadata": {}` to register a schema with explicitly no metadata. Registering the same schema definition with different metadata properties creates a new schema version. From 3f6e643e88e9172218905a13763207b39ed3e006 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Mon, 11 May 2026 19:43:25 -0400 Subject: [PATCH 16/19] docs: add What's New entry for Schema Registry metadata properties Co-Authored-By: Claude Sonnet 4.6 --- modules/get-started/pages/release-notes/redpanda.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index 0d5b53ad62..e57c65e799 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -83,6 +83,12 @@ xref:manage:schema-reg/schema-reg-contexts.adoc[Schema Registry contexts] are na To enable contexts, set xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] to `true` and restart your brokers. Once enabled, you reference schemas using qualified subject syntax, for example `:.staging:my-topic-value`. See xref:manage:schema-reg/schema-reg-contexts.adoc[] for configuration examples and limitations. +== Schema Registry metadata properties + +xref:manage:schema-reg/schema-reg-overview.adoc#_metadata_properties[Schema Registry metadata properties] let you store and retrieve arbitrary key-value pairs alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle, making it easier to track ownership and lineage without modifying the schema itself. + +You can set metadata when registering a schema using the `POST /subjects/{subject}/versions` endpoint or with the xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`--metadata-properties`] flag in `rpk registry schema create`. Metadata is returned in `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses, and viewable with `rpk registry schema get --print-metadata`. New schema versions automatically inherit metadata from the most recent version of the subject unless you register with an explicit empty `metadata` object. + == New configuration properties **Storage mode:** From 92e19a0ddb5d969106bd144615342c391c6b5e98 Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Tue, 12 May 2026 08:57:04 -0400 Subject: [PATCH 17/19] docs: add missing rpk registry context reference pages to fix build The schema-reg-contexts page referenced rpk-registry-context-list and rpk-registry-context-delete, which didn't exist, causing xref errors during the Netlify build. Adds the three context command pages and registers them in the nav. Co-Authored-By: Claude Sonnet 4.6 --- modules/ROOT/nav.adoc | 3 ++ .../rpk-registry-context-delete.adoc | 42 ++++++++++++++++ .../rpk-registry-context-list.adoc | 45 +++++++++++++++++ .../rpk-registry/rpk-registry-context.adoc | 48 +++++++++++++++++++ 4 files changed, 138 insertions(+) create mode 100644 modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc create mode 100644 modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc create mode 100644 modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index ee8e828c6c..db1d611147 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -434,6 +434,9 @@ **** xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-get.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-compatibility-level-set.adoc[] +**** xref:reference:rpk/rpk-registry/rpk-registry-context.adoc[] +***** xref:reference:rpk/rpk-registry/rpk-registry-context-delete.adoc[] +***** xref:reference:rpk/rpk-registry/rpk-registry-context-list.adoc[] **** xref:reference:rpk/rpk-registry/rpk-registry-mode.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-mode-get.adoc[] ***** xref:reference:rpk/rpk-registry/rpk-registry-mode-reset.adoc[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc new file mode 100644 index 0000000000..b972a5fd88 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-delete.adoc @@ -0,0 +1,42 @@ += rpk registry context delete +// tag::single-source[] + +Delete a schema registry context. + +A context can only be deleted once all subjects within it have been hard deleted. Soft-deleted subjects still block context deletion. Use `rpk registry subject delete --permanent` to hard delete subjects first. + +The default context `.` cannot be deleted. + +== Usage + +[,bash] +---- +rpk registry context delete [CONTEXT] [flags] +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|*Value* |*Type* |*Description* + +|-h, --help |- |Help for delete. + +|--no-confirm |- |Disable confirmation prompt. + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. + +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. + +|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. + +|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. + +|--schema-context |string |Schema context to use for all registry operations. + +|--skip-context-check |- |Skip the admin API verification of schema context support. + +|-v, --verbose |- |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc new file mode 100644 index 0000000000..4954d2c028 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context-list.adoc @@ -0,0 +1,45 @@ += rpk registry context list +// tag::single-source[] + +List schema registry contexts. + +== Usage + +[,bash] +---- +rpk registry context list [flags] +---- + +== Aliases + +[,bash] +---- +list, ls +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|*Value* |*Type* |*Description* + +|--format |string |Output format: `json`,`yaml`,`text`,`wide`,`help`. Default: `text`. + +|-h, --help |- |Help for list. + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. + +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. + +|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. + +|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. + +|--schema-context |string |Schema context to use for all registry operations. + +|--skip-context-check |- |Skip the admin API verification of schema context support. + +|-v, --verbose |- |Enable verbose logging. +|=== + +// end::single-source[] diff --git a/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc new file mode 100644 index 0000000000..181e348544 --- /dev/null +++ b/modules/reference/pages/rpk/rpk-registry/rpk-registry-context.adoc @@ -0,0 +1,48 @@ += rpk registry context +// tag::single-source[] + +Manage schema registry contexts. + +Schema contexts provide namespace isolation within the schema registry, allowing multiple independent sets of subjects and schemas to coexist. + +Before using schema contexts, enable the xref:reference:properties/cluster-properties.adoc#schema_registry_enable_qualified_subjects[`schema_registry_enable_qualified_subjects`] cluster property: + +[,bash] +---- +rpk cluster config set schema_registry_enable_qualified_subjects true +---- + +Use the `--schema-context` flag on the parent `registry` command to scope operations to a specific context. + +== Usage + +[,bash] +---- +rpk registry context [flags] + rpk registry context [command] +---- + +== Flags + +[cols="1m,1a,2a"] +|=== +|*Value* |*Type* |*Description* + +|-h, --help |- |Help for context. + +|--config |string |Redpanda or `rpk` config file; default search paths are `~/.config/rpk/rpk.yaml`, `$PWD`, and `/etc/redpanda/redpanda.yaml`. + +|-X, --config-opt |stringArray |Override `rpk` configuration settings. See xref:reference:rpk/rpk-x-options.adoc[`rpk -X`] or execute `rpk -X help` for inline detail or `rpk -X list` for terser detail. + +|--ignore-profile |- |Ignore `rpk.yaml` and `redpanda.yaml`; use default settings. + +|--profile |string |Profile to use. See xref:reference:rpk/rpk-profile.adoc[`rpk profile`] for more details. + +|--schema-context |string |Schema context to use for all registry operations. + +|--skip-context-check |- |Skip the admin API verification of schema context support. + +|-v, --verbose |- |Enable verbose logging. +|=== + +// end::single-source[] From 694f06f3e5272275c44a491953707492660e13df Mon Sep 17 00:00:00 2001 From: Joyce Fee <102751339+Feediver1@users.noreply.github.com> Date: Tue, 12 May 2026 08:49:30 -0500 Subject: [PATCH 18/19] Apply suggestion from @Feediver1 --- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 156fc34d88..2838b91aca 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -196,7 +196,7 @@ When you register a new schema version without a `metadata` field, the new versi [NOTE] ==== -Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following features are not supported: +Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following configuration objects are not supported: * `metadata.tags` * `ruleSet` From de792731a1e943835e5b6b1cbb9e04b47b52955c Mon Sep 17 00:00:00 2001 From: Joyce Fee Date: Tue, 12 May 2026 09:56:34 -0400 Subject: [PATCH 19/19] docs: fix anchor for metadata-properties xref in What's New Add explicit [#metadata-properties] ID to the heading so the xref resolves to the correct section rather than the top of the page. Co-Authored-By: Claude Sonnet 4.6 --- modules/get-started/pages/release-notes/redpanda.adoc | 2 +- modules/manage/pages/schema-reg/schema-reg-overview.adoc | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/get-started/pages/release-notes/redpanda.adoc b/modules/get-started/pages/release-notes/redpanda.adoc index e57c65e799..8cb179e6dc 100644 --- a/modules/get-started/pages/release-notes/redpanda.adoc +++ b/modules/get-started/pages/release-notes/redpanda.adoc @@ -85,7 +85,7 @@ To enable contexts, set xref:reference:properties/cluster-properties.adoc#schema == Schema Registry metadata properties -xref:manage:schema-reg/schema-reg-overview.adoc#_metadata_properties[Schema Registry metadata properties] let you store and retrieve arbitrary key-value pairs alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle, making it easier to track ownership and lineage without modifying the schema itself. +xref:manage:schema-reg/schema-reg-overview.adoc#metadata-properties[Schema Registry metadata properties] let you store and retrieve arbitrary key-value pairs alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle, making it easier to track ownership and lineage without modifying the schema itself. You can set metadata when registering a schema using the `POST /subjects/{subject}/versions` endpoint or with the xref:reference:rpk/rpk-registry/rpk-registry-schema-create.adoc[`--metadata-properties`] flag in `rpk registry schema create`. Metadata is returned in `GET /subjects/{subject}/versions/{version}` and `GET /schemas/ids/{id}` responses, and viewable with `rpk registry schema get --print-metadata`. New schema versions automatically inherit metadata from the most recent version of the subject unless you register with an explicit empty `metadata` object. diff --git a/modules/manage/pages/schema-reg/schema-reg-overview.adoc b/modules/manage/pages/schema-reg/schema-reg-overview.adoc index 2838b91aca..18526e3384 100644 --- a/modules/manage/pages/schema-reg/schema-reg-overview.adoc +++ b/modules/manage/pages/schema-reg/schema-reg-overview.adoc @@ -159,6 +159,7 @@ ifndef::env-cloud[] Additionally, you cannot have xref:manage:schema-reg/schema-id-validation.adoc#about-schema-id-validation[schema ID validation] with JSON schemas if the xref:manage:schema-reg/schema-id-validation.adoc#set-subject-name-strategy-per-topic[subject name strategy] _is not_ `TopicNameStrategy`. endif::[] +[#metadata-properties] == Metadata properties Schema Registry lets you store and retrieve arbitrary key-value metadata properties alongside schemas. Properties such as `owner`, `team`, or `application.version` travel with the schema through its lifecycle. You can register a new schema with associated metadata properties by sending a `POST` request to `/subjects/{subject}/versions` with a `metadata.properties` object in the request body: