Skip to content

Provide non-normative examples of state transitions and adjust state description #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Provide non-normative examples of state transitions and adjust state description #138

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d8c3b3a
Remove constricting CN state descriptions, to fit to all transitions
SebastianOpriel Aug 4, 2023
427957a
Add table to give non-normative examples of state transitions
SebastianOpriel Aug 4, 2023
96bb0f8
Update negotiation/contract.negotiation.protocol.md
SebastianOpriel Aug 10, 2023
0b829b6
Update negotiation/contract.negotiation.protocol.md
SebastianOpriel Aug 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions negotiation/contract.negotiation.protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ the counter-party. Both parties have the same state of the CN. In case the state

The CN states are:

- **REQUESTED** - A contract for an asset has been requested by the consumer based on an offer and the provider has sent an ACK response.
- **REQUESTED** - A contract for an asset has been requested by the consumer and the provider has sent an ACK response.
- **OFFERED** - The provider has sent a contract offer to the consumer and the consumer has sent an ACK response.
- **ACCEPTED** - The consumer has accepted the latest contract offer and the provider has sent an ACK response.
- **AGREED** - The provider has accepted the latest contract offer, sent an agreement to the consumer, and the consumer has sent an ACK response.
- **AGREED** - The provider has 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.
Expand All @@ -39,6 +39,21 @@ The CN state machine is represented in the following diagram. Note that transiti
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.

Following table gives non-normative examples of transitions:

| Origin State | Actor | Message | Target State | Non-normative Example |
|----------------------------|--------|-------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| INIT | C | ContractRequestMessage | REQUESTED | The consumer requests a contract, without previous direct interaction with provider, e.g. through the usage of a central cataloging system, which provides all necessary information about the provider, to directly request a data contract. |
Copy link
Contributor

@juliapampus juliapampus Aug 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Too specific. We should never name components in this specs, like "central cataloging system", not even in non-normative documents. In addition, this is a wrong statement. This transition indeed can be base on previous interactions between consumer & provider.

With this we leave it open:

Suggested change
| INIT | C | ContractRequestMessage | REQUESTED | The consumer requests a contract, without previous direct interaction with provider, e.g. through the usage of a central cataloging system, which provides all necessary information about the provider, to directly request a data contract. |
| INIT | C | ContractRequestMessage | REQUESTED | The consumer requests a contract, based on a previously requested dataset or catalog containing a provider's contract offer . |

or

Suggested change
| INIT | C | ContractRequestMessage | REQUESTED | The consumer requests a contract, without previous direct interaction with provider, e.g. through the usage of a central cataloging system, which provides all necessary information about the provider, to directly request a data contract. |
| INIT | C | ContractRequestMessage | REQUESTED | The consumer requests a contract, based on a previously requested dataset or catalog from a catalog service. |

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be "The consumer requests a contract based for a dataset" since "a previously requested dataset or catalog" is not defined.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As we want to give the reader an idea, that such dataset can be identified out of scope of the procool, I suggest: "The consumer requests a contract for a data set that has been brought to his attention outside the scope of the Protocol."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's also not entirely accurate. The consumer could make up a contract offer for an existing data set. These types of explanations are best done in a separate, non-normative document. Examples like this are valuable but should not be in this document. Per my comment below about the role of specifications, they have no bearing on how an implementor must ensure correct protocol behavior.

| INIT | P | ContractOfferMessage | OFFERED | The provider sends a contract offer directly to a consumer without previous interaction, e.g. because the provider knows about desired data (e.g., consumer placed a search for data request in a catalog) or consumer/provider are in an existing business relationship and provider wants to ship information to its business partner. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You state "without previous interaction" and in the same sentence name business relationships.

Suggested change
| INIT | P | ContractOfferMessage | OFFERED | The provider sends a contract offer directly to a consumer without previous interaction, e.g. because the provider knows about desired data (e.g., consumer placed a search for data request in a catalog) or consumer/provider are in an existing business relationship and provider wants to ship information to its business partner. |
| INIT | P | ContractOfferMessage | OFFERED | The provider sends a contract offer to a consumer, e.g., in the context of an existing business relationship. |

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should read "The provider sends a contract offer to a consumer" as an "existing business relationship" is undefined.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point is, that we add the table especially for a more explanatory non-normative content. Stripping away all examples, brings the table back to a normative state and gets obsolete, as the diagram explains the transitions quite well. Thus, I would prefer @juliapampus suggestion

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see how that is more explanatory, as "context" and "existing business relationship" are vague terms. What is a "business relationship," and what is a "business context"? Those are completely open-ended.

The purpose of the specification is not to explain how DSP may be used. IMO, the specification should explain to implementors what the correct protocol behaviors are and stop there. It is a normative document, not an explanation of how to implement a dataspace or how dataspace technologies may solve project requirements.

Those are fine goals, but they should be addressed in "architecture/primer/whitepaper" documents.

I also disagree with including the following types of statements:

The consumer requests a contract, without previous direct interaction with provider, e.g. through the usage of a central cataloging system, which provides all necessary information about the provider, to directly request a data contract.

Besides being an implementation detail, the DSP catalog protocol is designed to enable decentralized catalog designs (it mentions this and explicitly does not define a replication protocol).

| REQUESTED | P | ContractOfferMessage | OFFERED | The provider sends an offering for a requested resource. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Naming

Suggested change
| REQUESTED | P | ContractOfferMessage | OFFERED | The provider sends an offering for a requested resource. |
| REQUESTED | P | ContractOfferMessage | OFFERED | The provider sends a (counter) contract offer for a requested dataset, based on a previous contract request. |

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two things related things. "Counter" is not defined. I don't think we need "based on a previous contract request" because that is also ambiguous ("based on" is not defined). I would simply state "The provider sends a contract offer." The contract offer by definition is in the context of the contract negotiation but we could also state it explicitly, "The provider sends a contract offer for the referenced contract negotiation"

Copy link
Member Author

@SebastianOpriel SebastianOpriel Aug 11, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jimmarino

The provider sends a contract offer for the referenced contract negotiation

I would add "[...] contract negotiation process", to have a textual linking to the processId.

@juliapampus

The provider sends a (counter) contract offer for a requested dataset, based on a previous contract request.

We might not have a dataset here, since INIT -> OFFERED is possible. So in general: How can the consumer decide, if the offer shall be accepted without a reference to a dataset? A ContractOfferMessage just has processId, offer and callbackAddress. Is it possible that this edge may not be effective?

| REQUESTED | P | ContractAgreementMessage | AGREED | The provider sends a contract agreement after a successful validation of the consumer's contract request. |
| OFFERED | C | ContractRequestMessage | REQUESTED | The consumer declines the offered contract and might sent a counter offer to the provider. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| OFFERED | C | ContractRequestMessage | REQUESTED | The consumer declines the offered contract and might sent a counter offer to the provider. |
| OFFERED | C | ContractRequestMessage | REQUESTED | The consumer declines the offered contract by sending a (new) contract request (to be seen as counter offer) to the provider. |

Copy link
Member Author

@SebastianOpriel SebastianOpriel Aug 11, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| OFFERED | C | ContractRequestMessage | REQUESTED | The consumer declines the offered contract and might sent a counter offer to the provider. |
| OFFERED | C | ContractRequestMessage | REQUESTED | The consumer declines the offered contract by sending a new contract request to the provider. |
  • Technically it will always be a new contract request
  • "counter offer" is not defined.

For curiosity (maybe discuss next week): How could a consumer define other parameters inside the ContractRequestMessage? WIthin the odrl:Offer?

| OFFERED | C | ContractNegotiationEventMessage:accepted | ACCEPTED | The consumer accepts to comply with the defined details in the contract. |
| ACCEPTED | P | ContractAgreementMessage | AGREED | The provider sends a provider-signed contract agreement to the consumer. |
| AGREED | C | ContractAgreementVerificationMessage | VERIFIED | The consumer sends a both-sides signed contract agreement to the provider. |
| VERIFIED | P | ContractNegotiationEventMessage:finalized | FINALIZED | The provider assures the consumer to have received the signed agreement. |
| \*/{TERMINATED, FINALIZED} | {C, P} | ContractNegotiationTerminationMessage | FINALIZED | The provider or consumer is not willing to continue any further negotiation process. This might happen e.g. in the case the provider doesnt want to place any offer (i.e. data) to the consumer. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TERMINATED and FINALIZED are never initial states. The table may contain the additional transitions introduced in #43 either in the same rows than the success states, or new ones.

Copy link
Member Author

@SebastianOpriel SebastianOpriel Aug 11, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The most left column is the origin state, not an initial state. With */{...} I wanted to express "All but {...}" from set theory, but I mixed up the backslash. Thus, the correct notation would be * \ {TERMINATED, FINALIZED}

Suggested change
| \*/{TERMINATED, FINALIZED} | {C, P} | ContractNegotiationTerminationMessage | FINALIZED | The provider or consumer is not willing to continue any further negotiation process. This might happen e.g. in the case the provider doesnt want to place any offer (i.e. data) to the consumer. |
| * \ {TERMINATED, FINALIZED} | {C, P} | ContractNegotiationTerminationMessage | FINALIZED | The provider or consumer is not willing to continue any further negotiation process. This might happen e.g. in the case the provider doesnt want to place any offer (i.e. data) to the consumer. |


## Message Types

The CN state machine is transitioned upon receipt and acknowledgement of a message. This section details those messages as abstract message types.
Expand Down