OpenFreyt Protocol — Normative Glossary
Generated from
specification/glossary.md. Edit the canonical source file, not this page.
Status: Normative
Version: 1.0.0-draft
Locked by: M001-S01-T01
This glossary is the single authoritative vocabulary for all OpenFreyt Protocol (PCX) specification documents, schemas, conformance tests, and implementations. Terms defined here MUST be used exactly as specified. Where a term has a restricted meaning within PCX that differs from everyday usage, the PCX definition governs.
1. Locked Vocabulary Decisions
Section titled “1. Locked Vocabulary Decisions”The following four decisions were open questions in PROTOCOL.md §15. They are now permanently locked; downstream slices MAY NOT reopen them without a new ADR and milestone-level re-planning.
1.1 Decision A — Vehicle / Body-Type Vocabulary
Section titled “1.1 Decision A — Vehicle / Body-Type Vocabulary”Resolution: Closed enum drawn from the UNECE Recommendation 28 subset, with a namespaced extension escape hatch.
Canonical enum members:
| Member | Description |
|---|---|
tautliner |
Curtain-sided trailer with taut curtain system |
curtainsider |
Curtain-sided trailer (general) |
box |
Rigid box body (dry) |
refrigerated |
Temperature-controlled enclosure |
flatbed |
Flat platform without sides |
tanker |
Liquid or gas bulk container |
bulk |
Open-top bulk commodity carrier |
heavy-lift |
Specialized heavy / over-dimensional equipment |
low-loader |
Low-bed trailer for oversized cargo |
swap-body |
Interchangeable swap-body unit (BIC/EN 284) |
Extension escape hatch: any value prefixed extension: (e.g.
extension:walking-floor) is valid and MUST NOT be rejected by conformant
implementations. Schema validators MUST accept the pattern
^extension:[a-z0-9][a-z0-9-]*$. Proprietary extensions are broker-scoped and
carry no cross-broker interoperability guarantee.
1.2 Decision B — Area Representation
Section titled “1.2 Decision B — Area Representation”Resolution: GeoJSON RFC 7946 geometry object — either a Point (with an
added radiusKm property) or a Polygon — plus an optional
adminRegionCode field for administrative region lookup.
Canonical area object fields:
| Field | Type | Required | Description |
|---|---|---|---|
geometry |
GeoJSON Point or Polygon |
yes | RFC 7946 geometry object |
radiusKm |
number (positive) |
only when geometry is Point |
Radius in kilometres around the point |
adminRegionCode |
string |
no | ISO 3166-1 alpha-2 country code, optionally suffixed with ISO 3166-2 subdivision code (e.g. DE, DE-BY) |
A Polygon geometry MUST follow RFC 7946 §3.1.6 (exterior ring
counter-clockwise, holes clockwise; first and last positions identical).
radiusKm MUST be omitted or null when geometry is Polygon.
1.3 Decision C — Organization Identity
Section titled “1.3 Decision C — Organization Identity”Resolution: Organization identity is an opaque, broker-scoped string
(organizationId). An optional structured legalIdentifier object provides
cross-system linkage without coupling the protocol to a single registry.
organizationId: opaque string, max 255 characters, broker-assigned.
Uniqueness is scoped to the issuing broker service.
legalIdentifier object fields:
| Field | Type | Required | Description |
|---|---|---|---|
type |
"GLN" | "EORI" | "DUNS" | "custom" |
yes | Legal identifier namespace |
value |
string |
yes | Identifier value within the namespace |
type: "custom" is reserved for national or sector-specific registries. When
type is "custom" a customTypeLabel string field SHOULD be provided.
1.4 Decision D — Decision Policy
Section titled “1.4 Decision D — Decision Policy”Resolution: Match-decision behaviour is governed by a decisionPolicy
enum. The default is BILATERAL_REQUIRED.
| Value | Semantics |
|---|---|
BILATERAL_REQUIRED |
A MatchProposal reaches accepted only when both the capacity owner and the load owner have accepted. Default. |
INITIATOR_ONLY |
Only the broker service or the party that created the MatchProposal must accept; the other party’s decision is advisory only. |
ACCEPTOR_ONLY |
Only the non-initiating party must explicitly accept; the initiating party’s acceptance is implicit on proposal creation. |
decisionPolicy is a property of MatchProposal. Its value MUST NOT
change after the proposal is created.
2. Common Envelope
Section titled “2. Common Envelope”Every PCX resource carries the following CommonEnvelope fields. These fields are defined once here and inherited by all seven core resource types.
| Field | Type | Required | Description |
|---|---|---|---|
id |
UUIDv7 string | yes | Globally unique resource identifier. MUST be a valid UUIDv7 (RFC 9562 §5.7). Monotonically increasing time prefix enables ordered pagination. |
resourceVersion |
integer ≥ 1 |
yes | Monotonic optimistic-concurrency counter. Incremented on every mutation. Consumers MUST treat a version gap > 1 as a missed-event signal. |
ownerOrganizationId |
string |
yes | Broker-scoped organizationId of the organization that owns this resource. Authorization checks compare this field. |
createdAt |
ISO 8601 UTC datetime | yes | Instant the resource was first persisted. MUST NOT change after creation. |
updatedAt |
ISO 8601 UTC datetime | yes | Instant of the last mutation. Equal to createdAt on first write. |
externalReferences |
array of ExternalReference |
no | Optional list of cross-system pointers (TMS order IDs, ERP references, etc.). |
ExternalReference object fields:
| Field | Type | Required | Description |
|---|---|---|---|
system |
string |
yes | Identifier for the external system (e.g. "sap-tm", "samsara") |
referenceId |
string |
yes | The ID or key in that system |
url |
string (URI) |
no | Optional deep-link URL |
3. Core Resources
Section titled “3. Core Resources”PCX defines exactly seven core resources. All inherit CommonEnvelope.
3.1 PartnerRelationship
Section titled “3.1 PartnerRelationship”A bilateral agreement between two organizations, established within a single broker service, that enables capacity and load data exchange.
Canonical additional fields:
| Field | Type | Description |
|---|---|---|
initiatorOrganizationId |
string |
Organization that sent the invitation |
acceptorOrganizationId |
string |
Organization that received the invitation |
decisionPolicy |
DecisionPolicy |
Default decision policy for matches within this relationship |
permittedScopes |
string[] |
Scopes explicitly granted within this relationship |
invitedAt |
datetime | When the invitation was sent |
activatedAt |
datetime | null | When both parties accepted |
Lifecycle states:
| State | Meaning |
|---|---|
pending |
Invitation sent; acceptor has not yet responded |
active |
Both parties have accepted; data exchange is permitted |
suspended |
Temporarily disabled; no new matches may be created |
terminated |
Permanently closed; all associated data becomes read-only |
3.2 CapacityOffer
Section titled “3.2 CapacityOffer”An offer of available transport capacity published by a carrier organization.
Canonical additional fields:
| Field | Type | Description |
|---|---|---|
vehicleBodyType |
VehicleBodyType |
Body type (see §1.1) |
vehicleCount |
integer ≥ 1 |
Number of vehicles available |
originArea |
Area |
Geographic origin area (see §1.2) |
destinationArea |
Area |
Geographic destination area |
availableFrom |
datetime | Earliest loading readiness |
availableUntil |
datetime | Latest departure window close |
capacityWeightKg |
number |
Max payload weight in kilograms |
capacityVolumeM3 |
number | null |
Max payload volume in cubic metres |
publishedAt |
datetime | null | When the offer was made visible |
Lifecycle states:
| State | Meaning |
|---|---|
draft |
Created but not visible to partners |
published |
Visible to authorized partners; eligible for matching |
partiallyMatched |
At least one match proposal exists; capacity partially allocated |
matched |
Fully allocated; no further matches accepted |
withdrawn |
Owner removed before expiry; no longer matchable |
expired |
availableUntil passed without full allocation |
cancelled |
Administratively cancelled by broker service |
3.3 LoadRequest
Section titled “3.3 LoadRequest”A request for transport capacity published by a shipper or freight forwarder.
Canonical additional fields:
| Field | Type | Description |
|---|---|---|
requiredBodyType |
VehicleBodyType |
Required vehicle body type |
originArea |
Area |
Pick-up area |
destinationArea |
Area |
Delivery area |
readyAt |
datetime | Cargo ready for pick-up |
deliverBy |
datetime | Required delivery deadline |
cargoWeightKg |
number |
Cargo weight in kilograms |
cargoVolumeM3 |
number | null |
Cargo volume in cubic metres |
hazmat |
boolean |
Whether cargo is hazardous (ADR) |
publishedAt |
datetime | null | When the request was made visible |
Lifecycle states: identical to CapacityOffer (draft, published,
partiallyMatched, matched, withdrawn, expired, cancelled).
3.4 MatchProposal
Section titled “3.4 MatchProposal”A broker-generated proposal linking one CapacityOffer to one LoadRequest.
Canonical additional fields:
| Field | Type | Description |
|---|---|---|
capacityOfferId |
UUIDv7 | Referenced CapacityOffer |
loadRequestId |
UUIDv7 | Referenced LoadRequest |
proposedAt |
datetime | When the broker created the proposal |
expiresAt |
datetime | Decision deadline |
decisionPolicy |
DecisionPolicy |
Policy governing acceptance (see §1.4) |
capacityOwnerDecision |
PartyDecision | null |
Capacity owner’s current decision |
loadOwnerDecision |
PartyDecision | null |
Load owner’s current decision |
Lifecycle states:
| State | Meaning |
|---|---|
open |
Proposal created; awaiting decisions per decisionPolicy |
accepted |
Decision policy satisfied; MatchDecision record created |
rejected |
At least one required party explicitly rejected |
expired |
expiresAt passed before policy was satisfied |
superseded |
A newer proposal for the same pair was created |
withdrawn |
Broker or initiating party withdrew before decision |
3.5 MatchDecision
Section titled “3.5 MatchDecision”The authoritative record that a MatchProposal reached accepted state.
Created automatically when the proposal transitions to accepted.
Canonical additional fields:
| Field | Type | Description |
|---|---|---|
matchProposalId |
UUIDv7 | The accepted MatchProposal |
capacityOfferId |
UUIDv7 | Denormalized for query efficiency |
loadRequestId |
UUIDv7 | Denormalized for query efficiency |
decidedAt |
datetime | Instant the policy was satisfied |
executionReferenceId |
UUIDv7 | null | Link to ExecutionReference when created |
Lifecycle states:
| State | Meaning |
|---|---|
active |
Decision stands; execution may proceed |
cancelled |
Decision voided (mutual cancellation or compliance override) |
disputed |
Under formal dispute resolution |
3.6 ExecutionReference
Section titled “3.6 ExecutionReference”A lightweight operational record that tracks real-world execution of a
matched transport. Created after MatchDecision reaches active.
Canonical additional fields:
| Field | Type | Description |
|---|---|---|
matchDecisionId |
UUIDv7 | Source MatchDecision |
scheduledPickupAt |
datetime | Planned pick-up time |
scheduledDeliveryAt |
datetime | Planned delivery time |
carrierReference |
string | null |
Carrier’s own shipment reference |
Lifecycle states:
| State | Meaning |
|---|---|
planned |
Not yet started; no driver/vehicle assigned |
inProgress |
Pick-up confirmed; shipment moving |
completed |
Delivery confirmed |
cancelled |
Transport cancelled after execution started |
disputed |
Execution facts under dispute |
3.7 ExecutionOutcome
Section titled “3.7 ExecutionOutcome”The final verified record of transport completion, supporting audit, payment, and compliance review.
Canonical additional fields:
| Field | Type | Description |
|---|---|---|
executionReferenceId |
UUIDv7 | Source ExecutionReference |
actualPickupAt |
datetime | null | Actual pick-up time |
actualDeliveryAt |
datetime | null | Actual delivery time |
proofOfDeliveryUrl |
string (URI) | null | Link to POD document |
complianceReviewStatus |
ComplianceReviewStatus |
Status of compliance review |
reviewedBy |
string | null |
organizationId of reviewer |
reviewedAt |
datetime | null | When compliance review was completed |
Lifecycle states:
| State | Meaning |
|---|---|
pending |
Execution complete; awaiting outcome submission |
submitted |
Outcome submitted; pending compliance review |
approved |
Compliance review passed |
rejected |
Compliance review failed; resubmission required |
disputed |
Outcome facts under formal dispute |
4. Authorization Scopes
Section titled “4. Authorization Scopes”PCX defines exactly nine authorization scopes. All scopes are broker-scoped: a token issued by broker A grants no rights on broker B.
| Scope | Resource(s) | Description |
|---|---|---|
relationships:manage |
PartnerRelationship | Create, update, suspend, and terminate partner relationships |
capacity:publish |
CapacityOffer | Create and mutate own CapacityOffers; withdraw or cancel |
capacity:read |
CapacityOffer | Read CapacityOffers where authorized by a PartnerRelationship |
loads:publish |
LoadRequest | Create and mutate own LoadRequests; withdraw or cancel |
loads:read |
LoadRequest | Read LoadRequests where authorized by a PartnerRelationship |
matches:read |
MatchProposal, MatchDecision | Read match proposals and decisions for own resources |
matches:decide |
MatchProposal | Submit accept/reject decisions on MatchProposals |
outcomes:write |
ExecutionReference, ExecutionOutcome | Create and update execution records |
outcomes:review |
ExecutionOutcome | Perform compliance review on ExecutionOutcomes |
5. Roles
Section titled “5. Roles”| Role | Description |
|---|---|
BrokerService |
The platform operating a PCX broker node. Issues tokens, enforces authorization, owns relationship lifecycle. |
OrganizationService |
A machine client (TMS, ERP integration) acting on behalf of an organization. Uses OAuth 2.0 client credentials. |
OrganizationMember |
A human user affiliated with an organization. Uses OAuth 2.0 authorization-code flow. |
ComplianceReviewer |
A human or service that performs outcomes:review operations. May be affiliated with the BrokerService. |
6. General Terms
Section titled “6. General Terms”| Term | Definition |
|---|---|
| PCX | OpenFreyt Protocol — Partner Capacity Exchange. The name of this protocol. |
| Broker | An entity that operates a PCX-conformant platform service connecting multiple transport organizations. |
| UUIDv7 | A UUID as defined in RFC 9562 §5.7. Encodes a 48-bit Unix millisecond timestamp prefix for monotonic ordering. |
| Invariant | A condition that MUST hold at all times for the system to be in a valid state. Invariants are defined in requirements/invariants.yaml. |
| Idempotency key | A caller-supplied string that allows safe retry of mutating requests without duplication. |
| Monotonic resourceVersion | The resourceVersion integer on a resource. Each mutation MUST increment it by exactly 1. |
| Optimistic concurrency | A write strategy where the caller supplies the expected resourceVersion; the server rejects with HTTP 409 if the current version differs. |
| Pre-match | The lifecycle phase before a MatchDecision exists. Certain sensitive fields (e.g. exact price, carrier identity) are suppressed during pre-match per R-005. |
| Post-match | The lifecycle phase after a MatchDecision is active. Full field disclosure is permitted to authorized parties. |
| 404-vs-403 rule | When a requester lacks authorization to know a resource exists, the server MUST return HTTP 404 (not 403) to prevent resource enumeration. Defined in R-001. |
| Field-level disclosure | The controlled reveal of sensitive resource fields based on lifecycle phase and authorization scope. Governed by the authorization matrix. |
| Relationship-gated | An operation or data access that requires an active PartnerRelationship between the requesting organization and the resource-owning organization. |
| PartyDecision | An object recording one party’s accept or reject decision on a MatchProposal, with decision ("accept" | "reject"), decidedAt, and optional note fields. |
| ComplianceReviewStatus | Enum: pending | approved | rejected | waived. Used on ExecutionOutcome. |
| ADR | Architecture Decision Record. Stored under docs/adr/. Normative; referenced by decision IDs in this glossary and the authorization matrix. |
| Conformant implementation | A broker service that passes all PCX conformance tests defined in conformance/. |
| Extension scope | Any value matching ^extension:[a-z0-9][a-z0-9-]*$ in an enum field. Conformant implementations MUST accept extension values without rejecting the message. |
| Stale event | An event whose resourceVersion is lower than the last known version for that resource ID. Consumers MUST discard stale events without side effects. |
| Double commitment | The race condition where two concurrent match operations claim the same capacity or load. Protected by optimistic concurrency and idempotency keys. |
| Audit trail | The immutable append-only log of all state transitions for PCX resources. Required by compliance and non-repudiation requirements. |