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

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>
Co-authored-by: Gellért Peresztegi-Nagy <gellert.nagy@redpanda.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Joyce Fee <joyce@redpanda.com>
Co-authored-by: Michele Cyran <michele@redpanda.com>

Author: 6 people

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

@@ -669,7 +669,23 @@ A successful registration returns the schema's `id`:
 
 == Reference a schema
 
-To build more complex schema definitions, you can add a reference to other schemas. The following example registers a Protobuf schema in subject `test-simple` with a message name `Simple`.
+To build more complex schema definitions, you can add a reference to other schemas. A reference identifies another schema using a `name`, `subject`, and `version`. The meaning of `name` depends on the schema type:
+
+[cols="1,2"]
+|===
+| Schema type | Reference name
+
+| Protobuf
+| The import path used in the `.proto` file (for example, `import "simple.proto";` uses name `simple.proto`).
+
+| 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`).
+
+| JSON Schema
+| Used to identify the referenced schema in `$ref`. Redpanda's Schema Registry does not yet support external JSON Schema references (where `$ref` points to a schema registered under a different subject). To structure complex JSON schemas, define referenced types within the same schema document using `definitions` / `$defs` or bundled `$id` schemas. See xref:manage:schema-reg/schema-reg-overview.adoc#limitations[JSON Schema limitations].
+|===
+
+The following example registers a Protobuf schema in subject `test-simple` with a message name `Simple`.
 
 [tabs]
 ====

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

@@ -146,14 +146,9 @@ All CRUD operations are supported for the JSON Schema (`json-schema`), and Redpa
 
 Schemas are held in subjects. Subjects have a compatibility configuration associated with them, either directly specified by a user, or inherited by the default. See `PUT /config` and `PUT/config/\{subject}` in the link:/api/doc/schema-registry/[Schema Registry API].
 
-If you have inserted a second schema into a subject where the compatibility level is anything but `NONE`, then any JSON Schema containing the following items are rejected:
+JSON Schema supports internal references (`$ref` using JSON Pointer fragments such as `#/definitions/...` or `#/$defs/...`) and bundled schemas (sub-schemas with their own `$id` defined within the same document). These work correctly with all compatibility levels.
 
-* `$ref`
-* `$defs` (`definitions` prior to draft 2019-09)
-* `dependentSchemas` / `dependentRequired` (`dependencies` prior to draft 2019-09)
-* `prefixItems`
-
-Consequently, you cannot https://json-schema.org/understanding-json-schema/structuring[structure a complex schema^] using these features.
+External references, where `$ref` points to a schema registered under a different subject, are not supported. To https://json-schema.org/understanding-json-schema/structuring[structure complex JSON schemas^], define referenced types within the same schema document using `definitions` / `$defs` or bundled `$id` schemas.
 
 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`.