Apicurio Registry concepts and glossary

You can use these definitions to understand the core concepts of Apicurio Registry.

Group

A group is a named namespace for organizing related artifacts.

Every artifact belongs to a group. If you do not specify a group when creating an artifact, Apicurio Registry places it 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.

Artifact

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.

Artifact version

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. After you create a version, you cannot change its content. Versions have a lifecycle state (see Version state) and can carry user-defined metadata and labels.

Content

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.

Global ID

A global ID is a globally unique numeric identifier for each artifact version in the registry.

Apicurio Registry auto-generates the global ID when you create a version. You can use the global ID to retrieve a specific version directly, regardless of group or artifact.

Content ID

A content ID 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.

Branch

A branch is a named, ordered sequence of artifact versions within an artifact.

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

Artifact reference

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, Apicurio Registry stores them to support referential integrity validation.

Labels

Labels are user-defined key-value string pairs that you can attach to groups, artifacts, or artifact versions.

You can use labels for organization, categorization, and filtering when searching.

Rule

A rule is a validation constraint that Apicurio Registry applies when you add new content.

Rules operate at three levels:

  • Global rules apply to all artifacts in the registry.

  • Group rules apply to all artifacts within a specific group.

  • Artifact rules apply to a specific artifact.

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

The available rule types are:

  • Validity rule: validates that the content is syntactically and semantically correct for its artifact type.

  • Compatibility rule: validates that new content is compatible with previous versions according to a specified compatibility level.

  • Integrity rule: validates referential integrity of artifact references.

Additional resources

Version state

The version state represents the lifecycle state of an artifact version.

The possible states are:

  • ENABLED: the version is fully available. You can retrieve content and metadata normally.

  • DEPRECATED: the version is still available, but Apicurio Registry returns a warning header to signal that consumers must migrate to a newer version.

  • DISABLED: the version metadata is visible, but you cannot fetch the version content.

You can transition between any of these three states.

Artifact type

The artifact type identifies the format or schema language of an artifact’s content.

Apicurio Registry uses the artifact type to parse, validate, and check compatibility of the content. Supported artifact types include:

  • AVRO: Apache Avro schema

  • PROTOBUF: Google Protocol Buffers definition

  • JSON: JSON Schema

  • OPENAPI: OpenAPI specification

  • ASYNCAPI: AsyncAPI specification

  • GRAPHQL: GraphQL schema definition

  • KCONNECT: Apache Kafka Connect schema

  • WSDL: Web Services Description Language definition

  • XSD: XML Schema Definition

  • XML: XML document

  • AGENT_CARD: AI Agent Card (A2A protocol)

  • ICEBERG_TABLE: Apache Iceberg table metadata

  • ICEBERG_VIEW: Apache Iceberg view metadata

Additional resources