Phase 72.5.1.9 adds @v2/telemetry-schema-migrations, the additive schema
migration tooling used before new telemetry event types or optional payload
fields reach emitters.
Compatibility Policy#
createTelemetrySchemaMigrationPlan and validateTelemetrySchemaMigrationPlan
enforce the v2-telemetry-schema-migrations-additive-v1 policy. Minor and patch
updates may add event types, add optional fields, deprecate fields, or document
fields. Breaking changes require a new wire major, and remove-required-field
is always rejected.
Plans must keep minReaderSchemaMajor <= target wire major. Release gates must
prove readerSkipsUnknownFields, warehouseToleratesUnknownTopics, ingestion
accepts additive payload fields, and rollback is documented.
Registry And Batch Applier#
TelemetrySchemaRegistry registers the standard taxonomy schemas from
@v2/telemetry-ingestion and accepts additive event definitions after a plan
passes validation. Duplicate topic and payload schema versions are rejected.
applyTelemetrySchemaMigrationsToBatch can add optional payload defaults to a
TelemetryEventBatch. By default it preserves the existing reader-compatible
wire version; emitTargetWireVersion: true is reserved for deployments where
new readers have already rolled out.
Targeted verification:
pnpm --filter @v2/telemetry-schema-migrations run typecheck
pnpm --filter @v2/telemetry-schema-migrations run test
python V2/ue/Tools/check-v2-telemetry-schema-migrations.py