Contract Layer · si-schema

Work in progress. The contract layer and all types defined in it (interfaces, protocol bindings, authority rules, alarm definitions, acceptance cases, lineages and their supporting structures) are under active development and subject to breaking changes without notice.

How objects are linked

Object	Owns	References	Why no duplication
`project`	document identity	none	One project header per artifact.
`parties`	party registry	none	Party IDs are defined once and reused by signals, interfaces, and lineages.
`components`	component/module registry	party/vendor ownership	Endpoints reuse component IDs instead of repeating component details in each interface/signal.
`functions.signals`	atomic signal definition	components, protocol/interface refs	Signal meaning is defined once and linked from other layers.
`interfaces`	boundary contract	components, protocol binding, authority/alarm IDs, signal refs	Interface groups signal links without redefining each signal payload.
`protocol_bindings`	L3 exchange profile	none	Transport/address/timing/security lives in one object and is referenced.
`lineages`	cross-party flow	signal links, parties	Transformation chain reuses signal and party IDs instead of duplicating fields.

Design rule: define meaning once, reference it everywhere else. If a field has its own lifecycle and validation logic, it belongs to a dedicated object, not duplicated across signal rows.

Top-level contract objects

Field	Type	Required	Purpose
`artefact`	`ArtifactMeta`	no	Role, release status, compatibility class, lifecycle governance.
`parties`	`list[Party]`	no	Parties across vendor, integrator, owner and analytics flows.
`protocol_bindings`	`list[ProtocolBinding]`	no	Level-3 exchange contract details (family, transport, timing).
`mode_definitions`	`list[ModeDefinition]`	no	Operating mode semantics.
`authority_rules`	`list[AuthorityRule]`	no	Command ownership and arbitration rules.
`alarm_definitions`	`list[AlarmDefinition]`	no	Alarm behavior (priority, latching, ack/reset, visibility).
`interfaces`	`list[Interface]`	no	First-class interface boundaries linking components and signals.
`acceptance_cases`	`list[AcceptanceCase]`	no	FAT/SAT-oriented acceptance semantics.
`lineages`	`list[Lineage]`	no	Cross-party transformation chain per signal.

Artifact governance example

artefact.yaml

YAML

artefact:
  artifact_id: eps_contract
  role: integration_contract
  status: released
  contract_version: 1.2.0
  compatibility: backward
  published_at: 2026-06-13
  lifecycle_state: active
  intended_consumers: [integrator, shipowner, analytics_provider]

Interfaces and protocol binding

contract_objects.yaml

YAML

parties:
  - id: VFD_VENDOR_A
    name: Vendor A Drive
    kind: vendor
  - id: YARD_INTEGRATOR
    name: Yard SI Team
    kind: integrator

protocol_bindings:
  - id: main_modbus
    family: modbus_tcp
    transport: network
    exchange_pattern: polled
    access_mode: read_write
    endpoint: 10.10.8.31:502
    address: "holding:40001..40064"
    addressing:
      kind: modbus
      register_type: holding
      start: 40001
      count: 2
    update_ms: 500
    timeout_ms: 3000
    network_profile:
      segment_id: AUT_NET_A
      vlan_id: 20
      security_zone: automation
      redundancy_role: primary
      security_mode: tls
      time_sync_source: ptp
      timestamp_quality_required: true

interfaces:
  - id: rcs_to_vfd_main
    name: RCS to VFD main command channel
    from_ref: { system_id: RCS, module_id: Main }
    to_ref:   { system_id: VFD, module_id: Main }
    medium: network
    protocol_binding_id: main_modbus
    authority_rule_id: main_cmd_auth
    alarm_definition_ids: [vfd_comms_lost]
    member_signals:
      - { function_no: 1, signal_id: speed_setpoint }
      - { function_no: 1, signal_id: run_cmd }

Lineage chain

lineage.yaml

YAML

lineages:
  - signal_ref: { function_no: 1, signal_id: shaft_power }
    hops:
      - step: 1
        actor: VFD_VENDOR_A
        rule: sample
        input_contract: null
        output_contract: "vfd_tm@1.0.0"
      - step: 2
        actor: YARD_INTEGRATOR
        rule: average
        rule_params: { window_s: 60 }
        input_contract: "vfd_tm@1.0.0"
        output_contract: "vessel_contract@1.2.0"

Layer 2 physical link profile

hardwired_interface.yaml

YAML

interfaces:
      - id: e_stop_loop
        name: E-stop hardwired loop
        from_ref: { system_id: RCS, module_id: Main }
        to_ref:   { system_id: TCS, module_id: HPS }
        medium: hardwired
        physical_link:
          electrical:
            contact_type: dry
            logic_type: sourcing
            wire_count: "2_wire"
            loop_powered: false
            external_powered: true
            nominal_voltage_v: 24
          connector:
            connector_type: TB
            mating_side_owner: YARD_INTEGRATOR
            pins:
              - pin: TB1-01
                signal_role: E_STOP_A
              - pin: TB1-02
                signal_role: E_STOP_B
            shield_termination: panel_single_end
            grounding_policy: pe_at_marshalling
          cable:
            cable_type: IEC60092-376
            pair_type: twisted_pair
            shielded: true
            max_length_m: 120
          redundancy_role: primary
          marshalling_location: ECR_MARSHALLING_A

Integration-contract requiredness

Group	si_internal	integration_contract
`interface boundary`	required	required
`family/exchange/access + timing`	optional	required
`address/addressing`	optional	required
`semantic identity package`	optional	required
`producer + lineage coverage`	optional	required
`physical_link (hardwired)`	optional	required
`network_profile (network)`	optional	required

CLI support. Use si-schema diff-contract old.yaml new.yaml to produce a machine-readable compatibility report (pass/fail, change list, and violations).

CI promotion gate. The workflow contract-promotion-gate enforces compatibility before promotion. If old_path is omitted, the baseline is auto-resolved from the base/default branch at the same contract path.