// 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_TOKEN_ENDPOINT`
|`apicurio.registry.auth.service.token.endpoint`
|Used by serializers and deserializers. URL of the token endpoint.
|`String`
|None
|`AUTH_CLIENT_ID`
|`apicurio.registry.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.registry.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.registry.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.registy.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`
|`DEREFERENCE_SCHEMA`
|`apicurio.registry.dereference-schema`
|Used to indicate the serdes to dereference the schema. This is used in two different situation, once the schema is registered, instructs the serdes to ask the server for the schema dereferenced. It is also used to instruct the serializer to dereference the schema before registering it Registry, but this is only supported for Avro.
|`boolean`
|`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`
|`contentId`
|===

[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`
|`false`
|`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. Default to a 4 byte format that includes the contentId in the message payload.
|`String`
|`io.apicurio.registry.serde.Default4ByteIdHandler`
|===

[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/generic/serde-common/src/main/java/io/apicurio/registry/serde/config/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].
