Provide non-normative examples of state transitions and adjust state description #138
Conversation
|
|
||
| | Origin State | Actor | Transition Trigger 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. | |
There was a problem hiding this comment.
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:
| | 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
| | 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. | |
There was a problem hiding this comment.
I think it should be "The consumer requests a contract based for a dataset" since "a previously requested dataset or catalog" is not defined.
There was a problem hiding this comment.
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."
There was a problem hiding this comment.
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.
| | Origin State | Actor | Transition Trigger 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. | | ||
| | 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. | |
There was a problem hiding this comment.
You state "without previous interaction" and in the same sentence name business relationships.
| | 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. | |
There was a problem hiding this comment.
This should read "The provider sends a contract offer to a consumer" as an "existing business relationship" is undefined.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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).
| |----------------------------|--------|-------------------------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | 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 | 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. | | ||
| | REQUESTED | P | ContractOfferMessage | OFFERED | The provider sends an offering for a requested resource. | |
There was a problem hiding this comment.
Naming
| | 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. | |
There was a problem hiding this comment.
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"
There was a problem hiding this comment.
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.
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?
| | 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. | | ||
| | REQUESTED | P | ContractOfferMessage | OFFERED | The provider sends an offering for a requested resource. | | ||
| | REQUESTED | P | ContractAgreementMessage | AGREED | The provider directly sends a contract agreement as no terms must be agreed to, e.g. in case publicly data shall be shared without any policies. Be aware that implementation of such transitions must comply with local laws in application. | | ||
| | OFFERED | C | ContractRequestMessage | REQUESTED | The consumer declines the offered contract and might sent a counter offer to the provider. | |
There was a problem hiding this comment.
| | 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. | |
There was a problem hiding this comment.
| | 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?
| | 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. | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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}
| | \*/{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. | |
Co-authored-by: Julia Pampus <[email protected]>
| | 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 | 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. | | ||
| | REQUESTED | P | ContractOfferMessage | OFFERED | The provider sends an offering for a requested resource. | | ||
| | REQUESTED | P | ContractAgreementMessage | AGREED | The provider directly sends a contract agreement as no terms must be agreed to, e.g. in case publicly data shall be shared without any policies. Be aware that implementation of such transitions must comply with local laws in application. | |
There was a problem hiding this comment.
The spec should never make any such statements regarding public data, terms or laws.
Co-authored-by: Julia Pampus <[email protected]>
|
Suggestion: move to best practices document (introduced with #146) |
|
let's integrate into #146 |
No description provided.