Apicurio Registry artifact and rule reference

This chapter provides details on the supported artifact types, states, metadata, and content rules that are stored in Apicurio Registry.

Additional resources

Apicurio Registry artifact types

You can store and manage a wide range of schema and API artifact types in Apicurio Registry.

Table 1. Apicurio Registry artifact types
Type Description

ASYNCAPI

AsyncAPI specification

AVRO

Apache Avro schema

GRAPHQL

GraphQL schema

JSON

JSON Schema

KCONNECT

Apache Kafka Connect schema

OPENAPI

OpenAPI specification

PROTOBUF

Google protocol buffers schema

WSDL

Web Services Definition Language

XML

Extensible Markup Language

XSD

XML Schema Definition

Apicurio Registry artifact states

The valid artifact states in Apicurio Registry are ENABLED, DISABLED, and DEPRECATED.

Table 2. Apicurio Registry artifact states
State Description

ENABLED

Basic state, all the operations are available.

DISABLED

The artifact and its metadata is viewable and searchable using the Apicurio Registry web console, but its content cannot be fetched by any client.

DEPRECATED

The artifact is fully usable but a header is added to the REST API response whenever the artifact content is fetched. The Apicurio Registry Rest Client will also log a warning whenever it sees deprecated content.

Apicurio Registry artifact metadata

When an artifact is added to Apicurio Registry, a set of metadata properties is stored along with the artifact content. This metadata consists of a set of generated read-only properties, along with some properties that you can set.

Table 3. Apicurio Registry read-only metadata
Property Type

contentId

integer

createdBy

string

createdOn

date

globalId

integer

groupId

string

id

string

modifiedBy

string

modifiedOn

date

references

array of ArtifactReference

type

ArtifactType

version

integer
Table 4. Apicurio Registry editable metadata
Property Type

description

string

labels

array of string

name

string

properties

map

state

ArtifactState
Updating artifact metadata

  • You can use the Apicurio Registry REST API to update the set of editable properties using the metadata endpoints.

  • You can edit the state property only by using the state transition API. For example, you can mark an artifact as deprecated or disabled.

Additional resources

For more details, see the /artifacts/{artifactId}/meta endpoint in the Apicurio Registry REST API documentation.

Apicurio Registry content rule types

You can specify VALIDITY, COMPATIBILITY, and INTEGRITY rule types to govern content evolution in Apicurio Registry. Theses rule types apply to both global rules and artifact-specific rules.

Table 5. Apicurio Registry content rule types
Type Description

VALIDITY

Validate content before adding it to Apicurio Registry. The possible configuration values for this rule are as follows:

  • FULL: The validation is both syntax and semantic.

  • SYNTAX_ONLY: The validation is syntax only.

  • NONE: All validation checks are disabled.

COMPATIBILITY

Enforce a compatibility level when updating artifacts (for example, select BACKWARD for backwards compatibility). Ensures that new artifacts are compatible with previously added artifact versions or clients. The possible configuration values for this rule are as follows:

  • FULL: The new artifact is forward and backward compatible with the most recently added artifact.

  • FULL_TRANSITIVE: The new artifact is forward and backward compatible with all previously added artifacts.

  • BACKWARD: Clients using the new artifact can read data written using the most recently added artifact.

  • BACKWARD_TRANSITIVE: Clients using the new artifact can read data written using all previously added artifacts.

  • FORWARD: Clients using the most recently added artifact can read data written using the new artifact.

  • FORWARD_TRANSITIVE: Clients using all previously added artifacts can read data written using the new artifact.

  • NONE: All backward and forward compatibility checks are disabled.

INTEGRITY

Enforce artifact reference integrity when creating or updating artifacts. Enable and configure this rule to ensure that any artifact references provided are correct. The possible configuration values for this rule are as follows:

  • FULL: All artifact reference integrity checks are enabled.

  • NO_DUPLICATES: Detect if there are any duplicate artifact references.

  • REFS_EXIST: Detect if there are any references to non-existent artifacts.

  • ALL_REFS_MAPPED: Ensure that all artifact references are mapped.

  • NONE: All artifact reference integrity checks are disabled.

Apicurio Registry content rule maturity

Not all content rules are fully implemented for every artifact type supported by Apicurio Registry. The following table shows the current maturity level for each rule and artifact type:

Table 6. Apicurio Registry content rule maturity matrix
Artifact type Validity rule Compatibility rule Integrity rule

Avro

Full

Full

Full

Protobuf

Full

Full

Full

JSON Schema

Full

Full

Mapping detection not supported

OpenAPI

Full

None

Full

AsyncAPI

Syntax Only

None

Full

GraphQL

Syntax Only

None

Mapping detection not supported

Kafka Connect

Syntax Only

None

Mapping detection not supported

WSDL

Full

None

Mapping detection not supported

XML

Full

None

Mapping detection not supported

XSD

Full

None

Mapping detection not supported

Apicurio Registry content rule precedence

When you add or update an artifact, Apicurio Registry applies rules to check the validity, compatibility, or integrity of the artifact content. Configured artifact-specific rules override the equivalent configured global rules, as shown in the following table.

Table 7. Apicurio Registry content rule precedence
Artifact-specific rule Global rule Rule applied to this artifact Global rule available for other artifacts?

Enabled

Enabled

Artifact-specific

Yes

Disabled

Enabled

Global

Yes

Disabled

Disabled

None

No

Enabled, set to None

Enabled

None

Yes

Disabled

Enabled, set to None

None

No