This document outlines the key elements of the Contract Negotiation Protocol. The following terms are used:
- A message type defines the structure of a message.
- A message is an instantiation of a message type.
- The contract negotiation protocol is the set of allowable message type sequences and is defined as a state machine (CNP-SM).
- A contract negotiation (CN) is an instantiation of the CNP-SM.
- A provider is a Participant Agent that offers a Dataset.
- A consumer is a Participant Agent that requests access to an offered Dataset.
A Contract Negotiation (CN) involves two parties, a provider that offers one or more Datasets under a usage contract and consumer that requests Datasets. A CN is uniquely identified through an IRI. Each CN requires a newly generated IRI, which may not be used in a CN after a terminal state has been reached. A CN progresses through a series of states, which are tracked by the provider and consumer using messages. A CN transitions to a state in response to an acknowledged message from the counter-party. Both parties have the same state of the CN. In case the states differ, the CN is terminated and a new CN has to be initiated.
The CN states are:
- REQUESTED - A contract for a Dataset has been requested by the consumer based on an Offer and the provider has sent an ACK response.
- OFFERED - The provider has sent an Offer to the consumer and the consumer has sent an ACK response.
- ACCEPTED - The consumer has accepted the latest Offer and the provider has sent an ACK response.
- AGREED - The provider has accepted the latest Offer, sent an Agreement to the consumer, and the consumer has sent an ACK response.
- VERIFIED - The consumer has sent an Agreement verification to the provider and the provider has sent an ACK response.
- FINALIZED - The provider has sent a finalization message including his own Agreement verification to the consumer and the consumer has sent an ACK response. Data is now available to the consumer.
- TERMINATED - The provider or consumer has placed the Contract Negotiation in a terminated state. A termination message has been sent by either of the Participants and the other has sent an ACK response. This is a terminal state.
The CN state machine is represented in the following diagram. Note that transitions to the TERMINATED state may occur from any other state and are not shown for simplicity:
Transitions marked with C indicate a message sent by the consumer, transitions marked with P indicate a provider message. Terminal states are final; the state machine may
not transition to another state. A new CN may be initiated if, for instance, the CN entered the TERMINATED state due to a network issue.
The CN state machine is transitioned upon receipt and acknowledgement of a message. This section details those messages as abstract message types.
- Concrete wire formats are defined by the protocol binding, e.g. HTTPS.
- All Policy types (Offer, Agreement) must contain a unique identifier in the form of a URI. GUIDs can also be used in the form of URNs, for instance following the pattern urn:uuid:{GUID}.
- An ODRL Agreement must have a target property containing the Dataset id.
Sent by: Consumer
Resulting State: REQUESTED, TERMINATED
Example: Initiating ContractRequestMessage, ContractRequestMessage
Response: ACK or ERROR.
Schema: ContractRequestMessageShape, ContractRequestMessage JSON Schema, ContractNegotiationShape and ContractNegotiation JSON Schema
The ContractRequestMessage is sent by a consumer to initiate a Contract Negotiation or to respond to a ContractOfferMessage sent by a provider.
-
The consumer must include an
offerproperty, which itself must have a@idproperty. If the message includes aproviderPidproperty, the request will be associated with an existing Contract Negotiation and a consumer Offer will be created using either theofferoroffer.@idproperties. If the message does not include aproviderPid, a new Contract Negotiation will be created on provider side using either theofferoroffer.@idproperties and the provider selects an appropriateproviderPid. -
An
offer.@idwill generally refer to an Offer contained in a Catalog. If the provider is not aware of theoffer.@idvalue, it must respond with an error message. -
The Dataset id is not technically required but included to avoid an error where the Offer is associated with a different data set.
-
callbackAddressis a URL indicating where messages to the consumer should be sent in asynchronous settings. If the address is not understood, the provider MUST return an UNRECOVERABLE error.
Sent by: Provider
Resulting State: OFFERED, TERMINATED
Example: Initiating ContractOfferMessage, ContractOfferMessage
Response: ACK or ERROR.
Schema: ContractOfferMessageShape and ContractOfferMessage JSON Schema
The ContractOfferMessage is sent by a provider to initiate a Contract Negotiation or to respond to a ContractRequestMessage sent by a consumer.
If the message includes a consumerPid property, the request will be associated with an existing Contract Negotiation. If the message does not include a consumerPid, a new Contract Negotiation
will be created on consumer side and the consumer selects an appropriate consumerPid.
- The Dataset id is not required but can be included when the provider initiates a Contract Negotiation.
Sent by: Provider
Resulting State: AGREED, TERMINATED
Example: ContractAgreementMessage
Response: ACK or ERROR.
Schema: ContractAgreementMessageShape and ContractAgreementMessage JSON Schema
The ContractAgreementMessage is sent by a provider when it agrees to a contract. It contains the complete Agreement.
A ContractAgreementMessage must contain a consumerPid and a providerPid.
A ContractAgreementMessage must contain an ODRL Agreement.
An Agreement must contain a dspace:timestamp property defined as an XSD DateTime type.
An Agreement must contain a dspace:consumerId and dspace:providerId. The contents of these
properties are a Dataspace-specific unique identifier of the Agreement parties. Note that these
identifiers are not necessarily the same as the identifiers of the Participant Agents negotiating the
contract (i.e. the Connectors).
Sent by: Consumer
Resulting State: VERIFIED, TERMINATED
Example: ContractAgreementVerificationMessage
Response: ACK or ERROR.
Schema: ContractAgreementVerificationMessageShape and the ContractAgreementVerificationMessage JSON Schema
The ContractAgreementVerificationMessage is sent by a consumer to verify the acceptance of an Agreement. A provider responds with an error if the contract cannot be
validated or is incorrect.
A ContractAgreementVerificationMessage must contain a consumerPid and a providerPid.
Sent by: Provider or Consumer
Resulting State: FINALIZED, ACCEPTED, TERMINATED
Example: ContractNegotiationEventMessage
Response: ACK or ERROR.
Schema: ContractNegotiationEventMessageShape and the ContractNegotiationEventMessage JSON Schema
When the ContractNegotiationEventMessage is sent by a provider with an eventType property set to FINALIZED, an Agreement has been finalized and the associated Dataset
is accessible. The state machine is transitioned to the FINALIZED state. Other event types may be defined in the future. A consumer responds with an error if the contract
cannot be validated or is incorrect.
It is an error for a consumer to send a ContractNegotiationEventMessage with an eventType FINALIZED to the provider.
When the ContractNegotiationEventMessage is sent by a consumer with an eventType set to ACCEPTED, the state machine is placed in the ACCEPTED state.
It is an error for a provider to send a ContractNegotiationEventMessage with an eventType ACCEPTED to the consumer.
Note that Contract Negotiation events are not intended for propagation of Agreement state after a Contract Negotiation has entered a terminal state. It is considered an error for a consumer or provider to send an event after the Contract Negotiation's state machine has entered a terminal state.
A ContractNegotiationEventMessage must contain a consumerPid and a providerPid.
Sent by: Consumer or Provider
Resulting State: TERMINATED
Example: ContractNegotiationTerminationMessage
Response: ACK or ERROR.
Schema: ContractNegotiationTerminationMessageShape and the ContractNegotiationTerminationMessage JSON Schema
The ContractNegotiationTerminationMessage is sent by a consumer or provider indicating it has cancelled the Contract Negotiation sequence. The message can be sent at any state of a Contract Negotiation
without providing an explanation. Nevertheless, the sender may provide a description to help the receiver.
A ContractNegotiationTerminationMessage must contain a consumerPid and a providerPid.
-
A Contract Negotiation may be terminated for a variety of reasons, for example, an unrecoverable error was encountered or one of the parties no longer wishes to continue. A Connector's operator may remove terminated Contract Negotiation resources after it has reached the terminated state.
-
If an error is received in response to a
ContractNegotiationTerminationMessage, the sending party may choose to ignore the error.
- The
ACKandERRORresponse message types are mapped onto a protocol such as HTTPS. A description of an error might be provided in protocol-dependent forms, e.g. for an HTTPS binding in the request or response body.
Sent by: Consumer or Provider
Example: ContractNegotiation
Schema: ContractNegotiationShape and the ContractNegotiationErrorMessage JSON Schema
The ContractNegotiation is an object returned by a consumer or provider indicating a successful state change happened.
Sent by: Consumer or Provider
Example: NegotiationError
Schema: ContractNegotiationErrorShape and the ContractNegotiationErrorMessage JSON Schema
The ContractNegotiationError is an object returned by a consumer or provider indicating an error has occurred. It does not cause a state transition.