Contract Schemas Reference

Human-readable documentation for the JSON contracts that define jinflow’s stable interfaces.

Contracts are pack-specific in content but follow a common structure. The fields shown here are from the interlogic pack as a representative example. Other packs (alptrack, millesime) define different Gold entities but use the same contract format and the same findings/verdict/smebit/bitbundle/report contracts.

How Contracts Work

Contracts define the schema for each layer’s output. They are the stable API between layers — internal table schemas may change, but contract fields are guaranteed. Signals reference gold.v1 entities by contract name (e.g. Shipment, not gold_shipments). Perspectives reference findings.v1. Theses produce verdict statuses consumed by verdicts via diagnosis.v1. The compiler validates all entity and field references against contracts before generating SQL.

The 7 contracts form a dependency chain:

1. Gold Contract (gold.v1)

Purpose: Defines the source-system-agnostic canonical dataset that signals operate on.

Contract ID: interlogic.gold.v1

Entities

Entity	dbt model	Primary key	Description
Shipment	gold_shipments	shipment_key	Shipments with origin/destination, value, and delivery tracking
ShipmentItem	gold_shipment_items	item_key	Line items within a shipment with HS classification and value
Checkpoint	gold_checkpoints	checkpoint_key	Tracking events along the shipment journey with geo-location
Warehouse	gold_warehouses	warehouse_key	Warehouse and facility master data with capacity and location
Route	gold_routes	route_key	Predefined logistics routes with origin/destination and planned transit
RouteLeg	gold_route_legs	leg_key	Individual segments of a multi-leg route with carrier and distance
Carrier	gold_carriers	carrier_key	Carrier master data with type, SLA tier, and regional coverage
Customer	gold_customers	customer_key	Customer master data with type and location
Container	gold_containers	container_key	Container master data with type and weight/volume limits
CustomsDeclaration	gold_customs_declarations	declaration_key	Customs filings with duty calculation and clearance status
InventorySnapshot	gold_inventory_snapshots	snapshot_key	Point-in-time warehouse inventory snapshots by item and lot
Incident	gold_incidents	incident_key	Operational incidents with severity, cost, and root cause tracking
TaxonomyNode	gold_taxonomy_nodes	taxonomy_node_key	Hierarchical classification trees
TaxonomyMemberMapping	gold_taxonomy_member_mappings	taxonomy_mapping_key	Links taxonomy nodes to dimension members
TaxonomyClosure	gold_taxonomy_closure	(taxonomy_id, ancestor_node_id, descendant_node_id)	All ancestor-descendant pairs for roll-up queries

Shipment

Field	Type	Nullable	Description
shipment_key	varchar	No	Surrogate key
shipment_id	varchar	No	Business identifier for the shipment
shipment_ref	varchar	No	Human-readable shipment reference
customer_id	varchar	No	FK to Customer
route_id	varchar	No	FK to Route
container_id	varchar	Yes	FK to Container
transport_mode	varchar	No	Mode of transport (sea/air/road/rail/multimodal)
ship_date	date	No	Date the shipment was dispatched
expected_delivery_date	date	No	Expected delivery date
actual_delivery_date	date	Yes	Actual delivery date
origin_country	varchar	No	Country of origin
origin_city	varchar	No	City of origin
origin_lat	decimal	No	Origin latitude
origin_lon	decimal	No	Origin longitude
destination_country	varchar	No	Destination country
destination_city	varchar	No	Destination city
destination_lat	decimal	No	Destination latitude
destination_lon	decimal	No	Destination longitude
declared_value_usd	decimal	No	Declared shipment value in USD
weight_kg	decimal	No	Total weight in kilograms
volume_m3	decimal	No	Total volume in cubic meters
incoterm	varchar	No	INCOTERM (EXW, FOB, CIF, etc.)
shipment_status	varchar	No	Current status (booked/in_transit/delivered/delayed/lost)
transit_days	integer	No	Computed actual transit days

Checkpoint

Field	Type	Nullable	Description
checkpoint_key	varchar	No	Surrogate key
checkpoint_id	varchar	No	Business identifier for the checkpoint
shipment_id	varchar	No	FK to Shipment
warehouse_id	varchar	Yes	FK to Warehouse
checkpoint_sequence	integer	No	Order in the shipment journey
checkpoint_type	varchar	No	Type (pickup/warehouse_in/customs_hold/customs_cleared/loaded/in_transit/arrived/warehouse_out/out_for_delivery/delivered)
checkpoint_status	varchar	No	Status (completed/pending/skipped/exception)
checkpoint_timestamp	timestamp	No	Timestamp of the checkpoint event
checkpoint_timezone	varchar	No	Timezone of the checkpoint
lat	decimal	No	Latitude
lon	decimal	No	Longitude
carrier_id	varchar	Yes	FK to Carrier
notes	varchar	Yes	Free-text notes

CustomsDeclaration

Field	Type	Nullable	Description
declaration_key	varchar	No	Surrogate key
declaration_id	varchar	No	Business identifier for the declaration
shipment_id	varchar	No	FK to Shipment
declaration_type	varchar	No	Type (export/import/transit)
filing_date	date	No	Date the declaration was filed
clearance_date	date	Yes	Date the declaration was cleared
port_locode	varchar	No	Port of filing UN/LOCODE
hs_code	varchar	No	Harmonized System tariff code
declared_quantity	integer	No	Declared quantity
declared_value_usd	decimal	No	Declared value in USD
duty_rate_pct	decimal	No	Duty rate as percentage
duty_amount_usd	decimal	No	Computed duty amount in USD
declaration_status	varchar	No	Status (filed/cleared/held/rejected)

Incident

Field	Type	Nullable	Description
incident_key	varchar	No	Surrogate key
incident_id	varchar	No	Business identifier for the incident
shipment_id	varchar	No	FK to Shipment
incident_type	varchar	No	Type (delay/damage/loss/customs_hold/temperature_breach/documentation_error)
reported_timestamp	timestamp	No	Timestamp when the incident was reported
resolved_timestamp	timestamp	Yes	Timestamp when the incident was resolved
severity	varchar	No	Severity (critical/major/minor)
estimated_cost_usd	decimal	No	Estimated cost impact in USD
root_cause	varchar	Yes	Root cause
notes	varchar	Yes	Free-text notes

Remaining Entities (summary)

ShipmentItem (10 fields): item_key, item_id, shipment_id, description, hs_code, hs_description, quantity, unit, item_value_usd, country_of_origin.

Warehouse (10 fields): warehouse_key, warehouse_id, name, warehouse_type (distribution_center/port_terminal/customs_bonded/cross_dock/cold_storage), country, city, lat, lon, capacity_m3, un_locode.

Route (8 fields): route_key, route_id, route_name, origin_locode, destination_locode, transport_mode, planned_transit_days, leg_count.

RouteLeg (10 fields): leg_key, leg_id, route_id, leg_sequence, origin_locode, destination_locode, carrier_id, mode, planned_days, distance_km.

Carrier (6 fields): carrier_key, carrier_id, name, carrier_type (ocean_line/airline/trucking/rail/courier), sla_tier (premium/standard/economy), regions.

Customer (7 fields): customer_key, customer_id, name, customer_type (shipper/consignee/broker/manufacturer), country, city, since_year.

Container (6 fields): container_key, container_id, container_type (TEU/FEU/reefer/open_top/flat_rack), max_weight_kg, max_volume_m3, tare_weight_kg.

InventorySnapshot (9 fields): snapshot_key, snapshot_id, warehouse_id, item_description, hs_code, snapshot_timestamp, quantity_units, quantity_kg, lot_number.

TaxonomyNode (10 fields): taxonomy_node_key, taxonomy_id, node_id, parent_node_id, node_name, depth, materialized_path, is_leaf, data_source, is_backfilled.

TaxonomyMemberMapping (4 fields): taxonomy_mapping_key, taxonomy_id, node_id, dimension_type, dimension_member_id.

TaxonomyClosure (4 fields): taxonomy_id, ancestor_node_id, descendant_node_id, depth.

2. Silver Contract (silver.v1)

Purpose: Defines the validated domain layer with data quality flags — the same entities as Gold plus lineage and validation columns.

Contract ID: interlogic.silver.v1

Pattern

Every Silver entity mirrors its Gold counterpart (same fields, same types) with four additional columns:

Field	Type	Nullable	Description
source_file	varchar	No	Source CSV file that produced this row
row_number	integer	No	Row number within the source file
is_valid	boolean	No	Whether the row passed all validation rules
invalid_reason	varchar	Yes	First validation rule that failed (null if valid)

Gold views filter to is_valid = true. Silver retains all rows so that silver_audit signals can inspect what Gold excluded.

Entities

The Silver contract defines 13 entities, one per Gold entity (excluding taxonomy entities which are tables, not views):

Silver entity	Silver model	Gold counterpart
SilverShipment	silver_shipments	Shipment
SilverShipmentItem	silver_shipment_items	ShipmentItem
SilverCheckpoint	silver_checkpoints	Checkpoint
SilverWarehouse	silver_warehouses	Warehouse
SilverRoute	silver_routes	Route
SilverRouteLeg	silver_route_legs	RouteLeg
SilverCarrier	silver_carriers	Carrier
SilverCustomer	silver_customers	Customer
SilverContainer	silver_containers	Container
SilverCustomsDeclaration	silver_customs_declarations	CustomsDeclaration
SilverInventorySnapshot	silver_inventory_snapshots	InventorySnapshot
SilverIncident	silver_incidents	Incident

3. Findings Contract (findings.v1)

Purpose: Defines the standard output schema for all signals and perspectives, enabling cross-signal aggregation and thesis evaluation.

Contract ID: interlogic.findings.v1

ProbeFinding

Field	Type	Nullable	Description
finding_id	string	No	Unique identifier for the finding
tenant_id	string	No	Tenant that produced this finding
probe_id	string	No	Signal that generated this finding
probe_version	string	No	Version of the signal
severity	string	No	Severity level (critical/high/medium/low/info)
entity_type	string	No	Gold entity type (e.g. Shipment, CustomsDeclaration)
entity_id	string	No	Business ID of the flagged entity
time_bucket	string	Yes	Time grouping (month, quarter, etc.)
money_at_risk	decimal	Yes	Monetary impact in base currency
qty_at_risk	decimal	Yes	Quantity impact
health_score	decimal	Yes	Health score (0.0-1.0, perspectives only)
evidence	string	No	JSON blob with signal-specific detail

dbt model pattern: signal_findings__* (one model per signal/perspective)

Primary key: finding_id

4. Verdict Contract (diagnosis.v1)

Purpose: Defines the output schema for root cause verdicts attached to confirmed theses.

Contract ID: interlogic.diagnosis.v1

Verdict

Field	Type	Nullable	Description
diagnosis_id	string	No	Unique identifier for the verdict
tenant_id	string	No	Tenant scope
hypothesis_id	string	No	The confirmed thesis this verdict explains
root_cause_category	string	No	Category (process_failure/system_failure/data_quality/behavioral/structural/external)
root_cause_id	string	No	Specific root cause identifier
confidence	decimal	No	Confidence score (0.0-1.0), includes base + boosts
finding_count	integer	No	Number of signal findings supporting this verdict
money_at_risk	decimal	Yes	Total monetary impact from supporting findings
hypothesis_evidence_score	decimal	No	Evidence score from the parent thesis

dbt model: diagnosis_verdicts

Primary key: diagnosis_id

5. Subject Matter Contract (smebit.v1)

Purpose: Defines the registry and verdict schemas for atomic expert knowledge artifacts.

Contract ID: interlogic.smebit.v1

SubjectMatter (registry)

Field	Type	Nullable	Description
smebit_id	string	No	Unique identifier (matches YAML filename)
smebit_version	string	No	Version string
provider_name	string	No	Name of the knowledge provider
provider_role	string	No	Role of the provider
provider_date	string	No	Date the knowledge was provided
scope_tenant_id	string	Yes	Tenant scope (null = cross-tenant)
scope_source_system	string	Yes	Source system scope
scope_time_from	string	Yes	Start of applicable time range
scope_time_until	string	Yes	End of applicable time range
category	string	No	Category (data_quality/mapping/business_rule/process/system/seasonal/historical/structural)
tags	string	Yes	Comma-separated tags
status	string	No	Lifecycle status
superseded_by	string	Yes	ID of the Subject Matter entry that replaces this one
has_check	boolean	No	Whether this Subject Matter entry has an executable check (Level 1)
has_prescription	boolean	No	Whether this Subject Matter entry includes a prescription
prescription_type	string	Yes	Prescription type (if applicable)
prescription_status	string	Yes	Prescription status (proposed/accepted/implemented)
subject_en	string	No	Subject line (English)
subject_de	string	No	Subject line (German)
subject_fr	string	No	Subject line (French)
why_en	string	Yes	Explanation of why (English)
why_de	string	Yes	Explanation of why (German)
why_fr	string	Yes	Explanation of why (French)
content_en	string	No	Full content (English)
content_de	string	No	Full content (German)
content_fr	string	No	Full content (French)
anchor_probes	string	Yes	Comma-separated signal IDs
anchor_hypotheses	string	Yes	Comma-separated thesis IDs
anchor_entities	string	Yes	Comma-separated entity type references

dbt model: smebit_registry

Primary key: smebit_id

SubjectMatterVerdict

Field	Type	Nullable	Description
verdict_id	string	No	Unique verdict identifier
tenant_id	string	No	Tenant scope
smebit_id	string	No	FK to Subject Matter registry
smebit_version	string	No	Version of the Subject Matter entry
status	string	No	Verdict status (confirmed/violated/no_data)
evidence	string	No	JSON blob with check-specific detail

dbt model pattern: smebit_verdicts__* (one per Level 1 Subject Matter entry)

Primary key: verdict_id

6. Dossier Contract (bitbundle.v1)

Purpose: Defines the registry and membership schemas for curated narrative groupings of SMEbits.

Contract ID: interlogic.bitbundle.v1

Dossier

Field	Type	Nullable	Description
bitbundle_id	string	No	Unique identifier (matches YAML filename, starts with bb_)
bitbundle_version	string	No	Version string
tenant_id	string	Yes	Tenant scope (null = cross-tenant)
curator_name	string	No	Name of the curator
curator_role	string	No	Role of the curator
date	string	No	Curation date
title_en	string	No	Bundle title (English)
title_de	string	No	Bundle title (German)
title_fr	string	No	Bundle title (French)
narrative_en	string	No	Full narrative (English)
narrative_de	string	No	Full narrative (German)
narrative_fr	string	No	Full narrative (French)
tags	string	Yes	Comma-separated tags
status	string	No	Lifecycle status (active/archived)
smebit_count	integer	No	Number of member Subject Matter entries

dbt model: bitbundle_registry

Primary key: bitbundle_id

DossierMembership

Field	Type	Nullable	Description
bitbundle_id	string	No	FK to Dossier
smebit_id	string	No	FK to Subject Matter
note_en	string	Yes	Contextual note for this link (English)
note_de	string	Yes	Contextual note for this link (German)
note_fr	string	Yes	Contextual note for this link (French)
sort_order	integer	No	Display order within the bundle

dbt model: bitbundle_memberships

Primary key: (bitbundle_id, smebit_id)

7. Report Contract (report.v1)

Purpose: Defines the output schema for compiled analytical reports (data payload and registry metadata).

Contract ID: interlogic.report.v1

ReportData

Field	Type	Nullable	Description
tenant_id	string	No	Tenant scope
report_id	string	No	Report identifier
report_version	string	No	Version of the report
sections	json	No	JSON array of section data payloads

dbt model pattern: report_data__* (one per report)

Primary key: None (one row per tenant per report)

ReportRegistry

Field	Type	Nullable	Description
report_id	string	No	Unique report identifier
report_version	string	No	Version string
title_en	string	No	Report title (English)
title_de	string	No	Report title (German)
title_fr	string	No	Report title (French)
description_en	string	No	Report description (English)
description_de	string	No	Report description (German)
description_fr	string	No	Report description (French)
audience	json	No	JSON array of target audiences
orientation	string	No	Page orientation (portrait/landscape)
page_size	string	No	Page size (A4, letter, etc.)
sections	json	No	JSON array of section definitions
created_at	string	No	Creation timestamp
modified_at	string	No	Last modification timestamp
compiled_at	string	No	Compilation timestamp

dbt model: report_registry

Primary key: report_id

Design Principles

Surrogate keys alongside business IDs. Every Gold entity has both a *_key (surrogate, generated via dbt_utils.generate_surrogate_key) and a *_id (business identifier from the source system). Surrogate keys are stable across rebuilds; business IDs are human-readable.

Tri-lingual support. All user-facing text fields come in _en, _de, _fr variants. This applies to Subject Matter subjects/content/why, Dossier titles/narratives, report titles/descriptions, and signal registry display text.

Quality tracking. Silver adds is_valid and invalid_reason to every entity. Invalid rows are retained (not silently dropped) so that data quality signals can inspect rejection patterns. Gold filters to is_valid = true.

Tenant isolation. Every fact and verdict table includes tenant_id. Findings, verdicts, Subject Matter verdicts, and report data are all scoped to a single tenant. Platform views union across tenants but preserve the tenant_id column.

Nullable fields explicitly marked. Foreign keys that represent optional relationships (e.g. container_id on Shipment, warehouse_id on Checkpoint) and fields that depend on process completion (e.g. actual_delivery_date, clearance_date, resolved_timestamp) are nullable. Required fields are never null in Gold.

JSON for structured evidence. The evidence field on ProbeFinding and SubjectMatterVerdict, and the sections field on ReportData/ReportRegistry, carry structured data as JSON strings. This keeps the table schema stable while allowing signal-specific and report-specific detail to evolve independently.