Apicurio Registry content rules
To govern the evolution of registry content, you can configure optional rules for artifact content added to the registry. All configured global rules or artifact rules must pass before a new artifact version can be uploaded to the registry. Configured artifact rules override any configured global rules.
The goal of these rules is to prevent invalid content from being added to the registry. For example, content can be invalid for the following reasons:
Invalid syntax for a given artifact type (for example,
Valid syntax, but semantics violate a specification
Incompatibility, when new content includes breaking changes relative to the current artifact version
You can enable optional content rules using the Apicurio Registry web console, REST API commands, or a Java client application.
Rules are applied only when content is added to the registry. This includes the following REST operations:
Adding an artifact
Updating 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.
You can configure Apicurio Registry content rules at a global level and at an artifact level. The order of precedence is as follows:
If you enable an artifact rule and the equivalent global rule, the artifact rule overrides the global rule.
If you disable an artifact rule, and enable the equivalent global rule, the global rule applies.
If you disable a rule at the artifact level and at the global level, you disable the rule for all artifacts.
If you set a rule value to
NONEat the artifact level, you override the enabled global rule. In this case, the artifact rule value
NONEtakes precedence for this artifact, but the enabled global rule continues to apply to any other artifacts that have the rule disabled at the artifact level.
Each rule has a name and configuration information. The registry maintains the list of rules for each artifact and the list of global rules. Each rule in the list consists of a name and configuration for the rule implementation.
A rule 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 true or false depending on whether the artifact passes the rule. If not, the 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.
For more details, see Apicurio Registry artifact and rule reference.
You can configure rules individually for each artifact, as well as globally. Apicurio Registry applies the rules configured for the specific artifact. If no rules are configured at that level, Apicurio Registry applies the globally configured rules. If no global rules are configured, no rules are applied.
Configure artifact rules
You can configure artifact rules using the Apicurio Registry web console or REST API. For details, see the following:
Configure global rules
You can configure global rules in several ways:
/rulesoperations in the REST API
Use the Apicurio Registry web console
Set default global rules using Apicurio Registry application properties
You 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:
The following rule names are currently supported:
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.