Référence des schémas Contract

Documentation lisible par un humain des Contracts JSON qui définissent les interfaces stables de jinflow.

Les Contracts sont spécifiques au contenu du pack mais suivent une structure commune. Les champs montrés ici proviennent du pack interlogic comme exemple représentatif. D’autres packs (alptrack, millesime) définissent des entités Gold différentes mais utilisent le même format de Contract et les mêmes Contracts findings/diagnosis/smebit/bitbundle/report.

Comment fonctionnent les Contracts

Les Contracts définissent le schéma pour la sortie de chaque couche. Ils sont l’API stable entre les couches — les schémas de tables internes peuvent changer, mais les champs Contract sont garantis. Les Signals référencent les entités gold.v1 par nom de Contract (par ex. Shipment, pas gold_shipments). Les Perspectives référencent findings.v1. Les Theses produisent des verdicts consommés par les Verdicts via diagnosis.v1. Le compilateur valide toutes les références Entity et champ contre les Contracts avant de générer le SQL.

Les 7 Contracts forment une chaîne de dépendance :

Pour la référence complète des champs de chaque Contract, voir la version anglaise qui contient toutes les spécifications détaillées de champs pour les 7 Contracts (gold.v1, silver.v1, findings.v1, diagnosis.v1, smebit.v1, bitbundle.v1, report.v1).

Principes de conception

Clés surrogates à côté des ID métier. Chaque entité Gold a à la fois un *_key (surrogate, généré via dbt_utils.generate_surrogate_key) et un *_id (identifiant métier du système source).

Support trilingue. Tous les champs de texte destinés aux utilisateurs viennent en variantes _en, _de, _fr.

Suivi de qualité. Silver ajoute is_valid et invalid_reason à chaque entité. Les lignes invalides sont conservées (pas supprimées silencieusement).

Isolation tenant. Chaque table de faits et de verdicts inclut tenant_id.

Champs nullable explicitement marqués. Les clés étrangères représentant des relations optionnelles et les champs dépendant de la complétion de processus sont nullable. Les champs requis ne sont jamais null dans Gold.

JSON pour les preuves structurées. Le champ evidence sur ProbeFinding et SubjectMatterVerdict, et le champ sections sur ReportData/ReportRegistry, portent des données structurées comme chaînes JSON.