// Metadata created by nebel

[id="registry-artifacts_{context}"]
= Schema and API artifacts in {registry}

[role="_abstract"]
The items stored in {registry}, such as event schemas and API designs, are known as registry _artifacts_. The following shows an example of an Apache Avro schema artifact in JSON format for a simple share price application:

.Example Avro schema
[source,json]
----
{
   "type": "record",
   "name": "price",
   "namespace": "com.example",
   "fields": [
       {
           "name": "symbol",
           "type": "string"
       },
       {
           "name": "price",
           "type": "string"
       }
   ]
}
----

When a schema or API design is added as an artifact in {registry}, client applications can then use that schema or API design to validate that the client messages conform to the correct data structure at runtime.


[discrete]
== Groups of schemas and APIs

An _artifact group_ is an optional named collection of schema or API artifacts. Each group contains a logically related set of schemas or API designs, typically managed by a single entity, belonging to a particular application or organization.

You can create optional artifact groups when adding your schemas and API designs to organize them in {registry}. For example, you could create groups to match your `development` and `production` application environments, or your `sales` and `engineering` organizations.

Schema and API groups can contain multiple artifact types. For example, you could have Protobuf, Avro, JSON Schema, OpenAPI, or AsyncAPI artifacts all in the same group.

You can create schema and API artifacts and groups using the {registry} web console, REST API, command line, Maven plug-in, or Java client application. The following simple example shows using the Core Registry REST API:

[source,bash]
----
$ curl -X POST -H "Content-type: application/json; artifactType=AVRO" \
  -H "X-Registry-ArtifactId: share-price" \
  --data '{"type":"record","name":"price","namespace":"com.example", \
   "fields":[{"name":"symbol","type":"string"},{"name":"price","type":"string"}]}' \
  https://my-registry.example.com/apis/registry/v2/groups/my-group/artifacts
----

This example creates an artifact group named `my-group` and adds an Avro schema with an artifact ID of `share-price`.

NOTE: Specifying a group is optional when using the {registry} web console, and a `default` group is created automatically. When using the REST API or Maven plug-in, specify the `default` group in the API path if you do not want to create a unique group.

[role="_additional-resources"]
.Additional resources

* For information on supported artifact types, see {registry-artifact-reference}.
* For information on the Core Registry API, see the {registry-rest-api}.


[discrete]
== References to other schemas and APIs

Some {registry} artifact types can include _artifact references_ from one artifact file to another. You can create efficiencies by defining reusable schema or API components, and then referencing them from multiple locations. For example, you can specify a reference in JSON Schema or OpenAPI using a `$ref` statement, or in Google Protobuf using an `import` statement, or in Apache Avro using a nested namespace.

The following example shows a simple Avro schema named `TradeKey` that includes a reference to another schema named `Exchange` using a nested namespace:

.Tradekey schema with nested Exchange schema
[source,json]
----
{
 "namespace": "com.kubetrade.schema.trade",
 "type": "record",
 "name": "TradeKey",
 "fields": [
   {
     "name": "exchange",
     "type": "com.kubetrade.schema.common.Exchange"
   },
   {
     "name": "key",
     "type": "string"
   }
 ]
}
----

.Exchange schema
[source,json]
----
{
 "namespace": "com.kubetrade.schema.common",
 "type": "enum",
 "name": "Exchange",
 "symbols" : ["GEMINI"]
}
----

An artifact reference is stored in {registry} as a collection of artifact metadata that maps from an artifact type-specific reference to an internal {registry} reference. Each artifact reference in {registry} is composed of the following:

* Group ID
* Artifact ID
* Artifact version
* Artifact reference name

You can manage artifact references using the {registry} core REST API, Maven plug-in, and Java serializers/deserializers (SerDes). {registry} stores the artifact references along with the artifact content. {registry} also maintains a collection of all artifact references so you can search them or list all references for a specific artifact.

[discrete]
=== Supported artifact types
{registry} currently supports artifact references for the following artifact types only:

* Avro
* Protobuf
* JSON Schema
* OpenAPI
* AsyncAPI

[role="_additional-resources"]
.Additional resources

* For details on managing artifact references, see:
ifdef::apicurio-registry,rh-service-registry[]
** {managing-registry-artifacts-api}.
** {managing-registry-artifacts-maven}.
endif::[]
ifdef::rh-openshift-sr[]
** {base-url}{manage-api-url-registry}[Managing Service Registry data using the Core Registry API].
** {base-url}{manage-maven-plugin-url-registry}[Managing schemas and APIs using the Service Registry Maven plug-in].
endif::[]
* For a Java example, see the https://github.com/Apicurio/apicurio-registry-examples/tree/main/serdes-with-references[Apicurio Registry SerDes with references demonstration].
