contract.negotiation.protocol.md

Contract Negotiation Protocol

This document outlines the key elements of the Contract Negotiation Protocol. The used terms are described here.

• Contract Negotiation Protocol
  • 1 Introduction
    • 1.1 States
    • 1.2 State Machine
  • 2 Message Types
    • 2.1 Contract Request Message
    • 2.2 Contract Offer Message
    • 2.3 Contract Agreement Message
    • 2.4 Contract Agreement Verification Message
    • 2.5 Contract Negotiation Event Message
    • 2.6 Contract Negotiation Termination Message
  • 3 Response Types
    • 3.1 ACK - Contract Negotiation
    • 3.2 ERROR - Contract Negotiation Error

1 Introduction

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.

1.1 States

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 CN 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.

1.2 State Machine

The CN state machine is represented in the following diagram:

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.

2 Message Types

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., Contract Negotiation HTTPS Binding..
• All Policy types (Offer, Agreement) must contain an 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.

2.1 Contract Request Message

Sent by	Consumer
Resulting state	REQUESTED, TERMINATED
Response	ACK or ERROR
Schema	TTL Shape, JSON Schema
Example	Initiating Message, Message
Diagram(s)

The Contract Request Message is sent by a Consumer to initiate a CN or to respond to a Contract Offer Message sent by a Provider.

• The Consumer must include an offer property, which itself must have a @id property. If the message includes a providerPid property, the request will be associated with an existing CN and a Consumer Offer will be created using either the offer or offer.@id properties. If the message does not include a providerPid, a new CN will be created on Provider side using either the offer or offer.@id properties and the Provider selects an appropriate providerPid.
• An offer.@id will generally refer to an Offer contained in a Catalog. If the Provider is not aware of the offer.@id value, it must respond with an error message.
• The callbackAddress is 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.
• Different to a Catalog or Dataset, the Offer inside a Contract Request Message must have an odrl:target attribute. However, it's contained Rules must not have any odrl:target attributes to prevent inconsistencies with the ODRL inferencing rules for compact policies.

2.2 Contract Offer Message

Sent by	Provider
Resulting state	OFFERED, TERMINATED
Response	ACK or ERROR
Schema	TTL Shape, JSON Schema
Example	Example Initial Message, Example Message
Diagram(s)	Initial message (note the missing consumerPid) Message following a Contract Request Message:

The Contract Offer Message is sent by a Provider to initiate a CN or to respond to a Contract Request Message sent by a Consumer.

• If the message includes a consumerPid property, the request will be associated with an existing CN. If the message does not include a consumerPid, a new CN 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 CN.
• Different to a Dataset (see DCAT Vocabulry Mapping), the Offer inside a ContractOfferMessage must have an odrl:target attribute. However, it's contained Rules must not have any odrl:target attributes to prevent inconsistencies with the ODRL inferencing rules for compact policies.

2.3 Contract Agreement Message

Sent by	Provider
Resulting state	AGREED, TERMINATED
Response	ACK or ERROR
Schema	TTL Shape, JSON Schema
Example	Message
Diagram(s)

The Contract Agreement Message is sent by a Provider when it agrees to a contract. It contains the complete Agreement.

• The message must contain a consumerPid and a providerPid.
• The message must contain an ODRL Agreement.
• An Agreement must contain a timestamp property defined as an XSD DateTime type.
• An Agreement must contain an assigner and assignee. 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 (e.g., Connectors).
• An Agreement must contain a odrl:target property. None of its Rules, however, must have any odrl:target attributes to prevent inconsistencies with the ODRL inferencing rules for compact policies.

2.4 Contract Agreement Verification Message

Sent by	Consumer
Resulting state	VERIFIED, TERMINATED
Response	ACK or ERROR
Schema	TTL Shape, JSON Schema
Example	Message
Diagram(s)

The Contract Agreement Verification Message 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.
• The message must contain a consumerPid and a providerPid.

2.5 Contract Negotiation Event Message

Sent by	Consumer, Provider
Resulting state	FINALIZED, ACCEPTED, TERMINATED
Response	ACK or ERROR
Schema	TTL Shape, JSON Schema
Example	Message
Diagram(s)

When the Contract Negotiation Event Message 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.
• The message must contain a consumerPid and a providerPid.
• When the message 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 Consumer to send the message with an event type FINALIZED to the Provider.
• It is an error for a Provider to send the message with an event type ACCEPTED to the Consumer.

Note that CN events are not intended for propagation of an Agreement state after a CN has entered a terminal state. It is considered an error for a Consumer or Provider to send an event after the CN state machine has entered a terminal state.

2.6 Contract Negotiation Termination Message

Sent by	Consumer, Provider
Resulting state	TERMINATED
Response	ACK or ERROR
Schema	TTL Shape, JSON Schema
Example	Message
Diagram(s)

The Contract Negotiation Termination Message is sent by a Consumer or Provider indicating it has cancelled the CN sequence. The message can be sent at any state of a CN without providing an explanation. Nevertheless, the sender may provide a description to help the receiver.

• The message must contain a consumerPid and a providerPid.
• If an error is received in response to the message, the sending party may choose to ignore the error.

Note that a CN 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 CN resources after it has reached the terminated state.

3 Response Types

The ACK and ERROR response 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.

3.1 ACK - Contract Negotiation

Sent by	Consumer, Provider
Schema	TTL Shape, JSON Schema
Example	Process
Diagram(s)

The Contract Negotiation is an object returned by a Consumer or Provider indicating a successful state change happened.

3.2 ERROR - Contract Negotiation Error

Sent by	Consumer, Provider
Schema	TTL Shape, JSON Schema
Example	Error
Diagram(s)

The Contract Negotiation Error is an object returned by a Consumer or Provider indicating an error has occurred. It does not cause a state transition.

Field	Type	Description
consumerPid	UUID	The CN unique id on Consumer side.
providerPid	UUID	The CN unique id on Provider side.
code	String	An optional implementation-specific error code.
reason	Array[object]	An optional array of implementation-specific error objects.