[id="all-registry-configs_{context}"]
= {registry} configuration options

The following {registry} configuration options are available for each component category:

== a2a
.a2a configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.a2a.agent.capabilities.push-notifications`
|`boolean`
|`false`
|`3.0.0`
|Whether the agent supports push notifications
|`apicurio.a2a.agent.capabilities.streaming`
|`boolean`
|`false`
|`3.0.0`
|Whether the agent supports streaming
|`apicurio.a2a.agent.description`
|`string`
|`API and Schema Registry with A2A Agent support`
|`3.0.0`
|Description of the registry agent
|`apicurio.a2a.agent.name`
|`string`
|`Apicurio Registry`
|`3.0.0`
|Name of the registry agent for A2A discovery
|`apicurio.a2a.agent.provider.organization`
|`string`
|`Apicurio`
|`3.0.0`
|Organization name for the agent provider
|`apicurio.a2a.agent.provider.url`
|`string`
|`https://www.apicur.io`
|`3.0.0`
|URL for the agent provider
|`apicurio.a2a.agent.url`
|`optional<string>`
|
|`3.0.0`
|Base URL for the registry agent's A2A endpoint
|`apicurio.a2a.agent.version`
|`optional<string>`
|
|`3.0.0`
|Version of the registry agent (defaults to app version)
|`apicurio.a2a.enabled`
|`boolean`
|`false`
|`3.0.0`
|Enable A2A protocol support _(experimental)_
|===

== api
.api configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.api.errors.include-stack-in-response`
|`boolean`
|`false`
|`2.1.4.Final`
|Include stack trace in errors responses
|`apicurio.apis.date-format`
|`string`
|`yyyy-MM-dd'T'HH:mm:ss'Z'`
|`2.4.3.Final`
|API date format (DEPRECATED - do not use)
|`apicurio.apis.date-format-timezone`
|`string`
|`UTC`
|`2.4.3.Final`
|API date format timezone (DEPRECATED - do not use)
|`apicurio.apis.v3.base-href`
|`string`
|`_`
|`2.5.0.Final`
|API base href (URI)
|`apicurio.disable.apis`
|`optional<list<string>>`
|
|`2.0.0.Final`
|Disable APIs
|===

== auth
.auth configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.auth.admin-override.claim`
|`string`
|`org-admin`
|`2.1.0.Final`
|Auth admin override claim
|`apicurio.auth.admin-override.claim-value`
|`string`
|`true`
|`2.1.0.Final`
|Auth admin override claim value
|`apicurio.auth.admin-override.enabled`
|`boolean`
|`false`
|`2.1.0.Final`
|Auth admin override enabled
|`apicurio.auth.admin-override.from`
|`string`
|`token`
|`2.1.0.Final`
|Auth admin override from
|`apicurio.auth.admin-override.role`
|`string`
|`sr-admin`
|`2.1.0.Final`
|Auth admin override role
|`apicurio.auth.admin-override.type`
|`string`
|`role`
|`2.1.0.Final`
|Auth admin override type
|`apicurio.auth.admin-override.user`
|`string`
|`admin`
|`3.0.0`
|Auth admin override user name
|`apicurio.auth.anonymous-read-access.enabled`
|`boolean [dynamic]`
|`false`
|`2.1.0.Final`
|Anonymous read access
|`apicurio.auth.authenticated-read-access.enabled`
|`boolean [dynamic]`
|`false`
|`2.1.4.Final`
|Authenticated read access
|`apicurio.auth.owner-only-authorization`
|`boolean [dynamic]`
|`false`
|`2.0.0.Final`
|Artifact owner-only authorization
|`apicurio.auth.owner-only-authorization.limit-group-access`
|`boolean [dynamic]`
|`false`
|`2.1.0.Final`
|Artifact group owner-only authorization
|`apicurio.auth.role-based-authorization`
|`boolean`
|`false`
|`2.1.0.Final`
|Enable role based authorization
|`apicurio.auth.role-source`
|`string`
|`token`
|`2.1.0.Final`
|Auth roles source
|`apicurio.auth.role-source.header.name`
|`string`
|
|`2.4.3.Final`
|Header authorization name
|`apicurio.auth.roles.admin`
|`string`
|`sr-admin`
|`2.0.0.Final`
|Auth roles admin
|`apicurio.auth.roles.developer`
|`string`
|`sr-developer`
|`2.1.0.Final`
|Auth roles developer
|`apicurio.auth.roles.readonly`
|`string`
|`sr-readonly`
|`2.1.0.Final`
|Auth roles readonly
|`apicurio.authn.audit.log.prefix`
|`string`
|`audit`
|`2.2.6`
|Prefix used for application audit logging.
|`apicurio.authn.basic-client-credentials.cache-expiration`
|`integer`
|`10`
|`2.2.6.Final`
|Default client credentials token expiration time in minutes.
|`apicurio.authn.basic-client-credentials.cache-expiration-offset`
|`integer`
|`10`
|`2.5.9.Final`
|Client credentials token expiration offset from JWT expiration, in seconds.
|`apicurio.authn.basic-client-credentials.enabled`
|`boolean [dynamic]`
|`false`
|`2.1.0.Final`
|Enable basic auth client credentials
|`apicurio.authn.basic.scope`
|`optional<string>`
|
|`2.5.0.Final`
|Client credentials scope.
|`apicurio.authn.mechanism.priority`
|`string`
|`basic,proxy-header,oidc`
|`3.2.3`
|Comma-separated ordered list of authentication mechanism names. Only mechanisms that are also enabled will be used. Valid values: basic, proxy-header, oidc.
|`apicurio.authn.proxy-header.email`
|`string`
|`X-Forwarded-Email`
|`3.1.7`
|Header name for email
|`apicurio.authn.proxy-header.enabled`
|`boolean`
|`false`
|`3.1.7`
|Enable proxy header authentication
|`apicurio.authn.proxy-header.groups`
|`string`
|`X-Forwarded-Groups`
|`3.1.7`
|Header name for groups/roles
|`apicurio.authn.proxy-header.trust-proxy-authorization`
|`boolean`
|`false`
|`3.1.0.Final`
|When enabled, authorization checks are skipped and the proxy is trusted to have performed authorization
|`apicurio.authn.proxy-header.username`
|`string`
|`X-Forwarded-User`
|`3.1.7`
|Header name for username
|`quarkus.http.auth.basic`
|`boolean`
|`false`
|`3.X.X.Final`
|Enable basic auth
|`quarkus.oidc.client-id`
|`string`
|
|`2.0.0.Final`
|Client identifier used by the server for authentication.
|`quarkus.oidc.client-secret`
|`optional<string>`
|
|`2.1.0.Final`
|Client secret used by the server for authentication.
|`quarkus.oidc.tenant-enabled`
|`boolean`
|`false`
|`2.0.0.Final`
|Enable auth
|`quarkus.oidc.token-path`
|`string`
|`/protocol/openid-connect/token/`
|`2.1.0.Final`
|Authentication server token endpoint.
|===

== cache
.cache configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.config.cache.enabled`
|`boolean`
|`true`
|`2.2.2.Final`
|Registry cache enabled
|`apicurio.http-caching.enabled`
|`boolean`
|`false`
|`3.2.0`
|Enable or disable HTTP caching entirely. When disabled, no server-side cache headers (ETag, Surrogate-Control, etc.) are sent, and cache strategies are not evaluated. At least one of the max-age configurations must be set to > 0, otherwise caching is automatically disabled and this property has no effect.
|`apicurio.http-caching.extra-headers-enabled`
|`boolean`
|`true`
|`3.2.0`
|Send additional informational headers to help understand caching behavior. Extra headers include X-Cache-Cacheability which indicates the evaluated cacheability level. These headers are useful for development, troubleshooting, and making additional decisions in the cache configuration.
|`apicurio.http-caching.high-cacheability.max-age-seconds`
|`long`
|`864000`
|`3.2.0`
|Expiration for high cacheability operations, in seconds. If set to <= 0, caching is disabled for these operations.
|`apicurio.http-caching.higher-quality-etags-enabled`
|`boolean`
|`true`
|`3.2.0`
|Provide higher quality ETags if possible, but they might be more expensive to compute. This feature trades more computation for potentially higher cacheability of some operations. 
|`apicurio.http-caching.low-cacheability.max-age-seconds`
|`long`
|`10`
|`3.2.0`
|Expiration for low cacheability operations, in seconds. If set to <= 0, caching is disabled for these operations.
|`apicurio.http-caching.moderate-cacheability.max-age-seconds`
|`long`
|`30`
|`3.2.0`
|Expiration for moderate cacheability operations, in seconds. If set to <= 0, caching is disabled for these operations.
|`apicurio.http-caching.opaque-etags-enabled`
|`optional<boolean>`
|
|`3.2.0`
|Hash raw ETag values before adding them to the header. Enabling this feature might marginally increase security, while disabling is useful for testing and debugging. If no value is provided, the feature is enabled when the `prod` profile is active.
|`apicurio.http-caching.vary-headers`
|`list<string>`
|`Accept,Accept-Encoding,Authorization`
|`3.2.0`
|Comma-separated list of request header names to include in the Vary response header. The Vary header tells caches that the response varies based on the values of the listed request headers.
|===

== ccompat
.ccompat configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.ccompat.group-concat.enabled`
|`boolean`
|`false`
|`2.6.2.Final`
|Enable group support via concatenation in subject (compatibility API)
|`apicurio.ccompat.group-concat.separator`
|`string`
|`:`
|`2.6.2.Final`
|Separator to use when group concatenation is enabled (compatibility API)
|`apicurio.ccompat.legacy-id-mode.enabled`
|`boolean [dynamic]`
|`false`
|`2.0.2.Final`
|Legacy ID mode (compatibility API)
|`apicurio.ccompat.max-subjects`
|`integer [dynamic]`
|`1000`
|`2.4.2.Final`
|Maximum number of Subjects returned (compatibility API)
|`apicurio.ccompat.use-canonical-hash`
|`boolean [dynamic]`
|`false`
|`2.3.0.Final`
|Canonical hash mode (compatibility API)
|===

== contracts
.contracts configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.contracts.enabled`
|`boolean`
|`false`
|`3.2.0`
|Enable data contracts support _(experimental)_
|===

== download
.download configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.download.href.ttl.seconds`
|`long [dynamic]`
|`30`
|`2.1.2.Final`
|Download link expiry
|===

== gitops
.gitops configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.gitops.repo.branch`
|`string`
|`main`
|`3.2.0`
|Branch to read from. _(experimental)_
|`apicurio.gitops.repo.dir`
|`optional<string>`
|
|`3.2.0`
|Directory name of the Git repository, relative to the workspace. _(experimental)_
|`apicurio.gitops.workspace`
|`string`
|`.`
|`3.2.0`
|Base directory where Git repositories are mounted. Repository directories are resolved relative to this path. _(experimental)_
|===

== health
.health configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.liveness.errors.ignored`
|`optional<list<string>>`
|
|`1.2.3.Final`
|Ignored liveness errors
|`apicurio.metrics.persistence-exception-liveness-check.counter-reset-window-duration.seconds`
|`integer`
|`60`
|`1.0.2.Final`
|Counter reset window duration of persistence liveness check
|`apicurio.metrics.persistence-exception-liveness-check.error-threshold`
|`integer`
|`1`
|`1.0.2.Final`
|Error threshold of persistence liveness check
|`apicurio.metrics.persistence-exception-liveness-check.logging.disabled`
|`boolean`
|`false`
|`2.0.0.Final`
|Disable logging of persistence liveness check
|`apicurio.metrics.persistence-exception-liveness-check.status-reset-window-duration.seconds`
|`integer`
|`300`
|`1.0.2.Final`
|Status reset window duration of persistence liveness check
|`apicurio.metrics.persistence-timeout-readiness-check.error-threshold`
|`integer`
|`5`
|`1.0.2.Final`
|Error threshold of persistence readiness check
|`apicurio.metrics.persistence-timeout-readiness-check.timeout.seconds`
|`integer`
|`15`
|`1.0.2.Final`
|Timeout of persistence readiness check
|`apicurio.metrics.persitence-timeout-readiness-check.status-reset-window-duration.seconds`
|`integer`
|`300`
|`1.0.2.Final`
|Status reset window duration of persistence readiness check
|`apicurio.metrics.resonse-error-liveness-check.counter-reset-window-duration.seconds`
|`integer`
|`60`
|`1.0.2.Final`
|Counter reset window duration of response liveness check
|`apicurio.metrics.response-error-liveness-check.counter-reset-window-duration.seconds`
|`integer`
|`60`
|`1.0.2.Final`
|Counter reset window duration of persistence readiness check
|`apicurio.metrics.response-error-liveness-check.disabled`
|`boolean`
|`false`
|`2.0.0.Final`
|Disable logging of response liveness check
|`apicurio.metrics.response-error-liveness-check.error-threshold`
|`integer`
|`1`
|`1.0.2.Final`
|Error threshold of response liveness check
|`apicurio.metrics.response-error-liveness-check.status-reset-window-duration.seconds`
|`integer`
|`300`
|`1.0.2.Final`
|Status reset window duration of response liveness check
|`apicurio.metrics.response-timeout-readiness-check.counter-reset-window-duration.seconds`
|`instance<integer>`
|`60`
|`1.0.2.Final`
|Counter reset window duration of response readiness check
|`apicurio.metrics.response-timeout-readiness-check.error-threshold`
|`instance<integer>`
|`1`
|`1.0.2.Final`
|Error threshold of response readiness check
|`apicurio.metrics.response-timeout-readiness-check.timeout.seconds`
|`instance<integer>`
|`10`
|`1.0.2.Final`
|Timeout of response readiness check
|`apicurio.metrics.response-timeout-rediness-check.status-reset-window-duration.seconds`
|`instance<integer>`
|`300`
|`1.0.2.Final`
|Status reset window duration of response readiness check
|`apicurio.storage.metrics.cache.check-period.ms`
|`long`
|`30000`
|`2.1.0.Final`
|Storage metrics cache check period
|===

== iceberg
.iceberg configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.iceberg.default-prefix`
|`string`
|`default`
|`3.0.0`
|Default prefix (catalog identifier) for the Iceberg REST API
|`apicurio.iceberg.enabled`
|`boolean`
|`false`
|`3.0.0`
|Enable the Iceberg REST Catalog API _(experimental)_
|`apicurio.iceberg.warehouse`
|`optional<string>`
|
|`3.0.0`
|Default warehouse location for Iceberg tables
|`apicurio.metrics.iceberg.enabled`
|`boolean`
|`true`
|`3.0.0`
|Enable Iceberg-specific metrics collection
|===

== import
.import configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.import.preserveContentId`
|`boolean`
|`true`
|`3.0.0`
|When set to true, content IDs from the import file will be used (otherwise new IDs will be generated).  Defaults to 'true'.
|`apicurio.import.preserveGlobalId`
|`boolean`
|`true`
|`3.0.0`
|When set to true, global IDs from the import file will be used (otherwise new IDs will be generated).  Defaults to 'true'.
|`apicurio.import.requireEmptyRegistry`
|`boolean`
|`true`
|`3.0.0`
|When set to true, importing data will only work when the registry is empty.  Defaults to 'true'.
|`apicurio.import.url`
|`optional<url>`
|
|`2.1.0.Final`
|The import URL
|`apicurio.import.work-dir`
|`string`
|
|`3.0.0`
|Temporary work directory to use when importing data.
|===

== kubernetesops
.kubernetesops configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.kubernetesops.label.registry-id`
|`string`
|`apicurio.io/registry-id`
|`3.0.0`
|Label key used to identify ConfigMaps belonging to this registry instance. The label value must match `apicurio.polling-storage.id`. _(experimental)_
|`apicurio.kubernetesops.namespace`
|`optional<string>`
|
|`3.0.0`
|Kubernetes namespace to watch for ConfigMaps. If not specified, auto-detects the pod's namespace or falls back to "default". _(experimental)_
|`apicurio.kubernetesops.watch.enabled`
|`boolean`
|`true`
|`3.0.0`
|Enable Kubernetes Watch API for real-time ConfigMap change detection. When enabled, changes are detected immediately via watch events in addition to periodic polling. _(experimental)_
|`apicurio.kubernetesops.watch.reconnect-delay`
|`duration`
|`PT10S`
|`3.0.0`
|Base delay before reconnecting after watch failure. Uses exponential backoff with a maximum of 5 minutes. _(experimental)_
|===

== limits
.limits configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.limits.config.max-artifact-labels`
|`long`
|`-1`
|`2.2.3.Final`
|Max artifact labels
|`apicurio.limits.config.max-artifact-properties`
|`long`
|`-1`
|`2.1.0.Final`
|Max artifact properties
|`apicurio.limits.config.max-artifacts`
|`long`
|`-1`
|`2.1.0.Final`
|Max artifacts
|`apicurio.limits.config.max-description-length`
|`long`
|`-1`
|`2.1.0.Final`
|Max artifact description length
|`apicurio.limits.config.max-label-size.bytes`
|`long`
|`-1`
|`2.1.0.Final`
|Max artifact label size
|`apicurio.limits.config.max-name-length`
|`long`
|`-1`
|`2.1.0.Final`
|Max artifact name length
|`apicurio.limits.config.max-property-key-size.bytes`
|`long`
|`-1`
|`2.1.0.Final`
|Max artifact property key size
|`apicurio.limits.config.max-property-value-size.bytes`
|`long`
|`-1`
|`2.1.0.Final`
|Max artifact property value size
|`apicurio.limits.config.max-requests-per-second`
|`long`
|`-1`
|`2.2.3.Final`
|Max artifact requests per second
|`apicurio.limits.config.max-schema-size.bytes`
|`long`
|`-1`
|`2.2.3.Final`
|Max schema size (bytes)
|`apicurio.limits.config.max-total-schemas`
|`long`
|`-1`
|`2.1.0.Final`
|Max total schemas
|`apicurio.limits.config.max-versions-per-artifact`
|`long`
|`-1`
|`2.1.0.Final`
|Max versions per artifacts
|`apicurio.storage.metrics.cache.max-size`
|`long`
|`1000`
|`2.4.1.Final`
|Storage metrics cache max size.
|===

== log
.log configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.log.level`
|`string [dynamic]`
|`INFO`
|`3.1.0`
|Dynamic log level for Apicurio Registry
|===

== observability
.observability configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.metrics.rest.enabled`
|`boolean`
|`true`
|`3.1.1`
|        Enable collecting metrics about REST API requests.

|`apicurio.metrics.rest.explicit-status-codes-list`
|`list<string>`
|`401`
|`3.1.1`
|        Only the general category of the HTTP status code is added as a tag/label on REST API request metrics,
        e.g. `1xx`, `2xx`, ...         If you are interested in metrics for a specific status code, e.g. 401 for authentication errors,
        this property allows you to specify a list of such codes.         Each request will be counted only once, i.e. either as the specific status code or in the general category. 
|`apicurio.metrics.rest.method-tag-enabled`
|`boolean`
|`true`
|`3.1.1`
|        Add the HTTP method tag/label on REST API request metrics.         You might disable this tag to reduce metrics cardinality.

|`apicurio.metrics.rest.path-filter-pattern`
|`string`
|`/apis/.*`
|`3.1.1`
|        Only requests with a path matching this pattern (Java syntax) will be considered for metrics collection.         The pattern is applied to the request path only,
        e.g. `curl 'http://localhost:8080/apis/registry/v3/groups/default/artifacts?offset=42&limit=10'`
        will be matched against `/apis/registry/v3/groups/default/artifacts`.

|`apicurio.metrics.rest.path-tag-enabled`
|`boolean`
|`true`
|`3.1.1`
|        Add the unsubstituted path tag/label on REST API request metrics,
        e.g. `/apis/registry/v3/groups/{groupId}/artifacts/{artifactId}`.         You might disable this tag to reduce metrics cardinality.         When an unsubstituted REST API resource path could not be determined,
        the tag value will be `(unspecified)`.

|`quarkus.otel.enabled`
|`boolean`
|`true`
|`3.1.7`
|Enable or disable OpenTelemetry for distributed tracing, metrics export via OTLP, and log correlation. When enabled, {registry} exports telemetry data to an OpenTelemetry collector.
|`quarkus.otel.exporter.otlp.endpoint`
|`string`
|`http://localhost:4317`
|`3.1.7`
|The endpoint URL of the OpenTelemetry collector. Supports both gRPC (port 4317) and HTTP (port 4318) protocols.
|`quarkus.otel.exporter.otlp.protocol`
|`string`
|`grpc`
|`3.1.7`
|The protocol to use for exporting telemetry data. Valid values are `grpc` or `http/protobuf`.
|`quarkus.otel.instrument.kafka`
|`boolean`
|`true`
|`3.1.7`
|Enable or disable automatic tracing instrumentation for Kafka operations. Useful for tracing in KafkaSQL storage deployments.
|`quarkus.otel.logs.enabled`
|`boolean`
|`true`
|`3.1.7`
|BUILD-TIME property to enable log export via OpenTelemetry. When enabled along with JSON logging, trace context is automatically included in log entries. Use `quarkus.otel.sdk.disabled` to control log export at runtime.
|`quarkus.otel.metrics.enabled`
|`boolean`
|`true`
|`3.1.7`
|BUILD-TIME property to enable metrics export via OpenTelemetry. This works alongside existing Prometheus metrics export. Use `quarkus.otel.sdk.disabled` to control metrics at runtime.
|`quarkus.otel.resource.attributes`
|`optional<string>`
|
|`3.1.7`
|Additional resource attributes to include in telemetry data, specified as comma-separated key=value pairs. Example: `service.version=3.0.0,deployment.environment=production`
|`quarkus.otel.sdk.disabled`
|`boolean`
|`true`
|`3.1.7`
|Disable the OpenTelemetry SDK at runtime. Set to `false` to enable OpenTelemetry. This is the primary runtime control for enabling/disabling all telemetry signals.
|`quarkus.otel.service.name`
|`string`
|`apicurio-registry`
|`3.1.7`
|The logical service name for this {registry} instance. This name appears in traces and metrics exported to the OpenTelemetry collector.
|`quarkus.otel.traces.enabled`
|`boolean`
|`true`
|`3.1.7`
|BUILD-TIME property to enable distributed tracing instrumentation. When enabled, {registry} creates spans for REST API requests and storage operations. Use `quarkus.otel.sdk.disabled` to control tracing at runtime.
|`quarkus.otel.traces.sampler`
|`string`
|`parentbased_always_on`
|`3.1.7`
|The sampling strategy for traces. Use `parentbased_always_on` for development or `parentbased_traceidratio` for production to reduce overhead.
|`quarkus.otel.traces.sampler.arg`
|`string`
|`1.0`
|`3.1.7`
|The sampling ratio when using `parentbased_traceidratio` sampler. A value of `0.1` means 10% of traces are sampled.
|===

== redirects
.redirects configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.redirects`
|`map<string, string>`
|
|`2.1.2.Final`
|Registry redirects
|`apicurio.redirects.enabled`
|`boolean`
|
|`2.1.2.Final`
|Enable redirects
|`apicurio.url.override.host`
|`optional<string>`
|
|`2.5.0.Final`
|Override the hostname used for generating externally-accessible URLs. The host and port overrides are useful when deploying Registry with HTTPS passthrough Ingress or Route. In cases like these, the request URL (and port) that is then re-used for redirection does not belong to actual external URL used by the client, because the request is proxied. The redirection then fails because the target URL is not reachable.
|`apicurio.url.override.port`
|`optional<integer>`
|
|`2.5.0.Final`
|Override the port used for generating externally-accessible URLs.
|===

== rest
.rest configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.rest.artifact.references.default-handling`
|`optional<string>`
|
|`3.1.0`
|Optional configuration to override default reference handling behavior. When not set, uses API defaults (PRESERVE for v3, false for v2, none for ccompat).
|`apicurio.rest.deletion.artifact-version.enabled`
|`boolean [dynamic]`
|`false`
|`2.4.2`
|Enables artifact version deletion
|`apicurio.rest.deletion.artifact.enabled`
|`boolean [dynamic]`
|`false`
|`3.0.0`
|Enables artifact deletion
|`apicurio.rest.deletion.group.enabled`
|`boolean [dynamic]`
|`false`
|`3.0.0`
|Enables group deletion
|`apicurio.rest.draft.production-mode.enabled`
|`boolean [dynamic]`
|`false`
|`3.0.x`
|Enables production-like behavior for draft versions
|`apicurio.rest.mutability.artifact-version-content.enabled`
|`boolean [dynamic]`
|`false`
|`3.0.2`
|Enables artifact version mutability
|`apicurio.rest.search-results.labels.max-size.bytes`
|`int`
|`512`
|`3.0.3`
|Max size of the labels (in bytes) per item from within search results
|===

== search
.search configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.search.index.content.max-size`
|`int`
|`1048576`
|`3.2.0`
|Maximum content size (in characters) to index
|`apicurio.search.index.elasticsearch.index-name`
|`string`
|`apicurio-registry`
|`3.2.0`
|Elasticsearch index name
|`apicurio.search.index.elasticsearch.number-of-replicas`
|`int`
|`1`
|`3.2.0`
|Number of Elasticsearch index replicas
|`apicurio.search.index.elasticsearch.number-of-shards`
|`int`
|`1`
|`3.2.0`
|Number of Elasticsearch index shards
|`apicurio.search.index.enabled`
|`boolean`
|`false`
|`3.2.0`
|Enable search indexing _(experimental)_
|===

== semver
.semver configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.semver.branching.coerce`
|`boolean [dynamic]`
|`false`
|`3.0.0`
|If true, invalid versions will be coerced to Semantic Versioning 2 format (https://semver.org) if possible.
|`apicurio.semver.branching.enabled`
|`boolean [dynamic]`
|`false`
|`3.0.0`
|Automatically create or update branches for major ('A.x') and minor ('A.B.x') artifact versions.
|`apicurio.semver.validation.enabled`
|`boolean [dynamic]`
|`false`
|`3.0.0`
|Validate that all artifact versions conform to Semantic Versioning 2 format (https://semver.org).
|===

== storage
.storage configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.datasource.blue.db-kind`
|`string`
|`h2`
|`3.0.0`
|Gitops blue datasource db kind
|`apicurio.datasource.blue.jdbc.initial-size`
|`string`
|`20`
|`3.0.0`
|Gitops blue datasource pool initial size
|`apicurio.datasource.blue.jdbc.max-size`
|`string`
|`100`
|`3.0.0`
|Gitops blue datasource pool max size
|`apicurio.datasource.blue.jdbc.min-size`
|`string`
|`20`
|`3.0.0`
|Gitops blue datasource pool minimum size
|`apicurio.datasource.blue.jdbc.url`
|`string`
|`jdbc:h2:mem:registry_blue`
|`3.0.0`
|Gitops blue datasource jdbc url
|`apicurio.datasource.blue.password`
|`string`
|`sa`
|`3.0.0`
|Gitops blue datasource password
|`apicurio.datasource.blue.username`
|`string`
|`sa`
|`3.0.0`
|Gitops blue datasource username
|`apicurio.datasource.green.db-kind`
|`string`
|`h2`
|`3.0.0`
|Gitops green datasource db kind
|`apicurio.datasource.green.jdbc.initial-size`
|`string`
|`20`
|`3.0.0`
|Gitops green datasource pool initial size
|`apicurio.datasource.green.jdbc.max-size`
|`string`
|`100`
|`3.0.0`
|Gitops green datasource pool max size
|`apicurio.datasource.green.jdbc.min-size`
|`string`
|`20`
|`3.0.0`
|Gitops green datasource pool minimum size
|`apicurio.datasource.green.jdbc.url`
|`string`
|`jdbc:h2:mem:registry_green`
|`3.0.0`
|Gitops green datasource jdbc url
|`apicurio.datasource.green.password`
|`string`
|`sa`
|`3.0.0`
|Gitops green datasource password
|`apicurio.datasource.green.username`
|`string`
|`sa`
|`3.0.0`
|Gitops green datasource username
|`apicurio.events.kafka.topic`
|`string`
|`registry-events`
|`3.0.1`
|Kafka sql storage events topic
|`apicurio.events.kafka.topic.*`
|`map<string, string>`
|
|`3.1.3`
|Kafka sql events topic properties. There is an optional Registry-specific configuration property: 'replication.factor'. IMPORTANT: As a temporary compatibility measure, configuration properties for this topic are also inherited from 'apicurio.kafkasql.topic' unless explicitly overridden by this property. This will be removed in a next minor version.
|`apicurio.kafkasql.bootstrap.servers`
|`string`
|
|
|Kafka sql storage bootstrap servers
|`apicurio.kafkasql.consumer.group-prefix`
|`string`
|`apicurio-`
|
|Kafka sql storage prefix for consumer group name
|`apicurio.kafkasql.consumer.poll.timeout`
|`integer`
|`5000`
|
|Kafka sql storage consumer poll timeout in milliseconds
|`apicurio.kafkasql.coordinator.response-timeout`
|`integer`
|`30000`
|
|Kafka sql storage coordinator response timeout in milliseconds
|`apicurio.kafkasql.security.protocol`
|`optional<string>`
|
|
|Kafka sql storage security protocol
|`apicurio.kafkasql.security.sasl.client-id`
|`string`
|
|
|Kafka sql storage sasl client identifier
|`apicurio.kafkasql.security.sasl.client-secret`
|`string`
|
|
|Kafka sql storage sasl client secret
|`apicurio.kafkasql.security.sasl.enabled`
|`boolean`
|`false`
|
|Kafka sql storage sasl enabled
|`apicurio.kafkasql.security.sasl.login.callback.handler.class`
|`string`
|
|
|Kafka sql storage sasl login callback handler
|`apicurio.kafkasql.security.sasl.mechanism`
|`string`
|
|
|Kafka sql storage sasl mechanism
|`apicurio.kafkasql.security.sasl.token.endpoint`
|`string`
|
|
|Kafka sql storage sasl token endpoint
|`apicurio.kafkasql.security.ssl.key.password`
|`optional<string>`
|
|
|Kafka sql storage ssl key password
|`apicurio.kafkasql.security.ssl.keystore.location`
|`optional<string>`
|
|
|Kafka sql storage ssl keystore location
|`apicurio.kafkasql.security.ssl.keystore.password`
|`optional<string>`
|
|
|Kafka sql storage ssl keystore password
|`apicurio.kafkasql.security.ssl.keystore.type`
|`optional<string>`
|
|
|Kafka sql storage ssl keystore type
|`apicurio.kafkasql.security.ssl.truststore.location`
|`optional<string>`
|
|
|Kafka sql storage ssl truststore location
|`apicurio.kafkasql.security.ssl.truststore.password`
|`optional<string>`
|
|
|Kafka sql storage ssl truststore password
|`apicurio.kafkasql.security.ssl.truststore.type`
|`optional<string>`
|
|
|Kafka sql storage ssl truststore type
|`apicurio.kafkasql.snapshot.every.seconds`
|`string`
|`86400s`
|`3.0.0`
|Kafka sql journal topic snapshot every
|`apicurio.kafkasql.snapshots.topic`
|`string`
|`kafkasql-snapshots`
|`3.0.0`
|Kafka sql snapshots topic name
|`apicurio.kafkasql.snapshots.topic.*`
|`map<string, string>`
|
|`3.1.3`
|Kafka sql snapshots topic properties. There are two optional Registry-specific configuration properties: 'partitions' and 'replication.factor'. IMPORTANT: As a temporary compatibility measure, configuration properties for this topic are also inherited from 'apicurio.kafkasql.topic' unless explicitly overridden by this property. This will be removed in a next minor version.
|`apicurio.kafkasql.ssl.key.password`
|`optional<string>`
|
|
|Kafka sql storage ssl key password (deprecated, use apicurio.kafkasql.security.ssl.key.password)
|`apicurio.kafkasql.ssl.keystore.location`
|`optional<string>`
|
|
|Kafka sql storage ssl keystore location (deprecated, use apicurio.kafkasql.security.ssl.keystore.location)
|`apicurio.kafkasql.ssl.keystore.password`
|`optional<string>`
|
|
|Kafka sql storage ssl keystore password (deprecated, use apicurio.kafkasql.security.ssl.keystore.password)
|`apicurio.kafkasql.ssl.keystore.type`
|`optional<string>`
|
|
|Kafka sql storage ssl keystore type (deprecated, use apicurio.kafkasql.security.ssl.keystore.type)
|`apicurio.kafkasql.ssl.truststore.password`
|`optional<string>`
|
|
|Kafka sql storage ssl truststore password (deprecated, use apicurio.kafkasql.security.ssl.truststore.password)
|`apicurio.kafkasql.topic`
|`string`
|`kafkasql-journal`
|
|Kafka sql storage topic name
|`apicurio.kafkasql.topic-configuration-verification-override-enabled`
|`boolean`
|`false`
|`3.1.3`
|When using KafkaSQL storage, Apicurio Registry verifies that the topic configuration will not cause accidental data loss or corruption. Setting this property to true will partially disable this verification for *all* Apicurio Registry topics. Specifically, 'retention.ms=-1' is not enforced to support automatic cleanup when Apicurio Registry snapshotting feature is used. In this case, snapshots have to be made more frequently than messages are deleted. IMPORTANT: We might change which topics and which verification checks are affected by this configuration property in the future.
|`apicurio.kafkasql.topic.*`
|`map<string, string>`
|
|
|Kafka sql storage topic properties. There are two optional Registry-specific configuration properties: 'partitions' and 'replication.factor'.
|`apicurio.kafkasql.topic.auto-create`
|`boolean`
|`true`
|
|Kafka sql storage topic auto create
|`apicurio.polling-storage.debounce.max-wait-period`
|`duration`
|`PT90S`
|`3.2.0`
|Maximum time to wait for changes to settle before forcing a load. Prevents indefinite delay when changes keep arriving. Set to PT0S for no maximum. _(experimental)_
|`apicurio.polling-storage.debounce.quiet-period`
|`duration`
|`PT30S`
|`3.2.0`
|After detecting a change, wait until no new changes are seen for this duration before loading data. Absorbs rapid successive pushes. Set to PT0S to disable debouncing. _(experimental)_
|`apicurio.polling-storage.deterministic-ids-enabled`
|`boolean`
|`true`
|`3.2.0`
|When enabled, contentId and globalId are deterministically generated from content hashes and artifact coordinates if not explicitly specified. When disabled, missing IDs cause an error. Generated IDs use the upper half of positive longs (above Long.MAX_VALUE/2), leaving the lower half for user-specified IDs. _(experimental)_
|`apicurio.polling-storage.file-suffixes`
|`list<string>`
|`registry,ar`
|`3.2.0`
|Comma-separated list of file suffixes that identify registry metadata files. Each suffix is combined with supported extensions (.yaml, .yml, .json) to form the full pattern. For example, suffix "registry" matches *.registry.yaml, *.registry.yml, and *.registry.json. _(experimental)_
|`apicurio.polling-storage.id`
|`string`
|`main`
|`3.2.0`
|Identifier of this Registry instance. Only data that references this identifier will be loaded. _(experimental)_
|`apicurio.polling-storage.poll-period`
|`duration`
|`PT10S`
|`3.2.0`
|Minimum period between data source polls. The actual poll (reading from Git or Kubernetes) only happens when at least this much time has passed since the last poll. _(experimental)_
|`apicurio.polling-storage.require-registry-config`
|`boolean`
|`true`
|`3.2.0`
|When enabled, a load is rejected if the data source does not contain a registry configuration file matching the configured registry ID. This prevents accidental data loss from force-pushes or empty branches. To intentionally clear all data, first push a commit with only the registry configuration file (no artifacts), then remove it. _(experimental)_
|`apicurio.sql.db-schema`
|`string`
|`*`
|`3.0.6`
|Database schema name (only needed when running two instances of Registry against the same database, in multiple schemas)
|`apicurio.sql.init`
|`boolean`
|`true`
|`2.0.0.Final`
|SQL init
|`apicurio.storage.connection.retry.backoff-multiplier`
|`double`
|`2.0`
|`3.1.4`
|Multiplier for exponential backoff between retry attempts
|`apicurio.storage.connection.retry.enabled`
|`boolean`
|`true`
|`3.1.4`
|Enable connection retry with exponential backoff for transient database connection failures
|`apicurio.storage.connection.retry.initial-delay-ms`
|`long`
|`1000`
|`3.1.4`
|Initial delay in milliseconds before first retry
|`apicurio.storage.connection.retry.max-attempts`
|`int`
|`10`
|`3.1.4`
|Maximum number of connection retry attempts
|`apicurio.storage.connection.retry.max-delay-ms`
|`long`
|`30000`
|`3.1.4`
|Maximum delay in milliseconds between retry attempts
|`apicurio.storage.enable-automatic-group-creation`
|`boolean`
|`true`
|`3.0.15`
|Enable automatic creation of group when creating an artifact
|`apicurio.storage.kind`
|`string`
|
|`3.0.0`
|Application storage variant, for example, sql, kafkasql, gitops, or kubernetesops
|`apicurio.storage.read-only.enabled`
|`boolean [dynamic]`
|`false`
|`3.0.0`
|Enable Registry storage read-only mode
|`apicurio.storage.references.max-depth`
|`int`
|`100`
|`3.0.6`
|Maximum recursion depth for resolving schema references. Prevents stack overflow from deeply nested schemas.
|`apicurio.storage.snapshot.location`
|`string`
|`./`
|`3.0.0`
|Kafka sql snapshots store location
|`apicurio.storage.sql.kind`
|`string`
|`h2`
|`3.0.0`
|Application datasource database type
|`artifacts.skip.disabled.latest`
|`boolean`
|`true`
|`2.4.2`
|Skip artifact versions with DISABLED state when retrieving latest artifact version
|===

== system
.system configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.app.date`
|`string`
|
|`3.0.4`
|
|`apicurio.app.description`
|`string`
|
|`3.0.4`
|
|`apicurio.app.name`
|`string`
|
|`3.0.4`
|
|`apicurio.app.version`
|`string`
|
|`3.0.4`
|
|`apicurio.features.experimental.enabled`
|`boolean`
|`false`
|`3.2.0`
|Enable experimental features. When disabled, any experimental feature that is individually enabled will prevent the application from starting.
|===

== types
.types configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.artifact-types.config-file`
|`string`
|`/tmp/apicurio-registry-artifact-types.json`
|`3.1.0`
|Path to a configuration file containing a list of supported artifact types.
|===

== ui
.ui configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.app.context-path`
|`string`
|`/`
|`3.1.0`
|Context path for application (useful when behind a proxy)
|`apicurio.ui.auth.oidc.client-id`
|`string`
|`apicurio-registry-ui`
|`3.0.0`
|The OIDC clientId
|`apicurio.ui.auth.oidc.load-user-info`
|`optional<boolean>`
|
|`3.1.6`
|Whether to load user info from the OIDC userinfo endpoint. Defaults to true if not specified. Set to false for OIDC providers like Azure Entra ID where the userinfo endpoint has incompatible audience requirements.
|`apicurio.ui.auth.oidc.logout-url`
|`string`
|`f5`
|`3.0.0`
|The OIDC logout URL
|`apicurio.ui.auth.oidc.redirect-uri`
|`optional<string>`
|
|`3.0.0`
|The OIDC redirectUri
|`apicurio.ui.auth.oidc.scope`
|`string`
|`openid profile email`
|`3.0.8`
|UI auth OIDC scope value
|`apicurio.ui.contextPath`
|`string`
|`/`
|`3.0.0`
|Context path of the UI
|`apicurio.ui.docsUrl`
|`string`
|`/docs/`
|`3.0.0`
|URL of the Documentation component
|`apicurio.ui.editorsUrl`
|`string`
|`/editors/`
|`3.1.0`
|URL of the Editors component
|`apicurio.ui.features.agents.enabled`
|`boolean [dynamic]`
|`false`
|`3.2.0`
|Enabled to show the Agents tab in the UI _(experimental)_
|`apicurio.ui.features.breadcrumbs`
|`string`
|`true`
|`3.0.0`
|Enabled to show breadcrumbs in the UI
|`apicurio.ui.features.read-only.enabled`
|`string`
|`false`
|`3.0.0`
|Enabled to set the UI to read-only mode
|`apicurio.ui.features.settings`
|`string`
|`true`
|`3.0.0`
|Enabled to show the Settings tab in the UI
|`apicurio.ui.navPrefixPath`
|`string`
|`/`
|`3.0.0`
|Navigation prefix for all UI paths
|===

== unknown
.unknown configuration options
[.table-expandable,width="100%",cols="6,3,2,3,5",options="header"]
|===
|Name
|Type
|Default
|Available from
|Description
|`apicurio.app.id`
|`unknown`
|`apicurio-registry`
|
|
|`apicurio.auth.anonymous-read-access.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.auth.owner-only-authorization.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.auth.owner-only-authorization.limit-group-access.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.authn.basic-client-credentials.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.ccompat.legacy-id-mode.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.ccompat.max-subjects.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.ccompat.use-canonical-hash.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.config.dynamic.allow-all`
|`unknown`
|`true`
|
|
|`apicurio.config.refresh.every`
|`unknown`
|`1m`
|
|
|`apicurio.datasource.jdbc.initial-size`
|`unknown`
|`20`
|
|
|`apicurio.datasource.jdbc.max-size`
|`unknown`
|`100`
|
|
|`apicurio.datasource.jdbc.min-size`
|`unknown`
|`20`
|
|
|`apicurio.datasource.password`
|`unknown`
|`sa`
|
|
|`apicurio.datasource.url`
|`unknown`
|`jdbc:h2:mem:db_${quarkus.uuid}`
|
|
|`apicurio.datasource.username`
|`unknown`
|`sa`
|
|
|`apicurio.download.href.ttl.seconds.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.downloads.reaper.every`
|`unknown`
|`60s`
|
|
|`apicurio.kafkasql.producer.client.id`
|`unknown`
|`${registry.id}-producer`
|
|
|`apicurio.limits.config.cache.check-period`
|`unknown`
|`30000`
|
|
|`apicurio.log.level.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.logconfigjob.delayed`
|`unknown`
|`1s`
|
|
|`apicurio.logconfigjob.every`
|`unknown`
|`5s`
|
|
|`apicurio.redirects.root`
|`unknown`
|`/,/apis`
|
|
|`apicurio.rest.artifact.deletion.enabled`
|`unknown`
|`false`
|
|
|`apicurio.rest.deletion.artifact-version.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.rest.deletion.artifact.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.rest.deletion.group.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.rest.draft.production-mode.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.rest.mutability.artifact-version-content.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.semver.branching.coerce.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.semver.branching.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.semver.validation.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.storage.orphan-cleanup.every`
|`unknown`
|`1h`
|
|
|`apicurio.storage.read-only.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.ui.features.agents.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|`apicurio.ui.features.read-only.enabled.dynamic.allow`
|`unknown`
|`${apicurio.config.dynamic.allow-all}`
|
|
|===

