Apicurio Registry artifact reference

Look up the artifact types that Apicurio Registry supports, including AI/ML types, the states that artifact versions move through, and the metadata that Apicurio Registry stores for groups, artifacts, and artifact versions.

Additional resources

Apicurio Registry REST API documentation

Apicurio Registry artifact types

You can store and manage a wide range of schema and API artifact types in Apicurio Registry.

Table 1. Apicurio Registry artifact types
Type	Description	Supported versions
`ASYNCAPI`	AsyncAPI specification	`2.0.0` → `2.6.0`, `3.0.0`, `3.1.0`
`AVRO`	Apache Avro schema	`1.0` → `1.12`
`GRAPHQL`	GraphQL schema	*
`JSON`	JSON Schema	`draft-04`, `draft-06`, `draft-07`, `2019-09`, `2020-12`
`KCONNECT`	Apache Kafka Connect schema	`2.0.0`
`MCP_SERVER`	MCP server definitions (`server.json`, Model Context Protocol)	`v0.1`
`MCP_TOOL`	MCP tool definitions (Model Context Protocol)	`2025-11-25`
`MODEL_SCHEMA`	AI/ML model input/output schema definitions	`v1`
`OPENAPI`	OpenAPI specification	`2.0.0`, `3.0.0` → `3.0.3`, `3.1.0`, `3.2.0`
`OPENRPC`	OpenRPC specification for JSON-RPC APIs	`1.3`, `1.4`
`PROMPT_TEMPLATE`	LLM prompt templates with variable schemas	`v1`
`PROTOBUF`	Google protocol buffers schema	`proto2`, `proto3`
`THRIFT`	Apache Thrift interface definition language	*
`WSDL`	Web Services Definition Language	http://schemas.xmlsoap.org/wsdl/
`XML`	Extensible Markup Language
`XSD`	XML Schema Definition	http://www.w3.org/2001/XMLSchema

Artifact reference support by type

Artifact references let one artifact content depend on another artifact already stored in Apicurio Registry (for example, an OpenAPI document that uses $ref to point at a shared JSON Schema artifact). Support for finding, validating, and resolving (dereferencing or rewriting) references varies by artifact type. The table below lists the reference support for every built-in artifact type.

Table 2. Artifact reference support by type
Type	Finds references	Dereferences (`DEREFERENCE`)	Rewrites (`REWRITE`)	Notes
`AVRO`	Yes	Yes	Yes	References are named types (for example `com.example.Foo`) found in named-type fields.
`PROTOBUF`	Yes	Yes	Yes	References are resolved from `import` statements.
`JSON`	Yes	Yes	Yes	References are `$ref` pointers to external documents.
`OPENAPI`	Yes	Yes	Yes	References are `$ref` pointers to external documents.
`ASYNCAPI`	Yes	Yes	Yes	References are `$ref` pointers to external documents.
`OPENRPC`	Yes	Yes	Yes	References are `$ref` pointers to external documents.
`MODEL_SCHEMA`	Yes	Yes	Yes	AI/ML model input/output schemas may reference shared type definitions.
`PROMPT_TEMPLATE`	Yes	Yes	Yes	Prompt templates may reference shared variable schemas.
`ODCS_CONTRACT`	Yes	Yes	Yes	References are `schemas[].location` values pointing at the backing schema artifact (for example an `AVRO`, `JSON`, or `PROTOBUF` artifact). `DEREFERENCE` inlines the resolved schema content into an `x-apicurio-schemaDefinition` field alongside `location` (namespaced to avoid colliding with a schema entry that already defines its own property of that name, which is left untouched); `REWRITE` replaces the `location` value with a Registry API URL. Cross-artifact references inside the referenced schema content are not followed during ODCS projection; see the data contracts documentation for details.
`XSD`	Yes	No (throws an error)	Yes	The reference name must equal the literal `schemaLocation` attribute value. Only `REWRITE` is supported; requesting `DEREFERENCE` raises an error directing the caller to use `REWRITE` instead.
`WSDL`	Yes	No (throws an error)	Yes	The reference name must equal the literal `schemaLocation` or `location` attribute value. Only `REWRITE` is supported; requesting `DEREFERENCE` raises an error directing the caller to use `REWRITE` instead.
`GRAPHQL`	Yes (opt-in convention)	Yes	Yes	GraphQL has no standard import syntax. References are recognized only when the content uses the `import "other.graphql"` leading-comment convention popularized by third-party tools such as graphql-tools / graphql-import. Content that does not use this convention has no references. The named-import form ( `import Foo, Bar from "other.graphql"`) is recognized for reference finding and `REWRITE`, but is intentionally left unresolved on `DEREFERENCE` (the directive is left unchanged), since inlining the whole referenced file would ignore the requested name list and risks introducing conflicting or duplicate type definitions. Text that merely resembles an `#import` line inside a `"""…"""` block-string description is never treated as a directive.
`XML`	No	No	No	Generic XML content has no defined reference mechanism in Apicurio Registry.
`KCONNECT`	No	No	No	Kafka Connect schema content has no defined reference mechanism in Apicurio Registry.
`ICEBERG_TABLE`	No	No	No	The content validator rejects artifact references outright.
`ICEBERG_VIEW`	No	No	No	The content validator rejects artifact references outright.
`MCP_TOOL`	No	No	No	The content validator rejects artifact references outright.
`MCP_SERVER`	No	No	No	`server.json` has no reference fields; there is nothing in the content to map to a reference.
`AGENT_CARD`	No	No	No	Agent card content has no defined reference mechanism in Apicurio Registry.
`THRIFT`	No	No	No	Not currently implemented.

AI/ML artifact types

Apicurio Registry includes built-in support for AI/ML artifact types designed for LLMOps and prompt engineering workflows.

Apicurio Registry supports the following AI/ML artifact types:

MCP_SERVER

MCP (Model Context Protocol) server definitions, in the server.json format published to an MCP registry. Use this artifact type to:

Store the packages, remotes, and transports through which an MCP server can be reached
Track server releases with version history
Serve the servers through the MCP Registry API, which is enabled with apicurio.mcp-registry.enabled
Validate server definitions against the MCP registry specification

Content types: application/json

MCP_TOOL

MCP (Model Context Protocol) tool definitions. Use this artifact type to:

Store MCP tool definitions with input/output schemas
Track tool evolution with version history and compatibility checking
Enable discovery of tools via well-known endpoints
Validate tool definitions against the MCP specification

Content types: application/json

MODEL_SCHEMA

Defines and validates AI/ML model input/output schemas and metadata. Use this artifact type to:

Document model input/output contracts using JSON Schema
Track model capabilities (chat, vision, function calling)
Store provider information and context window limits
Ensure backward compatibility when updating model schemas

Content types: application/json, application/x-yaml

PROMPT_TEMPLATE

Version-controlled prompt templates with variable schemas. Use this artifact type to:

Store prompt templates with {{variable}} syntax
Define variable schemas with types, constraints, and defaults
Track prompt evolution with version history
Validate prompts have all required variables defined

Content types: application/x-yaml, application/json, text/x-prompt-template

Additional resources

Apicurio Registry artifact version states

The valid artifact version states in Apicurio Registry are ENABLED, DISABLED, and DEPRECATED.

Table 3. Apicurio Registry artifact version states
State	Description
`ENABLED`	Basic state, all the operations are available.
`DISABLED`	The artifact version metadata is viewable and searchable using the Apicurio Registry web console, but its content cannot be fetched by any client.
`DEPRECATED`	The artifact version is fully usable but a header is added to the REST API response whenever the artifact version content is fetched.

Apicurio Registry group metadata

When a group is created in Apicurio Registry, a set of metadata properties is created and stored. This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the group is created.

Table 4. Apicurio Registry system-generated metadata
Property	Type	Description
`owner`	string	The name of the user who created the group.
`createdOn`	date	The date and time when the group was created, for example, `2023-10-11T14:15:28Z`.
`modifiedBy`	string	The name of the user who modified the group.
`modifiedOn`	date	The date and time at which the group was modified, for example, `2023-10-11T14:15:28Z`.

Table 5. Apicurio Registry user-provided or system-generated metadata
Property	Type	Description
`groupId`	string	Unique identifier of the artifact group in Apicurio Registry, for example, `development` or `production`.

Table 6. Apicurio Registry editable metadata
Property	Type	Description
`description`	string	Optional meaningful description of the group, for example, `This is a simple group for testing`.
`labels`	map	Optional list of user-defined name-value pairs associated with the group. The name and value must be strings, for example, `my-key` and `my-value`.

You can update group metadata as follows:

You can use the Apicurio Registry REST API or web console to update the set of editable metadata properties.
You can update the state property only by using the Apicurio Registry REST API.

For more details, see the /groups/{groupId} endpoint in the Apicurio Registry REST API documentation.

Additional resources

Apicurio Registry REST API documentation

Automatic group creation

You can require clients to create a group before registering its first artifact by disabling automatic group creation.

Default behavior: With SQL or KafkaSQL storage, apicurio.storage.enable-automatic-group-creation defaults to true. Registering an artifact in a named group that does not exist creates the group automatically. The new group uses the artifact owner’s identity as its owner.
Explicit group creation: With apicurio.storage.enable-automatic-group-creation=false, registering an artifact in a missing named group fails with a group-not-found error. Clients must first create the group, for example, with POST /apis/registry/v3/groups. Existing groups and the built-in default group remain available.

Example: Requiring explicit group creation

apicurio.storage.enable-automatic-group-creation=false

The equivalent environment variable is APICURIO_STORAGE_ENABLE_AUTOMATIC_GROUP_CREATION=false. The setting takes effect when you restart the server.

Additional resources

Default reference handling for artifact content

You can set a default representation for retrieved artifact references when clients omit the reference-handling parameter.

The optional apicurio.rest.artifact.references.default-handling property accepts the following values for supported v3 content endpoints:

Table 7. Default reference-handling values
Value	Returned content
`PRESERVE`	Keeps references in the stored content unchanged. This is the v3 API default when the property is unset.
`DEREFERENCE`	Resolves registered references and incorporates the referenced content, according to the artifact type’s dereferencing support.
`REWRITE`	Rewrites registered references as URLs to the referenced content in Apicurio Registry, according to the artifact type’s reference support.

Example: Dereferencing content by default

apicurio.rest.artifact.references.default-handling=DEREFERENCE

The equivalent environment variable is APICURIO_REST_ARTIFACT_REFERENCES_DEFAULT_HANDLING=DEREFERENCE. The setting takes effect when you restart the server. It changes the response representation without modifying stored artifact content.

Per-request override

For v3 content retrieval by global ID or by group, artifact, and version, an explicit references query parameter overrides the configured default. For example, this request preserves references even when the server default is DEREFERENCE:

curl "https://registry.example.com/apis/registry/v3/groups/my-group/artifacts/my-schema/versions/1.0.0/content?references=PRESERVE"

Replace the URL and artifact coordinates with values from your deployment, and supply authentication if required.

Compatibility APIs

When no explicit parameter is supplied, the v2 API treats a configured DEREFERENCE value as dereference=true. The Confluent-compatible API applies its resolved format to supported Avro and Protobuf responses when this default is DEREFERENCE. Without the property, each API retains its existing default behavior.

Additional resources

Apicurio Registry artifact metadata

When an artifact is added to Apicurio Registry, a set of metadata properties is created and stored. This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the artifact is created.

Table 8. Apicurio Registry system-generated metadata
Property	Type	Description
`createdOn`	date	The date and time when the artifact was created, for example, `2023-10-11T14:15:28Z`.
`globalId`	integer	Globally unique identifier of an artifact version in Apicurio Registry. For example, a global ID of `1` is assigned to the first artifact version created in Apicurio Registry.
`modifiedBy`	string	The name of the user who modified the artifact.
`modifiedOn`	date	The date and time at which the artifact was modified, for example, `2023-10-11T14:15:28Z`.

Table 9. Apicurio Registry user-provided or system-generated metadata
Property	Type	Description
`groupId`	string	Unique identifier of an artifact group in Apicurio Registry, for example, `development` or `production`. When creating an artifact by using the Apicurio Registry web console, if you do not provide a group ID, this is set to `default`. You must provide a group ID when using the Apicurio Registry REST API, Java client, or Maven plug-in.
`artifactId`	string	Unique identifier of an artifact in Apicurio Registry. You can provide an artifact ID or use the UUID generated by Apicurio Registry, for example, `8d168cad-1865-4e6c-bb7e-04e8be005bea`. Different versions of an artifact use the same artifact ID, but have different global IDs.
`artifactType`	ArtifactType	The supported artifact type, for example, `AVRO`, `OPENAPI`, or `PROTOBUF`.

Table 10. Apicurio Registry editable metadata
Property	Type	Description
`name`	string	Optional human-readable name of the artifact, for example, `My first Avro schema`.
`description`	string	Optional meaningful description of the artifact, for example, `This is a simple OpenAPI for testing`.
`labels`	map	Optional list of user-defined name-value pairs associated with the artifact. The name and value must be strings, for example, `my-key` and `my-value`.
`owner`	string	The name of the user who owns the artifact.

You can update artifact metadata as follows:

You can use the Apicurio Registry REST API or web console to update the set of editable metadata properties.

For more details, see the /groups/{groupId}/artifacts/{artifactId} endpoint in the Apicurio Registry REST API documentation.

Additional resources

Apicurio Registry REST API documentation

Apicurio Registry artifact version metadata

When you add a new version to an artifact, Apicurio Registry creates a set of metadata properties and stores them along with the artifact version content.

This metadata consists of system-generated or user-generated properties that are read-only, and editable properties that you can update after the artifact version is created.

Table 11. Apicurio Registry system-generated metadata
Property	Type	Description
`owner`	string	The name of the user who created the artifact version.
`createdOn`	date	The date and time when the artifact version was created, for example, `2023-10-11T14:15:28Z`.
`modifiedBy`	string	The user who modified the artifact version.
`modifiedOn`	date	The date and time at which the artifact version was modified, for example, `2023-10-11T14:15:28Z`.
`contentId`	integer	Unique identifier of artifact version content in Apicurio Registry. The same content ID can be shared by multiple artifact versions when artifact versions have identical content. For example, a content ID of `4` can be used by multiple artifact versions with the same content, even across multiple artifacts.
`globalId`	integer	Globally unique identifier of an artifact version in Apicurio Registry. For example, a global ID of `1` is assigned to the first artifact version created in Apicurio Registry.

Table 12. Apicurio Registry user-provided or system-generated metadata
Property	Type	Description
`groupId`	string	Unique identifier of an artifact group in Apicurio Registry, for example, `development` or `production`.
`artifactId`	string	Unique identifier of an artifact in Apicurio Registry.
`version`	integer	The version string of the artifact version. If not provided, the system will generate a new sequential version. You can provide a version when using the Apicurio Registry REST API, SDKs, or Maven plug-in, for example, `2.1.6`.

Table 13. Apicurio Registry editable metadata
Property	Type	Description
`name`	string	Optional human-readable name of the artifact version, for example, `Version One`.
`description`	string	Optional meaningful description of the artifact version, for example, `This is the first version for testing`.
`labels`	map	Optional list of user-defined name-value pairs associated with the artifact version. The name and value must be strings, for example, `my-key` and `my-value`.
`state`	ArtifactState	The state of the artifact version: `ENABLED`, `DISABLED`, or `DEPRECATED`. Defaults to `ENABLED`.

You can update artifact version metadata as follows:

You can use the Apicurio Registry REST API or web console to update the set of editable metadata properties.
You can update the state property only by using the Apicurio Registry REST API.

For more details, see the /groups/{groupId}/artifacts/{artifactId}/versions/{versionId} endpoint in the Apicurio Registry REST API documentation.

Additional resources

Apicurio Registry REST API documentation