// Metadata created by nebel
// ParentAssemblies: assemblies/getting-started/as_registry-reference.adoc

[id="registry-serdes-config-props_{context}"]
= {registry} serializer/deserializer configuration properties

[role="_abstract"]
This section provides reference information on Java configuration properties for {registry} Kafka serializers/deserializers (SerDes).

[discrete]
== SchemaResolver interface

{registry} SerDes are based on the `SchemaResolver` interface, which abstracts access to the registry and applies the same lookup logic for the SerDes classes of all supported formats.

.Configuration property for SchemaResolver interface
[.table-expandable,width="100%",cols="5,5,5,3,5",options="header"]
|===
|Constant
|Property
|Description
|Type
|Default
|`SCHEMA_RESOLVER`
|`apicurio.registry.schema-resolver`
|Used by serializers and deserializers. Fully-qualified Java classname that implements `SchemaResolver`.
|String
|`io.apicurio.registry.resolver.DefaultSchemaResolver`
|===

NOTE: The `DefaultSchemaResolver` is recommended and provides useful features for most use cases.
For some advanced use cases, you might use a custom implementation of `SchemaResolver`.

[discrete]
== DefaultSchemaResolver class

You can use the `DefaultSchemaResolver` to configure features such as:

* Access to the registry API
* How to look up artifacts in the registry
* How to write and read artifact information to and from Kafka
* Fall-back options for deserializers

[discrete]
=== Configuration for registry API access options

The `DefaultSchemaResolver` provides the following properties to configure access to the core registry API:

.Configuration properties for access to registry API
[.table-expandable,width="100%",cols="4,5,5,3,2",options="header"]
|===
|Constant
|Property
|Description
|Type
|Default
|`REGISTRY_URL`
|`apicurio.registry.url`
|Used by serializers and deserializers. URL to access the registry API.
|`String`
|None
|`AUTH_SERVICE_URL`
|`apicurio.auth.service.url`
|Used by serializers and deserializers. URL of the authentication service. Required when accessing a secure registry using the OAuth client credentials flow.
|`String`
|None
|`AUTH_TOKEN_ENDPOINT`
|`apicurio.auth.service.token.endpoint`
|Used by serializers and deserializers. URL of the token endpoint. Required when accessing a secure registry and `AUTH_SERVICE_URL` is not specified.
|`String`
|None
|`AUTH_REALM`
|`apicurio.auth.realm`
|Used by serializers and deserializers. Realm to access the authentication service. Required when accessing a secure registry using the OAuth client credentials flow.
|`String`
|None
|`AUTH_CLIENT_ID`
|`apicurio.auth.client.id`
|Used by serializers and deserializers. Client ID to access the authentication service. Required when accessing a secure registry using the OAuth client credentials flow.
|`String`
|None
|`AUTH_CLIENT_SECRET`
|`apicurio.auth.client.secret`
|Used by serializers and deserializers. Client secret to access the authentication service. Required when accessing a secure registry using the OAuth client credentials flow.
|`String`
|None
|`AUTH_USERNAME`
|`apicurio.auth.username`
|Used by serializers and deserializers. Username to access the registry. Required when accessing a secure registry using HTTP basic authentication.
|`String`
|None
|`AUTH_PASSWORD`
|`apicurio.auth.password`
|Used by serializers and deserializers. Password to access the registry. Required when accessing a secure registry using HTTP basic authentication.
|`String`
|None
|===

[discrete]
=== Configuration for registry lookup options

The `DefaultSchemaResolver` uses the following properties to configure how to look up artifacts in {registry}.

.Configuration properties for registry artifact lookup
[.table-expandable,width="100%",cols="5,5,5,3,4",options="header"]
|===
|Constant
|Property
|Description
|Type
|Default
|`ARTIFACT_RESOLVER_STRATEGY`
|`apicurio.registry.artifact-resolver-strategy`
|Used by serializers only. Fully-qualified Java classname that implements `ArtifactReferenceResolverStrategy` and maps each Kafka message to an `ArtifactReference` (`groupId`, `artifactId`, and version).  For example, the default strategy uses the topic name as the schema `artifactId`.
|`String`
|`io.apicurio.registry.serde.strategy.TopicIdStrategy`
|`EXPLICIT_ARTIFACT_GROUP_ID`
|`apicurio.registry.artifact.group-id`
|Used by serializers only. Sets the `groupId` used for querying or creating an artifact. Overrides the `groupId` returned by the `ArtifactResolverStrategy`.
|`String`
|None
|`EXPLICIT_ARTIFACT_ID`
|`apicurio.registry.artifact.artifact-id`
|Used by serializers only. Sets the `artifactId` used for querying or creating an artifact. Overrides the `artifactId` returned by the `ArtifactResolverStrategy`.
|`String`
|None
|`EXPLICIT_ARTIFACT_VERSION`
|`apicurio.registry.artifact.version`
|Used by serializers only. Sets the artifact version used for querying or creating an artifact. Overrides the version returned by the `ArtifactResolverStrategy`.
|`String`
|None
|`FIND_LATEST_ARTIFACT`
|`apicurio.registry.find-latest`
|Used by serializers only. Specifies whether the serializer tries to find the latest artifact in the registry for the corresponding group ID and artifact ID.
|`boolean`
|`false`
|`AUTO_REGISTER_ARTIFACT`
|`apicurio.registry.auto-register`
|Used by serializers only. Specifies whether the serializer tries to create an artifact in the registry. The JSON Schema serializer does not support this feature.
|`boolean, boolean String`
|`false`
|`AUTO_REGISTER_ARTIFACT_IF_EXISTS`
|`apicurio.registry.auto-register.if-exists`
|Used by serializers only. Configures the behavior of the client when there is a conflict creating an artifact because the artifact already exists. Available values are `FAIL`, `UPDATE`, `RETURN`, or `RETURN_OR_UPDATE`.
|`String`
|`RETURN_OR_UPDATE`
|`CHECK_PERIOD_MS`
|`apicurio.registry.check-period-ms`
|Used by serializers and deserializers. Specifies how long to cache artifacts before auto-eviction (milliseconds). If set to zero, artifacts are fetched every time.
|`java.time.Duration, non-negative Number, or integer String`
|`30000`
|`RETRY_BACKOFF_MS`
|`apicurio.registry.retry-backoff-ms`
|Used by serializers and deserializers. If a schema can not be be retrieved from the Registry, it may retry a number of times. This configuration option controls the delay between the retry attempts (milliseconds).
|`java.time.Duration, non-negative Number, or integer String`
|`300`
|`RETRY_COUNT`
|`apicurio.registry.retry-count`
|Used by serializers and deserializers. If a schema can not be be retrieved from the Registry, it may retry a number of times. This configuration option controls the number of retry attempts.
|`non-negative Number, or integer String`
|`3`
|`USE_ID`
|`apicurio.registry.use-id`
|Used by serializers and deserializers. Configures to use the specified `IdOption` as the identifier for artifacts. Options are `globalId` and `contentId`. Instructs the serializer to write the specified ID to Kafka, and instructs the deserializer to use this ID to find the schema.
|`String`
|`globalId`
|===

[discrete]
=== Configuration to read/write registry artifacts in Kafka

The `DefaultSchemaResolver` uses the following properties to configure how artifact information is written to and read from Kafka.

.Configuration properties to read/write artifact information in Kafka
[.table-expandable,width="100%",cols="5,5,5,3,5",options="header"]
|===
|Constant
|Property
|Description
|Type
|Default
|`ENABLE_HEADERS`
|`apicurio.registry.headers.enabled`
|Used by serializers and deserializers. Configures to read/write the artifact identifier to Kafka message headers instead of in the message payload.
|`boolean`
|`true`
|`HEADERS_HANDLER`
|`apicurio.registry.headers.handler`
|Used by serializers and deserializers. Fully-qualified Java classname that implements `HeadersHandler` and writes/reads the artifact identifier to/from the Kafka message headers.
|`String`
|`io.apicurio.registry.serde.headers.DefaultHeadersHandler`
|`ID_HANDLER`
|`apicurio.registry.id-handler`
|Used by serializers and deserializers. Fully-qualified Java classname of a class that implements `IdHandler` and writes/reads the artifact identifier to/from the message payload. Only used if `apicurio.registry.headers.enabled` is set to `false`.
|`String`
|`io.apicurio.registry.serde.DefaultIdHandler`
|`ENABLE_CONFLUENT_ID_HANDLER`
|`apicurio.registry.as-confluent`
|Used by serializers and deserializers. Shortcut for enabling the legacy Confluent-compatible implementation of `IdHandler`. Only used if `apicurio.registry.headers.enabled` is set to `false`.
|`boolean`
|`false`
|===

[discrete]
=== Configuration for deserializer fall-back options

The `DefaultSchemaResolver` uses the following property to configure a fall-back provider for all deserializers.

.Configuration property for deserializer fall-back provider
[.table-expandable,width="100%",cols="5,5,5,3,5",options="header"]
|===
|Constant
|Property
|Description
|Type
|Default
|`FALLBACK_ARTIFACT_PROVIDER`
|`apicurio.registry.fallback.provider`
|Only used by deserializers. Sets a custom implementation of `FallbackArtifactProvider` for resolving the artifact used for deserialization. `FallbackArtifactProvider` configures a fallback artifact to fetch from the registry in case the lookup fails.
|`String`
|`io.apicurio.registry.serde.fallback.DefaultFallbackArtifactProvider`
|===

The `DefaultFallbackArtifactProvider` uses the following properties to configure deserializer fall-back options:

.Configuration properties for deserializer fall-back options
[.table-expandable,width="100%",cols="5,5,5,3,2",options="header"]
|===
|Constant
|Property
|Description
|Type
|Default
|`FALLBACK_ARTIFACT_ID`
|`apicurio.registry.fallback.artifact-id`
|Used by deserializers only. Sets the `artifactId` used as fallback for resolving the artifact used for deserialization.
|`String`
|None
|`FALLBACK_ARTIFACT_GROUP_ID`
|`apicurio.registry.fallback.group-id`
|Used by deserializers only. Sets the `groupId` used as fallback for resolving the group used for deserialization.
|`String`
|None
|`FALLBACK_ARTIFACT_VERSION`
|`apicurio.registry.fallback.version`
|Used by deserializers only. Sets the version used as fallback for resolving the artifact used for deserialization.
|`String`
|None
|===

.Additional resources
* For more details, see the link:https://github.com/Apicurio/apicurio-registry/blob/main/serdes/serde-common/src/main/java/io/apicurio/registry/serde/SerdeConfig.java[SerdeConfig Java class].
* You can configure application properties as Java system properties or include them in the Quarkus
`application.properties` file.
For more details, see the https://quarkus.io/guides/config#overriding-properties-at-runtime[Quarkus documentation].
