include::{mod-loc}shared/all-attributes.adoc[]

[id="registry-artifact-reference_{context}"]
= {registry} artifact reference
//If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.

[role="_abstract"]
This chapter provides reference information on the supported artifact types, states, and metadata that are stored in {registry}.

* xref:registry-artifact-types_{context}[]
* xref:registry-artifact-states_{context}[]
* xref:registry-group-metadata_{context}[]
* xref:registry-artifact-metadata_{context}[]
* xref:registry-artifact-version-metadata_{context}[]

[role="_additional-resources"]
.Additional resources
* For more information, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation].

//INCLUDES


// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_registry-reference.adoc

[id="registry-artifact-types_{context}"]

== {registry} artifact types

[role="_abstract"]
You can store and manage a wide range of schema and API artifact types in {registry}.

.{registry} artifact types
[%header,cols=3*]
|===
|Type
|Description
|Supported versions
|`ASYNCAPI`
|AsyncAPI specification
|`2.0.0` -> `2.6.0`, `3.0.0`
|`AVRO`
|Apache Avro schema
|`1.0` -> `1.12`,
|`GRAPHQL`
|GraphQL schema
|*
|`JSON`
|JSON Schema
|`draft-04`, `draft-07`, `2019-09`, `2020-12`
|`KCONNECT`
|Apache Kafka Connect schema
|`2.0.0`
|`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`
|`PROMPT_TEMPLATE`
|LLM prompt templates with variable schemas
|`v1`
|`PROTOBUF`
|Google protocol buffers schema
|`proto2`, `proto3`
|`WSDL`
|Web Services Definition Language
|http://schemas.xmlsoap.org/wsdl/
|`XML`
|Extensible Markup Language
|
|`XSD`
|XML Schema Definition
|http://www.w3.org/2001/XMLSchema
|===

[discrete]
=== AI/ML artifact types

{registry} includes built-in support for AI/ML artifact types designed for LLMOps and prompt engineering workflows.

==== 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`

[role="_additional-resources"]
.Additional resources
* For detailed examples and SDK integration, see the link:https://github.com/Apicurio/apicurio-registry/tree/main/examples/llm-artifact-types[LLM artifact types example]
* For a complete support chat application with RAG, see link:https://github.com/carlesarnal/apicurio-registry-support-chat[Apicurio Registry Support Chat]



// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_registry-reference.adoc

[id="registry-artifact-states_{context}"]

== {registry} artifact version states

[role="_abstract"]
The valid artifact version states in {registry} are `ENABLED`, `DISABLED`, and `DEPRECATED`.

.{registry} artifact version states
[%header,cols=2*]
|===
|State
|Description
|`ENABLED`
|Basic state, all the operations are available.
|`DISABLED`
|The artifact version metadata is viewable and searchable using the {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.
|===



// Metadata created by nebel

[id="registry-group-metadata_{context}"]
== {registry} group metadata

[role="_abstract"]
When a group is created in {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.

.{registry} system-generated metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|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`.
|===


.{registry} user-provided or system-generated metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|Property
|Type
|Description
|`groupId`
|string
|Unique identifier of the artifact group in {registry}, for example, `development` or `production`.
|===


.{registry} editable metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|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`.
|===

.Updating group metadata
* You can use the {registry} REST API or web console to update the set of editable metadata properties.
* You can update the `state` property only by using the {registry} REST API.

[role="_additional-resources"]
.Additional resources
For more details, see the `/groups/\{groupId\}` endpoint in the {registry-rest-api}.



// Metadata created by nebel

[id="registry-artifact-metadata_{context}"]
== {registry} artifact metadata

[role="_abstract"]
When an artifact is added to {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.

.{registry} system-generated metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|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 {registry}. For example, a global ID of `1` is assigned to the first artifact version created in {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`.
|===


.{registry} user-provided or system-generated metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|Property
|Type
|Description
|`groupId`
|string
|Unique identifier of an artifact group in {registry}, for example, `development` or `production`. When creating an artifact by using the {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 {registry}. You can provide an artifact ID or use the UUID generated by {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`.
|===


.{registry} editable metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|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.
|===

.Updating artifact metadata
* You can use the {registry} REST API or web console to update the set of editable metadata properties.

[role="_additional-resources"]
.Additional resources
For more details, see the `/groups/\{groupId\}/artifacts/\{artifactId\}` endpoint in the {registry-rest-api}.



// Metadata created by nebel

[id="registry-artifact-version-metadata_{context}"]
== {registry} artifact version metadata

[role="_abstract"]
When an artifact version is added to a {registry} artifact, a set of metadata properties is created and stored 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.

.{registry} system-generated metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|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 {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 {registry}. For example, a global ID of `1` is assigned to the first artifact version created in {registry}.
|===


.{registry} user-provided or system-generated metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|Property
|Type
|Description
|`groupId`
|string
|Unique identifier of an artifact group in {registry}, for example, `development` or `production`.
|`artifactId`
|string
|Unique identifier of an artifact in {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 {registry} REST API, SDKs, or Maven plug-in, for example, `2.1.6`.
|===


.{registry} editable metadata
[.table-expandable,width="100%",cols="1,1,2",options="header"]
|===
|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`.
|===

.Updating artifact version metadata
* You can use the {registry} REST API or web console to update the set of editable metadata properties.
* You can update the `state` property only by using the {registry} REST API.

[role="_additional-resources"]
.Additional resources
For more details, see the `/groups/\{groupId\}/artifacts/\{artifactId\}/versions/\{versionId\}` endpoint in the {registry-rest-api}.


