Container: Contract.contractAttributes
Extends: ServiceContract/v2.1
Protocol Version: 2.0
Semantic Model: generalised
Use Cases: Coordination contract (T1), referral lifecycle, handover, deviation signalling
Tags: generic-service, coordination, contract
ServiceCoordination is the coordination contract (T1) — the core of the generic
coordination layer. It carries the persistent coordination identity, a lifecycle
state machine, the targetCriteria the coordinator discovers against, an optional
named-target snapshot (recommendedTargetRef), a credential-scoped
handoverDocument, a notificationRoster, an in-band deviation signal, and
transfer (handoff) support. Chain: ServiceContract <- ServiceCoordination <- HealthReferral.
Contract.contractAttributes in on_confirm / on_status of the T1 transaction.targetCriteria vs recommendedTargetRef — targetCriteria is mandatory and is
the substance of the referral (what the coordinator re-discovers against on
TARGET_REFUSED / retry). recommendedTargetRef is an optional, non-binding named
overlay captured at Discover 1; its presence selects named vs scoped discovery mode.lifecycleState state machine — mirrors the ServiceEntitlement.state pattern:
a plain enum with conditional required rules expressed as separate allOf[]
if/then entries (ACTIVE requires coordinationId + targetCriteria; BOOKING_CONFIRMED
requires targetBookingRef).handoverDocument — a generic, credential-scoped reference: artifactRef is a
label resolving to a Document in the contract’s Descriptor.docs[]; the URL lives in
the core Document, never in this field. credentialScope is a plain credential id / DID.deviation — the in-band, protocol-carried deviation signal; its reasonCode is a
self-owned CodedValue. The out-of-band registry record is a separate concern (IG).CANCELLED vs WITHDRAWN — both are subject-initiated terminations, distinguished by
whether a downstream booking exists: CANCELLED applies before any T2 booking (nothing to
unwind); WITHDRAWN applies after a T2 booking is confirmed and therefore obliges the
coordinator to unwind/cancel the downstream (T2) booking.notificationRoster ordering — modelled with JSON-LD @container: @list (ordered, unlike
the @set arrays elsewhere): roster order is significant and conveys notification / escalation
priority. Consumers should preserve and honour the order.ServiceCoordinationResource)ServiceCoordinationOffer)Self-owned coded fields (deviation.reasonCode, targetCriteria.serviceCategory) use the pinned typed-CodedValue pattern (const @type, open/defaulted @context). Resolution of a code to its value set, and value-set extension by another network, follow the CodedValue resolution & extension convention (under discussion).
Small, schema-owned, operational/structural value sets — lifecycleState, targetCriteria.urgencyTier, handoverDocument.revocationStatus, notificationRoster[].partyRole / .notificationScope — are deliberately plain enums, not CodedValues, per that convention’s thumb rule (closed, network-owned sets stay plain enums).
UrgencyTier (ROUTINE / URGENT / EMERGENCY) appears as a parallel RDF class in all three packs — scoord:UrgencyTier (this contract), scres:UrgencyTier (ServiceCoordinationResource) and scoff:UrgencyTier (ServiceCoordinationOffer). On the wire it is a plain string enum, so there is no wire-level identity concern. At the semantic-graph layer the three classes are intentionally separate but equivalent: scoord:UrgencyTier is the shared anchor, and the scres: / scoff: members carry skos:exactMatch links back to it. This is the decentralised-vocabulary model in miniature — each pack owns its vocabulary and equivalence is published, not centrally mandated. Cross-pack reconciliation is an analytics/semantic-layer concern.
profile.json lists targetCriteria.urgencyTier as a filterable path. It is a scalar enum (not a CodedValue array), so this is an ordinary nested-scalar filter; whether a given gateway supports nested-path filtering is a deployment capability.