JSON Schema Like Field Catalogs For Top Critical Events — Полуформальные field catalogs для критичных async событий

Версия: 1.0
Дата: 24.04.2026
Статус: Готов к обсуждению

Назначение документа

Этот документ фиксирует первый JSON-Schema-like field-by-field catalog для наиболее критичных async событий платформы.

Его задача — определить:

• какие поля входят в envelope и payload для ключевых event families;
• какие поля required, а какие optional;
• какие типы и bounded value classes ожидаются;
• какие поля являются stable identifiers, а какие context/meta extensions;
• какие evolution notes важны на уровне конкретных полей.

Документ не является финальным JSON Schema пакетом и не претендует на полную формальную валидирующую спецификацию. Он является более строгим catalog layer между schema drafts и будущими formal schemas.

Опорные документы

• Schema Draft Package For Top Critical Events — Первый полуформальный schema-layer для критичных async событий
• Payload Examples For Top Critical Events — Первые example payloads для ключевых async событий
• Consumer Compatibility Checklist By Release Unit — Проверка готовности consumers к эволюции async contracts
• Version Evolution Policy For Async Event Contracts — Правила версии, совместимости и replay-дисциплины
• Retry DLQ Replay Matrix By Schema Family — Исполнительная матрица доставки, повторов и восстановления
• Webhook Compatibility Checklist For External Async Notifications — Границы внешних async уведомлений и их совместимости

Почему Этот Документ Нужен Отдельно

После появления:

• schema drafts;
• example payloads;
• consumer compatibility checklist;

уже недостаточно только narrative-level описаний required/optional fields.

Нужен следующий практический слой, который:

• раскладывает поля по типам;
• явно отделяет envelope от payload;
• фиксирует bounded enums/code classes;
• показывает, какие поля особенно чувствительны к breaking change;
• даёт общую точку отсчёта для будущих formal schemas.

Без этого contract evolution остаётся слишком зависимой от prose и примеров.

Главный Принцип

Field catalog должен быть:

• строгим по identifiers and required fields;
• осторожным по bounded enums;
• понятным для producer/consumer teams;
• пригодным для compatibility review;
• не перегруженным преждевременной низкоуровневой детализацией.

Field Notation

Для полей ниже фиксируются:

• path
• type
• required
• bounded values, where relevant
• notes

Event 1. quote.created

Envelope Fields

• event_name

  • type: string
  • required: yes
  • bounded values: quote.created
  • notes: stable event identity

• event_version

  • type: string
  • required: yes
  • bounded values: 1.0
  • notes: bump on breaking contract change

• event_id

  • type: string
  • required: yes
  • notes: stable unique event id

• occurred_at

  • type: string(datetime)
  • required: yes
  • notes: producer event time

• producer

  • type: string
  • required: yes
  • notes: bounded producer identity, not free-form prose

• correlation_id

  • type: string
  • required: yes
  • notes: cross-contour tracing

• causation_id

  • type: string
  • required: no
  • notes: command/event lineage when present

• actor_context_id

  • type: string
  • required: no
  • notes: actor-aware surfaces

• tenant_id

  • type: string
  • required: yes
  • notes: tenant-scoped event family

• workspace_id

  • type: string
  • required: no
  • notes: workspace-aware context

• delivery_class

  • type: string
  • required: yes
  • bounded values: domain-event
  • notes: must not drift semantically

• replay_sensitivity

  • type: string
  • required: yes
  • bounded values: high
  • notes: high-value family

• schema_family

  • type: string
  • required: yes
  • bounded values: quote-lifecycle.v1
  • notes: family lineage marker

Payload Fields

• payload.quote_id

  • type: string
  • required: yes
  • notes: primary quote identity

• payload.offer_id

  • type: string
  • required: yes
  • notes: parent commercial basis

• payload.quote_state

  • type: string
  • required: yes
  • bounded values: active, expired, invalidated
  • notes: for this event expected runtime value is active

• payload.price_basis_ref

  • type: string
  • required: yes
  • notes: reference-shaped, not full price snapshot

• payload.currency_code

  • type: string(ISO-4217-like)
  • required: yes
  • notes: currency of commercial promise

• payload.quote_valid_until

  • type: string(datetime)
  • required: no
  • notes: optional because some future quote families may differ

• payload.commercial_context_ref

  • type: string
  • required: yes
  • notes: commercial policy lineage

• payload.price_view_class

  • type: string
  • required: no
  • bounded values: implementation-defined bounded class
  • notes: additive evolution likely

• payload.quote_visibility_scope

  • type: string
  • required: no
  • notes: scope of intended visibility

Event 2. quote.invalidated

Envelope Differences From quote.created

• causation_id
  • type: string
  • required: yes
  • notes: required here because invalidation must be traceable to cause

Payload Fields

• payload.quote_id

  • type: string
  • required: yes

• payload.offer_id

  • type: string
  • required: yes

• payload.quote_state

  • type: string
  • required: yes
  • bounded values: invalidated
  • notes: fixed value for this event

• payload.invalidated_by_event_ref

  • type: string
  • required: yes
  • notes: causal reference, not embedded upstream payload

• payload.repricing_reason_code

  • type: string
  • required: yes
  • bounded values: bounded code set, additive growth possible
  • notes: semantic drift here is breaking risk

• payload.price_view_class

  • type: string
  • required: no

Event 3. offer.publication.suppressed

Envelope Fields

• event_name

  • type: string
  • required: yes
  • bounded values: offer.publication.suppressed

• event_version

  • type: string
  • required: yes

• event_id

  • type: string
  • required: yes

• occurred_at

  • type: string(datetime)
  • required: yes

• producer

  • type: string
  • required: yes

• correlation_id

  • type: string
  • required: yes

• causation_id

  • type: string
  • required: no

• delivery_class

  • type: string
  • required: yes
  • bounded values: integration-domain-hybrid

• replay_sensitivity

  • type: string
  • required: yes
  • bounded values: high

• schema_family

  • type: string
  • required: yes
  • bounded values: offer-publication.v1

Payload Fields

• payload.offer_id

  • type: string
  • required: yes

• payload.offer_revision

  • type: integer
  • required: yes

• payload.property_id

  • type: string
  • required: yes

• payload.publication_state

  • type: string
  • required: yes
  • bounded values: suppressed

• payload.integrity_state

  • type: string
  • required: yes
  • bounded values: bounded code set
  • notes: semantic meaning must remain stable

• payload.freshness_state

  • type: string
  • required: yes
  • bounded values: bounded freshness classes

• payload.suppression_reason_codes

  • type: array[string]
  • required: no
  • notes: bounded code list, additive growth allowed

• payload.publication_scope

  • type: string
  • required: yes
  • notes: scope semantics are compatibility-sensitive

• payload.affected_surface_classes

  • type: array[string]
  • required: no
  • notes: bounded surface classes only

Event 4. booking.confirmed

Envelope Fields

• event_name

  • type: string
  • required: yes
  • bounded values: booking.confirmed

• event_version

  • type: string
  • required: yes

• event_id

  • type: string
  • required: yes

• occurred_at

  • type: string(datetime)
  • required: yes

• producer

  • type: string
  • required: yes

• correlation_id

  • type: string
  • required: yes

• causation_id

  • type: string
  • required: no

• actor_context_id

  • type: string
  • required: no

• tenant_id

  • type: string
  • required: yes

• workspace_id

  • type: string
  • required: no

• delivery_class

  • type: string
  • required: yes
  • bounded values: domain-event

• replay_sensitivity

  • type: string
  • required: yes
  • bounded values: high

• schema_family

  • type: string
  • required: yes
  • bounded values: booking-transitions.v1

Payload Fields

• payload.booking_id

  • type: string
  • required: yes

• payload.booking_state

  • type: string
  • required: yes
  • bounded values: confirmed

• payload.quote_id

  • type: string
  • required: yes

• payload.booking_reference_scope

  • type: string
  • required: yes
  • notes: bounded scope semantics

• payload.supplier_confirmation_state

  • type: string
  • required: yes
  • bounded values: confirmed, future bounded additions possible

• payload.transactional_outcome_class

  • type: string
  • required: yes
  • bounded values: success

• payload.support_visibility_class

  • type: string
  • required: yes
  • bounded values: bounded support visibility classes

• payload.manual_intervention_required

  • type: boolean
  • required: yes

• payload.supplier_booking_ref

  • type: string
  • required: no
  • notes: optional supplier correlation field

Event 5. booking.unknown.external.state

Envelope Differences From booking.confirmed

• causation_id
  • type: string
  • required: yes
  • notes: required for operational traceability

Payload Fields

• payload.booking_id

  • type: string
  • required: yes

• payload.booking_state

  • type: string
  • required: yes
  • bounded values: unknown_external_state

• payload.quote_id

  • type: string
  • required: yes

• payload.booking_reference_scope

  • type: string
  • required: yes

• payload.supplier_confirmation_state

  • type: string
  • required: yes
  • bounded values: unknown

• payload.transactional_outcome_class

  • type: string
  • required: yes
  • bounded values: uncertainty-oriented bounded class

• payload.support_visibility_class

  • type: string
  • required: yes
  • bounded values: escalation-oriented bounded class

• payload.manual_intervention_required

  • type: boolean
  • required: yes

• payload.recovery_path_ref

  • type: string
  • required: yes

• payload.unknown_state_reason_code

  • type: string
  • required: yes
  • bounded values: bounded code set

Event 6. settlement.event.posted

Envelope Fields

• event_name

  • type: string
  • required: yes
  • bounded values: settlement.event.posted

• event_version

  • type: string
  • required: yes

• event_id

  • type: string
  • required: yes

• occurred_at

  • type: string(datetime)
  • required: yes

• producer

  • type: string
  • required: yes

• correlation_id

  • type: string
  • required: yes

• causation_id

  • type: string
  • required: no

• tenant_id

  • type: string
  • required: yes

• workspace_id

  • type: string
  • required: no

• delivery_class

  • type: string
  • required: yes
  • bounded values: financial-domain-event

• replay_sensitivity

  • type: string
  • required: yes
  • bounded values: high

• schema_family

  • type: string
  • required: yes
  • bounded values: settlement-reconciliation.v1

Payload Fields

• payload.financial_event_id

  • type: string
  • required: yes

• payload.booking_id

  • type: string
  • required: yes

• payload.financial_state_class

  • type: string
  • required: yes
  • bounded values: bounded financial state codes

• payload.currency_code

  • type: string(ISO-4217-like)
  • required: yes

• payload.amount_scope_class

  • type: string
  • required: yes
  • bounded values: bounded amount scope classes

• payload.financial_counterparty_scope

  • type: string
  • required: yes

• payload.settlement_basis_ref

  • type: string
  • required: yes

• payload.clearing_context_ref

  • type: string
  • required: no

Event 7. usage.quota.exhausted

Envelope Fields

• event_name

  • type: string
  • required: yes
  • bounded values: usage.quota.exhausted

• event_version

  • type: string
  • required: yes

• event_id

  • type: string
  • required: yes

• occurred_at

  • type: string(datetime)
  • required: yes

• producer

  • type: string
  • required: yes

• correlation_id

  • type: string
  • required: yes

• tenant_id

  • type: string
  • required: yes

• delivery_class

  • type: string
  • required: yes
  • bounded values: integration-control-signal

• replay_sensitivity

  • type: string
  • required: yes
  • bounded values: medium

• schema_family

  • type: string
  • required: yes
  • bounded values: usage-governance.v1

Payload Fields

• payload.tenant_id

  • type: string
  • required: yes
  • notes: duplicated tenant-level enforcement identity

• payload.usage_profile_id

  • type: string
  • required: yes

• payload.governance_state

  • type: string
  • required: yes
  • bounded values: quota_exhausted

• payload.affected_surface_scope

  • type: string
  • required: yes

• payload.enforcement_class

  • type: string
  • required: yes
  • bounded values: bounded enforcement classes

• payload.quota_window_ref

  • type: string
  • required: no

• payload.throttle_policy_ref

  • type: string
  • required: no

Cross-Catalog Rules

Для всей первой волны field catalogs должны действовать:

• removing required field is breaking risk;
• semantic drift in bounded code classes is breaking risk;
• adding optional field may be additive only with safe consumer fallback;
• identifiers and correlation fields are highest-stability fields;
• heavy snapshot expansion into currently reference-shaped fields requires explicit compatibility review.

What Must Stay Out Of Scope

Пока не нужно:

• превращать catalog в final machine-validating schema set;
• моделировать broker serialization details;
• описывать every nested future field;
• фиксировать every future enum value in advance.

Что Должно Появиться Следом

Следующий практический слой после этого документа:

• Webhook Compatibility Checklist For External Async Notifications — Границы внешних async уведомлений и их совместимости
• producer readiness checklist paired with consumer checklist;
• release-gate templates for async contract changes;
• future formal JSON Schema / AsyncAPI schema package derived from these catalogs.

Этот документ создаёт более формальный field-layer и делает критичные async contracts значительно более пригодными для controlled implementation and compatibility review.

Уточнение под Фазы 4–6 (28.04.2026)

JSON Schema-like field catalogs для критичных async событий должны опираться на каноничные структуры:

• Booking entities + 14 states → booking-state-machine.md;
• Payment entities (PaymentIntent, Refund, Chargeback, Settlement, PayoutBatch) → payment-domain.md;
• Tour saga entities (CompositionRule, TourBookingTransaction, DriftEvent) → tour-builder-operational-model.md;
• Notification entities → notification-and-communication.md;
• Tenant isolation entities → multi-tenant-isolation-strength.md;
• Security audit entities → security-architecture.md;
• Compliance entities → compliance-and-legal.md;
• DR / capacity / SLA / incident entities → disaster-recovery-and-capacity.md, sla-and-on-call-model.md, runbooks-incident-playbooks.md.

Сводный каталог events → initial-event-taxonomy.md. DDL-уровневые схемы расширены в database-schema.md, секция «Расширение схемы под Фазы 4–6».

При создании field catalogs — использовать OpenAPI 3.1 или JSON Schema 2020-12 (см. proposal-openapi-first-polyglot-codegen.md).

Уточнение выполнено через no-destruction.