Перейти к основному содержимому

Schema Draft Package For Top Critical Events — Первый полуформальный schema-layer для критичных async событий

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

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

Этот документ фиксирует первый полуформальный schema-draft package для наиболее критичных async событий платформы.

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

  • какие event schemas должны получить первичную полуформальную структуру раньше других;
  • как разделяются envelope, payload, required fields, optional fields и evolution notes;
  • какие compatibility boundaries уже нужно удерживать;
  • как перейти от examples и payload outlines к будущему formal AsyncAPI/JSON Schema пакету без premature hard freeze.

Документ не является финальным schema registry и не утверждает окончательные serialisation contracts. Он является bounded drafting layer между examples и formal schema package.

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

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

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

  • payload family outlines;
  • example payloads;

уже недостаточно иметь только narrative descriptions и illustrative JSON examples.

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

  • какие поля уже считаются required;
  • какие поля допустимы как optional;
  • какие enum/value classes уже стабилизируются первыми;
  • где schema evolution должна быть особенно осторожной;
  • какие schemas реально worth drafting first.

Без этого examples остаются полезными, но всё ещё слишком свободными для implementation discipline.

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

Первый schema-draft package должен быть:

  • explicit about required vs optional fields;
  • strict on identifiers and correlation;
  • cautious about enums and value freeze;
  • compatible with replay and support needs;
  • narrow enough to avoid freezing undeveloped contours.

Scope Первой Волны​

Первая волна schema drafts должна покрывать только high-value события, где ошибка контракта особенно дорога:

  • quote.created
  • quote.invalidated
  • offer.publication.suppressed
  • booking.confirmed
  • booking.unknown.external.state
  • settlement.event.posted
  • usage.quota.exhausted

Draft Structure Pattern​

Для каждого event schema draft ниже фиксируются:

  • event schema family
  • required envelope fields
  • required payload fields
  • optional payload fields
  • value-class notes
  • evolution notes

Draft 1. quote.created​

Event Schema Family​

quote-lifecycle.v1

Required Envelope Fields​

  • event_name
  • event_version
  • event_id
  • occurred_at
  • producer
  • correlation_id
  • tenant_id
  • delivery_class
  • replay_sensitivity
  • schema_family
  • payload

Required Payload Fields​

  • quote_id
  • offer_id
  • quote_state
  • price_basis_ref
  • currency_code
  • commercial_context_ref

Optional Payload Fields​

  • quote_valid_until
  • workspace_id
  • actor_context_id
  • price_view_class
  • quote_visibility_scope

Value-Class Notes​

  • quote_state first-wave values:
    • active
    • expired
    • invalidated
  • delivery_class should remain domain-event for this family.

Evolution Notes​

  • do not freeze detailed monetary breakdown in this schema family yet;
  • price_view_class may evolve with surface strategy;
  • adding optional visibility/context fields is safe if existing required fields remain stable.

Draft 2. quote.invalidated​

Event Schema Family​

quote-lifecycle.v1

Required Envelope Fields​

  • all quote.created required envelope fields
  • causation_id

Required Payload Fields​

  • quote_id
  • offer_id
  • quote_state
  • invalidated_by_event_ref
  • repricing_reason_code

Optional Payload Fields​

  • workspace_id
  • actor_context_id
  • price_view_class

Value-Class Notes​

  • quote_state for this event should be fixed to invalidated;
  • repricing_reason_code should remain code-based, not free-text.

Evolution Notes​

  • keep invalidated_by_event_ref reference-shaped, not expanded into full upstream snapshot;
  • additional optional reason-context fields may be added later.

Draft 3. offer.publication.suppressed​

Event Schema Family​

offer-publication.v1

Required Envelope Fields​

  • event_name
  • event_version
  • event_id
  • occurred_at
  • producer
  • correlation_id
  • delivery_class
  • replay_sensitivity
  • schema_family
  • payload

Required Payload Fields​

  • offer_id
  • offer_revision
  • property_id
  • publication_state
  • integrity_state
  • freshness_state
  • publication_scope

Optional Payload Fields​

  • suppression_reason_codes
  • affected_surface_classes

Value-Class Notes​

  • publication_state for this event should be fixed to suppressed;
  • integrity_state should remain code-like and bounded;
  • affected_surface_classes should be treated as a bounded list, not arbitrary labels.

Evolution Notes​

  • do not freeze full governance snapshot into this schema;
  • suppression reason catalog can expand, but existing codes should remain backward meaningful.

Draft 4. booking.confirmed​

Event Schema Family​

booking-transitions.v1

Required Envelope Fields​

  • event_name
  • event_version
  • event_id
  • occurred_at
  • producer
  • correlation_id
  • tenant_id
  • delivery_class
  • replay_sensitivity
  • schema_family
  • payload

Required Payload Fields​

  • booking_id
  • booking_state
  • quote_id
  • booking_reference_scope
  • supplier_confirmation_state
  • transactional_outcome_class
  • support_visibility_class
  • manual_intervention_required

Optional Payload Fields​

  • workspace_id
  • actor_context_id
  • supplier_booking_ref

Value-Class Notes​

  • booking_state for this event should be fixed to confirmed;
  • transactional_outcome_class first-wave value should be success;
  • manual_intervention_required should remain explicit boolean.

Evolution Notes​

  • do not add full booking item arrays or traveller snapshots to this event family yet;
  • partner-facing derived events may need later surface-specific variants, but not in this first schema draft.

Draft 5. booking.unknown.external.state​

Event Schema Family​

booking-transitions.v1

Required Envelope Fields​

  • all required booking.confirmed envelope fields
  • causation_id

Required Payload Fields​

  • booking_id
  • booking_state
  • quote_id
  • booking_reference_scope
  • supplier_confirmation_state
  • transactional_outcome_class
  • support_visibility_class
  • manual_intervention_required
  • recovery_path_ref
  • unknown_state_reason_code

Optional Payload Fields​

  • workspace_id
  • actor_context_id

Value-Class Notes​

  • booking_state for this event should be fixed to unknown_external_state;
  • transactional_outcome_class should remain bounded to uncertainty semantics;
  • support_visibility_class should remain escalation-oriented code, not prose.

Evolution Notes​

  • keep uncertainty explanation code-based;
  • if richer supplier context appears later, add it as optional bounded references, not vendor-specific blob fields.

Draft 6. settlement.event.posted​

Event Schema Family​

settlement-reconciliation.v1

Required Envelope Fields​

  • event_name
  • event_version
  • event_id
  • occurred_at
  • producer
  • correlation_id
  • tenant_id
  • delivery_class
  • replay_sensitivity
  • schema_family
  • payload

Required Payload Fields​

  • financial_event_id
  • booking_id
  • financial_state_class
  • currency_code
  • amount_scope_class
  • financial_counterparty_scope
  • settlement_basis_ref

Optional Payload Fields​

  • workspace_id
  • clearing_context_ref

Value-Class Notes​

  • delivery_class should remain financial-domain-oriented;
  • financial_state_class first-wave value may start with initial-posted;
  • amount_scope_class should remain code-like and bounded.

Evolution Notes​

  • do not freeze invoice/ledger-specific semantics here;
  • additional financial references can be added later if kept reference-based.

Draft 7. usage.quota.exhausted​

Event Schema Family​

usage-governance.v1

Required Envelope Fields​

  • event_name
  • event_version
  • event_id
  • occurred_at
  • producer
  • correlation_id
  • tenant_id
  • delivery_class
  • replay_sensitivity
  • schema_family
  • payload

Required Payload Fields​

  • tenant_id
  • usage_profile_id
  • governance_state
  • affected_surface_scope
  • enforcement_class

Optional Payload Fields​

  • quota_window_ref
  • throttle_policy_ref

Value-Class Notes​

  • governance_state for this event should be fixed to quota_exhausted;
  • enforcement_class should remain bounded to policy/action classes.

Evolution Notes​

  • do not turn this event into low-level metrics schema;
  • richer usage metrics belong in reporting or aggregation layers, not in this event family.

Cross-Draft Compatibility Rules​

Для всей первой schema-draft wave должны действовать:

  • adding new optional fields is allowed;
  • removing required fields is disallowed;
  • changing identifier semantics is disallowed;
  • changing bounded code meaning requires version evolution note;
  • replacing reference fields with embedded heavy snapshots should be treated as breaking change risk.

What Must Stay Out Of Scope​

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

  • писать full JSON Schema syntax for every field;
  • фиксировать transport serialization quirks;
  • нормализовывать all future event families into this package;
  • обещать public external compatibility for all drafts;
  • моделировать vendor-specific extensions.

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

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

Этот документ создаёт первый полуформальный schema-layer и переводит payload examples в более контролируемый contract drafting stage.

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

Schema drafts для критичных async событий теперь опираются на каноничные структуры из reference-документов фаз 4–6:

Сводный каталог — initial-event-taxonomy.md. 6 классов событий с guarantees — eventing-and-queue-baseline.md. При новых schema drafts использовать OpenAPI 3.1 / AsyncAPI 3 согласно proposal-openapi-first-polyglot-codegen.md.

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