Specification

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

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:

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.

2.1 Contract Request Message

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

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

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

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

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

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

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

3.2 ERROR - Contract Negotiation Error

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.

Last updated

© 2016 – 2024 | All Rights Reserved | International Data Spaces Association