Registry Concepts and Glossary

A group is a named namespace for organizing related artifacts. Every artifact belongs to a group. If no group is specified when creating an artifact, it is placed in the default group. Groups can carry their own metadata (description, labels) and can have group-level rules that apply to all artifacts within the group.

An artifact is a named schema or API definition within a group, uniquely identified by the combination of groupId and artifactId. An artifact acts as a container for zero or more artifact versions. Examples of artifacts include an Avro schema, a Protobuf definition, an OpenAPI specification, or an AsyncAPI definition.

An artifact version is an immutable snapshot of an artifact’s content. Each version is identified within its artifact by a version string and is also assigned a globally unique numeric globalId. Once created, the content of a version cannot be changed. Versions have a lifecycle state (see Version State) and can carry user-defined metadata and labels.

Content is the actual schema or API payload stored in the registry (for example, an Avro JSON schema, a Protobuf .proto definition, or an OpenAPI YAML specification). Content is deduplicated: if two artifact versions have identical content, they share the same contentId.

A globalId is a globally unique numeric identifier assigned to each artifact version in the registry. It is auto-generated when a version is created and can be used to retrieve a specific version directly, regardless of group or artifact.

A contentId is a unique numeric identifier for a piece of content. Because content is deduplicated, multiple artifact versions with identical content share the same contentId. This is useful when different artifacts or versions reference the same schema payload.

A branch is a named, ordered sequence of artifact versions within an artifact. Branches are used to track parallel evolution paths for an artifact. For example, an artifact might have a latest branch (the default) and a 1.x branch for maintenance releases.

An artifact reference is a reference from one artifact to another. References model relationships such as $ref in JSON Schema, import in Protobuf, or type references in Avro. When an artifact version contains references, the registry tracks them to support referential integrity validation.

Labels are user-defined key-value string pairs that can be attached to groups, artifacts, or artifact versions. Labels are used for organization, categorization, and filtering when searching.

A rule is a validation constraint that is applied when new content is added to the registry. Rules operate at three levels:

When a rule is configured at multiple levels, the most specific level takes precedence (artifact > group > global).

The available rule types are:

For more information, see Apicurio Registry content rule reference.

The version state represents the lifecycle state of an artifact version. The possible states are:

State transitions are allowed between any of these three states.

The artifact type identifies the format or schema language of an artifact’s content. The registry uses the artifact type to determine how to parse, validate, and check compatibility of the content. Supported artifact types include:

For more information, see Apicurio Registry artifact reference.