schemaregistry.jikkou.io/normalize-schema doesn't change schema registry settings and results in an endless update loop

[teebee]

Describe the bug
The description of the annotation schemaregistry.jikkou.io/normalize-schema indicates that it can be used to normalize the schema on schema registry server side. However, it only seems to have an influence on whether jikkou itself normalizes a schema before registration or not. Is the description inaccurate or is jikkou's behavior flawed?

If the annotation is only intended to control the behavior of jikkou, I suggest extending the specification with another normalize attribute, which sets the corresponding configuration at the subject level - similar to how the compatibilityLevel is handled.

In addition, the annotation schemaregistry.jikkou.io/normalize-schema: true gets you into an endless update loop.

To Reproduce

Jikkou configuration:

$ cat ~/.jikkou/config
{
  "currentContext": "default",
  "default": {
    "configFile": null,
    "configProps": {
      "kafka.bootstrap.servers": "localhost:9092",
      "schemaregistry.url": "http://localhost:8081"
    }
  }
}

Sample subject configuration:

$ cat sample.yml
---
apiVersion: schemaregistry.jikkou.io/v1beta2
kind: SchemaRegistrySubject
metadata:
  name: sample
  annotations:
    schemaregistry.jikkou.io/normalize-schema: true
spec:
  compatibilityLevel: NONE
  schemaType: AVRO
  schema: '{"doc":"","namespace":"example.avro","type":"record","name":"User","fields":[{"name":"name","type":["null","string"],"default":null}]}'

Empty schema registry:

$ curl -s http:/localhost:8081/subjects | jq .
[]

Run jikkou:

$ jikkou apply -f sample.yml
TASK [CREATE] Create subject 'sample' (type=CREATE, compatibilityLevel=NONE) - CHANGED ******************
{
  "end" : "2025-11-21T19:55:48.881518Z",
  "status" : "CHANGED",
  "description" : "Create subject 'sample' (type=CREATE, compatibilityLevel=NONE)",
  "change" : {
    "apiVersion" : "schemaregistry.jikkou.io/v1beta2",
    "kind" : "SchemaRegistrySubjectChange",
    "metadata" : {
      "name" : "sample",
      "labels" : { },
      "annotations" : {
        "schemaregistry.jikkou.io/normalize-schema" : true,
        "jikkou.io/managed-by-location" : "sample.yml"
      }
    },
    "spec" : {
      "changes" : [ {
        "name" : "schema",
        "op" : "CREATE",
        "after" : "{\"doc\":\"\",\"fields\":[{\"default\":null,\"name\":\"name\",\"type\":[\"null\",\"string\"]}],\"name\":\"User\",\"namespace\":\"example.avro\",\"type\":\"record\"}"
      }, {
        "name" : "schemaType",
        "op" : "CREATE",
        "after" : "AVRO"
      }, {
        "name" : "references",
        "op" : "CREATE",
        "after" : [ ]
      }, {
        "name" : "compatibilityLevel",
        "op" : "CREATE",
        "after" : "NONE"
      } ],
      "op" : "CREATE",
      "data" : {
        "normalizeSchema" : true,
        "permanentDelete" : false
      }
    }
  },
  "failed" : false,
  "changed" : true
}
EXECUTION in 391ms
ok : 0, created : 1, altered : 0, deleted : 0 failed : 0

Check subject configuration:

$ curl -s http:/localhost:8081/config/sample | jq .
{
  "compatibilityLevel": "NONE"
}

Note that normalize: true is missing!

Check if the schema has been registered:

$ curl -s http:/localhost:8081/schemas | jq .
[
  {
    "subject": "sample",
    "version": 1,
    "id": 1,
    "guid": "e8392590-1b30-071e-1e47-929267400f94",
    "schemaType": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"User\",\"namespace\":\"example.avro\",\"fields\":[{\"name\":\"name\",\"type\":[\"null\",\"string\"],\"default\":null}]}"
  }
]

Note that jikkou still means that an update is required:

$ jikkou apply -f sample.yml
TASK [UPDATE] Update subject 'sample' (type=UPDATE, compatibilityLevel=NONE) - CHANGED ******************
{
  "end" : "2025-11-21T20:02:09.001952Z",
  "status" : "CHANGED",
  "description" : "Update subject 'sample' (type=UPDATE, compatibilityLevel=NONE)",
  "change" : {
    "apiVersion" : "schemaregistry.jikkou.io/v1beta2",
    "kind" : "SchemaRegistrySubjectChange",
    "metadata" : {
      "name" : "sample",
      "labels" : { },
      "annotations" : {
        "schemaregistry.jikkou.io/normalize-schema" : true,
        "jikkou.io/managed-by-location" : "sample.yml"
      }
    },
    "spec" : {
      "changes" : [ {
        "name" : "compatibilityLevel",
        "op" : "NONE",
        "before" : "NONE",
        "after" : "NONE"
      }, {
        "name" : "schema",
        "op" : "UPDATE",
        "before" : "{\n  \"type\" : \"record\",\n  \"name\" : \"User\",\n  \"namespace\" : \"example.avro\",\n  \"fields\" : [ {\n    \"name\" : \"name\",\n    \"type\" : [ \"null\", \"string\" ],\n    \"default\" : null\n  } ]\n}",
        "after" : "{\"doc\":\"\",\"fields\":[{\"default\":null,\"name\":\"name\",\"type\":[\"null\",\"string\"]}],\"name\":\"User\",\"namespace\":\"example.avro\",\"type\":\"record\"}"
      }, {
        "name" : "schemaType",
        "op" : "NONE",
        "before" : "AVRO",
        "after" : "AVRO"
      }, {
        "name" : "references",
        "op" : "NONE",
        "before" : [ ],
        "after" : [ ]
      } ],
      "op" : "UPDATE",
      "data" : {
        "normalizeSchema" : true,
        "permanentDelete" : false
      }
    }
  },
  "failed" : false,
  "changed" : true
}
EXECUTION in 161ms
ok : 0, created : 0, altered : 1, deleted : 0 failed : 0

Expected behavior
Either the description of the annotation schemaregistry.jikkou.io/normalize-schema needs to be made clearer, or the behavior of jikkou needs to be fixed. In addition, jikkou should never get into an endless update loop.

If the annotation is only for controlling the behavior of jikkou, spec.normalize should be introduced.

Screenshots/Configs
If applicable, add screenshots to help explain your problem.

Runtime environment

• OS: Ubuntu 24.04.3 LTS
• Jikkou: Jikkou version "0.36.4" 2025-10-08, JVM: 21.0.2 (GraalVM Community Substrate VM 21.0.2+13)
• Docker version: Docker version 28.2.2, build 28.2.2-0ubuntu1~24.04.1
• Kafka Cluster Version: confluentinc/cp-kafka:8.0.0, confluentinc/cp-schema-registry:8.0.0

Additional context
Add any other context about the problem here.

[teebee]

The log entry POST /subjects/sample/versions?normalize=true HTTP/1.1 of the schema registry shows that the annotation schemaregistry.jikkou.io/normalize-schema affects the request to register the schema. In this respect, normalization is actually done by the schema registry as described, just not by changing the configuration of the schema register (at the subject level).

So, I would like to ask to make the documentation a bit clearer and to fix the endless update loop in the case of schemaregistry.jikkou.io/normalize-schema: true when registering a schema that is not already normalized.

And I would very much appreciate it if subject level normalization would be made configurable via jikkou. For instance like this:

---
apiVersion: schemaregistry.jikkou.io/v1beta2
kind: SchemaRegistrySubject
metadata:
  name: sample
spec:
  compatibilityLevel: NONE

  normalize: true

  schemaType: AVRO
  schema: '{"doc":"","namespace":"example.avro","type":"record","name":"User","fields":[{"name":"name","type":["null","string"],"default":null}]}'

[fhussonnois]

Hi @teebee Thank you very much for opening this issue and for the detailed explanation. You’re right: the schemaregistr,y.jikkou.io/normalize-schema property is not well enough documented. As you mentioned, this property is only sent to the Schema Registry to ask the server to perform normalization as described in the Confluent documentation.

However, it has no impact on Jikkou’s own normalization behavior, which is now controlled by the provider property normalizeSchemasEnabled (default: true), e.g.,

jikkou  {
  provider.schemaregistry {
    enabled = true
    type = io.streamthoughts.jikkou.schema.registry.SchemaRegistryExtensionProvider
    config = {
      normalizeSchemasEnabled = true
    }
  }
}

In addition, when using Avro schemas, it may be more appropriate to use the schemaregistry.jikkou.io/use-canonical-fingerprint annotation to adjust how schemas are compared.

I will try to reproduce your issue and evaluate your proposal to add the normalize field at the spec level.