Motivation

In Pulsar 2.1, SchemaType.JSON was standardized to use Apache Avro schema format for SchemaInfo.schema. However, the broker-side fallback logic (StructSchemaDataValidator and JsonSchemaCompatibilityCheck) is too lenient — it accepts any valid JSON as a schema definition, not just the legacy Jackson format from the 2.0 era.

This has caused real issues for non-Java clients (e.g., Rust) where users accidentally register JSON Schema Draft 2020-12 definitions. The broker accepts them, but Java consumers fail with SchemaParseException: Type not supported: object because AvroBaseStructSchema requires Avro format with no fallback.

Changes

This PIP proposes:

• Add schemaJsonAllowLegacyJacksonFormat broker config (default false) to control whether the old Jackson JSON Schema format is accepted
• When disabled (default), both StructSchemaDataValidator and JsonSchemaCompatibilityCheck strictly require valid Avro schema format, consistent with consumer-side requirements
• When enabled, the current backward-compatible behavior is preserved
• Deprecate (not remove) the ProducerImpl client-side code that sends old format to pre-v13 brokers

Impact

• The legacy format has been superseded since Pulsar 2.1 (2018)
• Java producers are unaffected (JSONSchema.of() has generated Avro format since 2.1)
• Non-Java clients get a clear error at registration time instead of a confusing consumer-side failure
• Users with genuine legacy schemas can opt in via the configuration flag

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

🤖 Generated with Claude Code