// 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.

Artifacts have metadata, both generated and editable.  Standard metadata for an artifact includes (but may not be limited to):

=== Generated or immutable properties

- groupId
- artifactId
- artifactType
- createdOn
- modifiedBy
- modifiedOn

=== Editable properties
- name
- description
- labels
- owner

[discrete]
== Artifact Versions
Every artifact is composed of zero or more _artifact version_s.  Only artifact versions have actual
content (as well as metadata).  These versions represent the evolution of the content of an artifact,
and are immutable.  You can think of an Artifact as an ordered sequence of Versions, typically with
the most recent version representing the "current" schema or API design content.


Artifact Versions have metadata, both generated and editable.  Standard metadata for an artifact version includes (but may not be limited to):

=== Generated or immutable properties

- groupId
- artifactId
- version
- globalId
- contentId
- owner
- createdOn
- modifiedBy
- modifiedOn

=== Editable properties
- name
- description
- labels
- state


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

Groups have metadata, both generated and editable.  Standard metadata for a group includes (but may not be limited to):

=== Generated or immutable properties

- groupId
- owner
- createdOn
- modifiedBy
- modifiedOn

=== Editable properties
- description
- labels

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.

NOTE: Specifying a group is optional when using the {registry} web console, and the `default` group is used 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:
** {managing-registry-artifacts-api}.
** {managing-registry-artifacts-maven}.
* For a Java example, see the https://github.com/Apicurio/apicurio-registry/tree/main/examples/serdes-with-references[Apicurio Registry SerDes with references demonstration].
