// Metadata created by nebel

[id="registry-artifacts"]
= Schema and API artifacts and groups 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:

[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 the 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. 

{registry} supports a wide range of message payload formats for standard event schemas and API specifications. For example, supported formats include Apache Avro, Google Protobuf, GraphQL, AsyncAPI, OpenAPI, and others. For more details, see {registry-reference}. 

[discrete]
== Schema and API groups

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, and AsyncAPI schema and API artifacts all in the same group.    

You can create schema and API artifacts and optional groups using the {registry} web console, core REST API, Maven plug-in, or Java client application.  The following simple example shows using the 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 adds an Avro schema with an artifact ID of `share-price` in an artifact group named `my-group`.

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

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

* For more details on schemas and groups, see the link:https://github.com/cloudevents/spec/blob/master/schemaregistry/schemaregistry.md[Cloud Native Computing Foundation (CNCF) Schema Registry API].
