// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/assembly-managing-registry-artifacts-maven.adoc

[id="adding-artifact-references-manually-using-maven-plugin_{context}"]
= Adding artifact references manually using the {registry} Maven plug-in

[role="_abstract"]
Some {registry} artifact types can include _artifact references_ from one artifact file to another. You can create efficiencies by defining reusable schema or API artifacts, and then referencing them from multiple locations in artifact references. 

The following artifact types support artifact references: 

* Apache Avro 
* Google Protobuf 
* JSON Schema 
* OpenAPI
* AsyncAPI

This section shows a simple example of using the {registry} Maven plug-in to manually register an artifact reference to a simple Avro schema artifact stored in {registry}. This example assumes that the following `Exchange` schema artifact has already been created in {registry}:

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

This example then creates a `TradeKey` schema artifact, which includes a reference to the nested `Exchange` schema artifact:

.TradeKey schema with nested reference to 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"
    }
  ]
} 
----

.Prerequisites
* You have created a Maven project for your client application. For more details, see the https://maven.apache.org/index.html[Apache Maven documentation].
* The referenced `Exchange` schema artifact is already created in {registry}.

.Procedure
. Update your Maven `pom.xml` file to use the `apicurio-registry-maven-plugin` to register the `TradeKey` schema, which includes a nested reference to the `Exchange` schema as follows:
+
[source,xml]
----
<plugin>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-maven-plugin</artifactId>
    <version>${apicurio-registry.version}</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>register</goal> <1>
            </goals>
            <configuration>
                <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl> <2>
                <authServerUrl>MY-AUTH-SERVER</authServerUrl> 
                <clientId>MY-CLIENT-ID</clientId>
                <clientSecret>MY-CLIENT-SECRET</clientSecret> <3>
                <clientScope>MY-CLIENT-SCOPE</clientScope>
                <artifacts>
                    <artifact>
                        <groupId>test-group</groupId> <4>
                        <artifactId>TradeKey</artifactId>
                        <version>2.0</version>
                        <type>AVRO</type>
                        <file>
                            ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                        </file>
                        <ifExists>RETURN_OR_UPDATE</ifExists>
                        <canonicalize>true</canonicalize>
                        <references>
                            <reference> <5>
                                <name>com.kubetrade.schema.common.Exchange</name> 
                                <groupId>test-group</groupId>
                                <artifactId>Exchange</artifactId>
                                <version>2.0</version>
                                <type>AVRO</type>
                                <file>
                                    ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                </file>
                                <ifExists>RETURN_OR_UPDATE</ifExists>
                                <canonicalize>true</canonicalize>
                            </reference>
                        </references>
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>
----
+
<1> Specify `register` as the execution goal to upload the schema artifacts to {registry}.
<2> Specify the {registry} URL by using the `../apis/registry/v2` endpoint.
ifdef::apicurio-registry,rh-service-registry[]
<3> If authentication is required, you can specify your authentication server and client credentials.
endif::[]
ifdef::rh-openshift-sr[]
<3> Specify your service account ID and secret and the {org-name} Single Sign-On authentication server: `{sso-token-url}`
endif::[]
<4> Specify the {registry} artifact group ID. You can specify the `default` group if you do not want to use a unique group ID.
<5> Specify the {registry} artifact reference using its group ID, artifact ID, version, type, and location. You can register multiple artifact references in this way.

. Build your Maven project, for example, by using the `mvn package` command. 

[role="_additional-resources"]
.Additional resources
 * For more details on using Apache Maven, see the https://maven.apache.org/index.html[Apache Maven documentation].
 * For an open source example of using the {registry} Maven plug-in to manually register an artifact reference, see the link:https://github.com/Apicurio/apicurio-registry-examples/tree/main/avro-maven-with-references[avro-maven-with-references demonstration example].
 * For more examples of artifact references, see the section on configuring each artifact type in {registry-client-serdes-config}.


