DOC-1790: Schema Registry Metadata Properties (#1690)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Gellért Peresztegi-Nagy <gellert.nagy@redpanda.com>
Co-authored-by: Kat Batuigas <36839689+kbatuigas@users.noreply.github.com>

Author: 4 people

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[]

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:**

modules/manage/pages/schema-reg/schema-reg-overview.adoc

@@ -159,6 +159,53 @@ 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:
+
+[,json]
+----
+{
+  "schema": "{\"type\":\"string\"}",
+  "metadata": {
+    "properties": {
+      "owner": "platform-team",
+      "application.version": "2.1.0"
+    }
+  }
+}
+----
+
+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]
+----
+# 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"}'
+----
+
+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.
+
+[NOTE]
+====
+Redpanda supports only `metadata.properties` from the Confluent Data Contracts specification. The following configuration objects are not supported:
+
+* `metadata.tags`
+* `ruleSet`
+* `defaultMetadata` and `overrideMetadata` (configuration options)
+* `defaultRuleSet` and `overrideRuleSet` (configuration options)
+* `compatibilityGroup` (configuration option)
+====
+
 == Next steps
 
 * xref:manage:schema-reg/schema-reg-api.adoc[]

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[]

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[]

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[]

modules/reference/pages/rpk/rpk-registry/rpk-registry-schema-create.adoc

@@ -38,6 +38,23 @@ 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 +72,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 (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.
 
 |--schema |string |Schema filepath to upload, must be `.avro`, `.avsc`, or `.proto`.