Apicurio Registry content rule reference

Apicurio Registry supports content rules that govern how artifacts evolve. The following sections describe the available rule types, their maturity level for each artifact type, and the order of precedence when both artifact-specific and global rules are configured.

Additional resources

Apicurio Registry content rule types

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

Table 1. Apicurio Registry content rule types
Type Description

VALIDITY

Validates 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

Enforces a compatibility level when updating artifacts (for example, BACKWARD for backward compatibility). This rule 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

Enforces artifact reference integrity when creating or updating artifacts. This rule ensures that artifact references 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.

  • NO_CIRCULAR_REFERENCES: Detect circular reference chains among artifacts.

  • 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 2. 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

Full

OpenAPI

Full

Full

Full

AsyncAPI

Syntax Only

None

Full

OpenRPC

Full

None

Full

GraphQL

Syntax Only

None

Mapping detection not supported

Kafka Connect

Syntax Only

None

Mapping detection not supported

Thrift

Syntax Only

None

Mapping detection not supported

WSDL

Full

None

Mapping detection not supported

XML

Full

None

Mapping detection not supported

XSD

Full

Full

Mapping detection not supported

JSON Schema validity

With the FULL level, the VALIDITY rule checks that a JSON Schema artifact is a valid schema in JSON Schema draft 4, 6, 7, 2019-09, or 2020-12.

  • Draft: the draft is the one that $schema declares. A schema without $schema is validated as draft 7, as the compatibility rule reads it. A schema whose $schema names no draft, such as a custom meta-schema, is also validated as draft 7, but the compatibility rule cannot compare it yet and fails with HTTP status 422.

  • Meta-schema: the schema must be valid against the meta-schema of its draft.

  • References: a reference within the schema must point at something that exists, such as a definition. A reference to another document is resolved against the artifact references recorded for the version. If Apicurio Registry has no content for it, the reference is accepted, because the validity of a schema does not depend on what an external reference points to. No document is fetched over the network. To require that every external reference is recorded, use the INTEGRITY rule.

  • Unused references: an artifact reference that the content does not use is rejected, because it usually indicates a typo in the reference name.

Each rule violation has a JSON Pointer to the problem as its context, for example /items/properties/price/exclusiveMinimum. More than one problem can be reported at once.

The SYNTAX_ONLY level checks only that the content is well-formed JSON.

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