Configuring custom artifact types

You can configure Apicurio Registry with custom artifact types at deployment time, in addition to the built-in types. Webhooks or Java classes provide content detection, validation, compatibility checking, canonicalization, and dereferencing for each custom type. You can add Java providers to a derived container image without rebuilding Apicurio Registry.

Artifact type configuration file

At startup, Apicurio Registry reads the list of supported artifact types from a JSON file. The apicurio.artifact-types.config-file property specifies the file location, with APICURIO_ARTIFACT_TYPES_CONFIG_FILE as the corresponding environment variable. When the file does not exist, only the built-in artifact types are available.

Example configuration file

{
  "includeStandardArtifactTypes": true,
  "artifactTypes": [
    {
      "artifactType": "MARKDOWN",
      "name": "Markdown",
      "description": "Markdown documents with a level-1 title and level-2 sections.",
      "contentTypes": ["text/markdown", "text/plain"],
      "contentAccepter": {
        "type": "java",
        "classname": "io.apicurio.registry.examples.customtypes.MarkdownContentAccepter"
      },
      "contentValidator": {
        "type": "java",
        "classname": "io.apicurio.registry.examples.customtypes.MarkdownContentValidator"
      },
      "compatibilityChecker": {
        "type": "webhook",
        "url": "https://markdown-service.example.com/compatibility",
        "headers": { "Authorization": "Bearer YOUR_SECRET_TOKEN" }
      }
    }
  ]
}

Table 1. Top-level properties
Property	Description
`includeStandardArtifactTypes`	Whether the built-in artifact types, such as `AVRO`, `JSON`, and `OPENAPI`, remain available. When this property is `false`, Apicurio Registry supports only the types listed in `artifactTypes`.
`artifactTypes`	The list of custom artifact types.

Table 2. Artifact type properties
Property	Description
`artifactType`	The unique identifier of the type, such as `MARKDOWN`, in the REST API and the user interface.
`name`, `description`	Display name and description of the type.
`contentTypes`	The content types (media types) accepted for this artifact type.
`contentAccepter`	Provider that determines whether content belongs to this type. Apicurio Registry uses this provider to detect the artifact type when a client does not specify one.
`contentValidator`	Provider that implements the `VALIDITY` rule (`SYNTAX_ONLY` and `FULL` levels).
`compatibilityChecker`	Provider that implements the `COMPATIBILITY` rule (`BACKWARD`, `FORWARD`, `FULL`, and their transitive variants).
`contentCanonicalizer`	Provider that produces the canonical form of the content. Apicurio Registry uses this form to recognize equivalent content, for example, in canonical search and deduplication.
`contentDereferencer`	Provider that inlines or rewrites references to other artifacts when content is retrieved with `references=DEREFERENCE` or `references=REWRITE`.
`referenceFinder`	Provider that finds external references in the content. The Maven plug-in uses this provider to register references automatically.

Every provider property is optional. When you omit a provider, Apicurio Registry skips the corresponding operation for the type. For example, without a contentAccepter, Apicurio Registry does not detect the type automatically. Without a contentValidator, Apicurio Registry treats all content as valid. Without a compatibilityChecker, Apicurio Registry treats all content as compatible.

Table 3. Provider types
Provider	Description
`{"type": "java", "classname": "…"}`	A Java class that implements the corresponding interface of the `io.apicurio:apicurio-registry-schema-util-common` module: `io.apicurio.registry.content.ContentAccepter`, `io.apicurio.registry.rules.validity.ContentValidator`, `io.apicurio.registry.rules.compatibility.CompatibilityChecker`, `io.apicurio.registry.content.canon.ContentCanonicalizer`, `io.apicurio.registry.content.dereference.ContentDereferencer`, or `io.apicurio.registry.content.refs.ReferenceFinder`. The class must have a public no-argument constructor and must be available on the class path of Apicurio Registry.
`{"type": "webhook", "url": "…", "headers": {…}}`	An HTTP endpoint that Apicurio Registry calls with a JSON request that describes the operation, including the content, resolved references, and rule level. The endpoint returns a JSON response. Apicurio Registry sends the optional `headers` with every request, for example, for authentication. Webhooks work with the standard container image but add a network round trip to every operation.

Additional resources

Adding Java providers with the mutable container image
Apicurio Registry artifact reference

Container images for custom artifact types

The standard Apicurio Registry container image supports webhook providers. The VERSION-mutable image variant also supports Java providers by using Quarkus re-augmentation, which updates the application class path to include additional Java archive (JAR) files.

The standard image uses Quarkus fast-jar packaging, which indexes the class path when the image is built. The application cannot load a JAR file that you copy into the image after that indexing step. Each Apicurio Registry release also provides a VERSION-mutable image with Quarkus mutable-jar packaging for re-augmentation.

Table 4. Container image comparison
Characteristic	Standard image	`-mutable` image
Packaging	Quarkus fast-jar (`/deployments`)	Quarkus mutable-jar (`/deployments/quarkus-app`)
Size	Baseline	Approximately 47 MB (150 JAR files) of additional files in `lib/deployment`, or roughly 100 MB of image size with the current image layering. A derived image adds only a few MB. The `build.sh --prune` command removes the deployment JAR files from the file system but does not shrink the layers inherited from the base image.
Java providers	Not supported; webhook providers are available	Supported by `/deployments/build.sh`
Runtime behavior	Baseline	Same runtime behavior and startup time as the standard image

Additional resources

Quarkus re-augmentation guide

Adding Java providers with the mutable container image

You can add custom Java providers to Apicurio Registry by building a derived container image from the VERSION-mutable image. The derived image includes your provider Java archive (JAR) file and runs Quarkus re-augmentation at image build time to add the providers to the application class path.

Prerequisites

You have a JAR file containing your provider classes, compiled against the io.apicurio:apicurio-registry-schema-util-common module of the same Apicurio Registry minor version. The JAR file must not bundle the Apicurio Registry or Quarkus classes. Other dependencies must be available in the image or in the providers directory.
You have an artifact type configuration file as described in Artifact type configuration file.
You have Docker and curl installed.

Procedure

Create a Dockerfile that derives from the mutable image:
```
FROM apicurio/apicurio-registry:latest-release-mutable

COPY --chown=1001:0 my-artifact-type.jar /deployments/quarkus-app/providers/
COPY --chown=1001:0 artifact-types.json /deployments/artifact-types.json

RUN /deployments/build.sh --prune

ENV APICURIO_ARTIFACT_TYPES_CONFIG_FILE=/deployments/artifact-types.json
```
The /deployments/build.sh script re-augments the application with the JAR files in /deployments/quarkus-app/providers. It adds only the regenerated class-path index, a few MB in size, to the derived image. The --prune option removes the lib/deployment directory, which contains the Quarkus deployment JAR files, from the file system afterward. Omit --prune if you want to re-augment the derived image again later.
Build the image:
```
$ docker build -t my-registry .
```
Re-augmentation takes approximately 10 seconds and requires roughly 1 GB of memory during the image build. You can adjust the memory settings with the JAVA_OPTS_APPEND environment variable. Rebuild the derived image whenever the provider JAR files change. Re-augmentation does not change the startup time or runtime behavior of Apicurio Registry.

Run the image:

$ docker run -it -p 8080:8080 my-registry

Verification

In another terminal, list the available artifact types:
```
$ curl http://localhost:8080/apis/registry/v3/admin/config/artifactTypes
```
Verify that the response includes the name of your custom artifact type.

Additional resources