Apicurio Registry content rules

Apicurio Registry supports optional rules that govern the evolution of artifact content, with configuration options at the global, group, and artifact level.

Govern Apicurio Registry content using rules

To govern the evolution of artifact content added to Apicurio Registry, you can configure optional rules. All configured global rules, group-specific rules, or artifact-specific rules must pass before a new artifact version can be added to Apicurio Registry.

Configured artifact-specific rules override any configured group-specific rules, which in turn override any configured global rules.

The goal of these rules is to prevent invalid content from being added to Apicurio Registry and to control the evolution of an artifact (by e.g. checking the compatibility of a new artifact version against previous versions). For example, content can be invalid for the following reasons:

  • Invalid syntax for a given artifact type, for example, AVRO or PROTOBUF.

  • Valid syntax, but semantics violate a specification.

  • Incompatibility, when new content includes breaking changes relative to the current artifact version.

  • Artifact reference integrity, for example, a duplicate or non-existent artifact reference mapping.

You can enable optional content rules using the Apicurio Registry web console, REST API commands, or by using one of the SDKs.

When rules are applied

Rules are applied only when content is added to Apicurio Registry. This includes the following REST operations:

  • Adding an artifact

  • Adding an artifact version

If a rule is violated, Apicurio Registry returns an HTTP error. The response body includes the violated rule and a message showing what went wrong.

Order of precedence of rules

The order of precedence for artifact-specific and global rules is as follows:

  • Artifact-specific rules have the highest priority

  • Group-specific rules have the next highest priority

  • Global rules have the lowest priority

If a rule is configured at a higher level (e.g. at the global level), but you want that rule to be disabled at a lower level, you must configure the same rule (so that it overrides it) at the lower level and set its rules value to NONE.

How rules work

Each rule has a name and configuration information. Apicurio Registry maintains the list of rules for each artifact, each group, and the list of global rules. Each rule in the list consists of a name and configuration for the rule implementation.

When a rule is executed, it is provided with the content of the current version of the artifact (if one exists) and the new version of the artifact being added. The rule implementation returns either passes or fails depending on whether the artifact passes the rule. If not, Apicurio Registry reports the reason why in an HTTP error response. Some rules might not use the previous version of the content. For example, compatibility rules use previous versions, but syntax or semantic validity rules do not.

Additional resources

Content rule configuration

Administrators can configure Apicurio Registry global rules, group-specific rules, and artifact-specific rules. Developers can configure group-specific and artifact-specific rules only.

Apicurio Registry evaluates rule precedence separately for each rule type, such as COMPATIBILITY or VALIDITY. For each rule type, an artifact-specific rule overrides a group-specific rule of the same type, and a group-specific rule overrides a global rule of the same type. If a rule type is not configured at any level, and no default global rule is set for that type in the application properties, Apicurio Registry does not enforce that rule type. Configuring one rule type at a lower level does not disable other rule types that are configured at a higher level.

For example, consider a group with a COMPATIBILITY rule set to BACKWARD, and an artifact in that group with only a VALIDITY rule set to FULL:

  • When you add a new version of the artifact, Apicurio Registry enforces both rules: the VALIDITY rule from the artifact and the COMPATIBILITY rule from the group. The group rule still applies because the artifact rule is of a different type.

  • Apicurio Registry rejects a new version that is not backward compatible, and accepts a new version that passes both rules.

  • To disable compatibility checks for this artifact only, configure a COMPATIBILITY rule set to NONE on the artifact. The artifact-specific rule then overrides the group rule, and Apicurio Registry accepts the previously rejected content.

You can configure group-specific and artifact-specific rules using the Apicurio Registry web console or REST API.

Additional resources

Default global rule configuration

Administrators can configure global rules in several ways.

  • Use the admin/rules operations in the REST API

  • Use the Apicurio Registry web console

  • Set default global rules using Apicurio Registry application properties

Administrators can configure Apicurio Registry at the application level to enable or disable global rules. You can configure default global rules at installation time without post-install configuration using the following application property format:

apicurio.rules.global.<ruleName>

The following rule names are currently supported:

  • compatibility

  • validity

  • integrity

The value of the application property must be a valid configuration option that is specific to the rule being configured.

You can configure these application properties as Java system properties or include them in the Quarkus application.properties file. For more details, see the Quarkus documentation.