> For the complete documentation index, see [llms.txt](https://docs.lenses.io/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lenses.io/latest/k2k/configuration-reference/schema-migration.md).

# Schema migration

Replicate schemas to the target Schema Registry.

{% hint style="info" %}
This feature is **disabled by default**. Set the corresponding `features` toggle to `enabled` in your pipeline file for the behavior described on this page to take effect.
{% endhint %}

{% hint style="warning" %}
**This feature requires a license.** It is unavailable in free tier mode, and the license token must carry the matching entitlement. Enabling it with a token that does not cover it fails the pipeline at startup with a license restriction error.

See [Licensed features](https://github.com/lensesio-dev/k2k-documentation/tree/release/2.1.0/.gitbook/includes/licenses.md#licensed-features).
{% endhint %}

Avro, Protobuf, and JSON Schema records depend on subjects registered in Schema Registry. A consumer on the target Kafka cluster cannot deserialize replicated data unless the same schemas exist on the target Schema Registry. Schema replication must keep pace with data replication.

Enable `features.schemaMapping` to copy schemas referenced by replicated records. Configure `source.registry` and `target.registry` under [Schema Registry connectivity and authentication](https://docs.lenses.io/latest/k2k/configuration-reference/schema-registry-connectivity-authentication.md). Limit schema replication with `schemaMappings.topics` if needed. For supported types and registry caches, see the [Advanced](#advanced) section below.

## Prerequisites

* [License accepted](https://docs.lenses.io/latest/k2k/configuration-reference/licenses.md)
* [Kafka connectivity and authentication](https://docs.lenses.io/latest/k2k/configuration-reference/kafka-connectivity-authentication.md) configured
* [Schema Registry connectivity and authentication](https://docs.lenses.io/latest/k2k/configuration-reference/schema-registry-connectivity-authentication.md) configured
* [Topic selection and data routing](https://docs.lenses.io/latest/k2k/configuration-reference/topic-selection-and-data-routing.md) configured

## Example

Use the following pipeline configuration:

```yaml
name: "my_pipeline"
features:
  schemaMapping: enabled
source:
  kafka:
    common:
      "bootstrap.servers": "source:9092"
    consumer:
      "group.id": "my-k2k-group"
  registry:
    config:
      "schema.registry.url": "http://source-sr:8081"
target:
  kafka:
    common:
      "bootstrap.servers": "target:9092"
  registry:
    config:
      "schema.registry.url": "http://target-sr:8081"
schemaMappings:
  topics:
    - pattern: "orders.*"
      key: enabled
      value: enabled
replication:
  - source:
      topic: "orders.*"
  - sink:
      topic: source
      partition: source
```

## Configuration keys

### Feature toggle

| Key                      | Description                                     | Required | Default    | Used by    |
| ------------------------ | ----------------------------------------------- | -------- | ---------- | ---------- |
| `features.schemaMapping` | Replicate schemas to the target Schema Registry | No       | `disabled` | Replicator |

### Schema Registry connections

| Key                      | Description                       | Required    | Default | Used by    |
| ------------------------ | --------------------------------- | ----------- | ------- | ---------- |
| `source.registry`        | Source Schema Registry connection | Conditional | (none)  | Replicator |
| `source.registry.config` | Schema Registry client properties | Conditional | `{}`    | Replicator |
| `target.registry`        | Target Schema Registry connection | Conditional | (none)  | Replicator |
| `target.registry.config` | Schema Registry client properties | Conditional | `{}`    | Replicator |

### schemaMappings

| Key                               | Description                                   | Required | Default   | Used by    |
| --------------------------------- | --------------------------------------------- | -------- | --------- | ---------- |
| `schemaMappings.topics[].pattern` | Regex selecting topics this rule applies to   | No       | `.*`      | Replicator |
| `schemaMappings.topics[].key`     | Replicate schemas referenced by record keys   | No       | `enabled` | Replicator |
| `schemaMappings.topics[].value`   | Replicate schemas referenced by record values | No       | `enabled` | Replicator |

## Schema Registry client properties

Any standard Schema Registry client property can be set under `registry.config`, prefixed with `schema.registry` (for example `schema.registry.url`). For the full property list, see the [Schema Registry client configuration reference](https://docs.confluent.io/platform/current/schema-registry/sr-client-configs.html#configuration-reference-for-sr-clients-on-product).

Commonly used keys:

| Key                                             | Description                                           |
| ----------------------------------------------- | ----------------------------------------------------- |
| `schema.registry.url`                           | Schema Registry URL                                   |
| `schema.registry.basic.auth.credentials.source` | Basic auth source (`USER_INFO`, `SASL_INHERIT`, etc.) |
| `schema.registry.basic.auth.user.info`          | Credentials as `user:password`                        |
| `schema.registry.ssl.truststore.location`       | Truststore path for TLS                               |
| `schema.registry.ssl.truststore.password`       | Truststore password                                   |

## Advanced

### Supported schema types

Add custom schema types to `supportedTypes` if your Schema Registry uses formats not in the default list.

| Key                             | Description                    | Required | Default                            | Used by    |
| ------------------------------- | ------------------------------ | -------- | ---------------------------------- | ---------- |
| `schemaMappings.supportedTypes` | Schema types K2K can replicate | No       | `AVRO`, `JSON`, `PROTOBUF`, `YANG` | Replicator |

### Registry caches

K2K caches schemas locally to reduce Schema Registry round trips.

| Key                         | Description                                       | Required | Default | Used by    |
| --------------------------- | ------------------------------------------------- | -------- | ------- | ---------- |
| `source.registry.cacheSize` | Maximum schemas cached locally on the source side | No       | `31`    | Replicator |
| `target.registry.cacheSize` | Maximum schemas cached locally on the target side | No       | `31`    | Replicator |

For custom HTTP headers on Schema Registry requests, see [Schema Registry connectivity and authentication](https://docs.lenses.io/latest/k2k/configuration-reference/schema-registry-connectivity-authentication.md#schema-registry-headers).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lenses.io/latest/k2k/configuration-reference/schema-migration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
