Initial input for the creation of formal specification documents #72
Conversation
Fixed typo and added missing changelog entry for changes in CONTRIBUTING.md
Adding the Structure for the communication guide and moving the infomodel to a new location.
tidy up formatting
|
@ssteinbuss @PeterKoen-MSFT @sebbader Here is the initial PR for specification document input. It focuses on the Information Model and Catalog Service as a start, with contract negotiation and transfer to follow. Note that I merged conflicts, which can make the commit history a bit messy. We can also rebase commits if that is easier. |
There was a problem hiding this comment.
Hi @jimmarino, great work, thanks for the proposal! I added my views as a review, seemed the best suited way to write them down. Let's see how it works out for us.
|
|
||
| ### Dataspace | ||
|
|
||
| A `Dataspace` is a set of technical services that facilitate interoperable asset sharing between entities. |
There was a problem hiding this comment.
I'd rather define a dataspace coming from the network (focus more on technical interoperability) or ecosystem (focus on shared rules) rather than starting with the components.
There was a problem hiding this comment.
Can you propose an alternative formulation?
There was a problem hiding this comment.
Maybe something like:
"A dataspace is build of a defined set of entities that exchange data under contractually agreed terms of use. Data in this context does not necessarily mean a dataset or a file, but a determinable set of information (also in the form of an application or accesses to services or similar). From a business point of view, a dataspace is an association of a set of participants who want to exchange data offers. From a technical point of view, a dataspace is a set of technical services that facilitate interoperable asset sharing between entities.
There was a problem hiding this comment.
IMO we should only focus on the technical definition in these documents because they are specifications. The other parts of your definition would fit well in the RAM documents and supporting material.
|
|
||
| A `PariticipantAgent` that makes a `Catalog` accessible to `Participants`. | ||
|
|
||
| ### Connector (DataService) |
There was a problem hiding this comment.
I like the way of basing the Connector definition on the ParticipantAgent rather than saying it is a server. Let's enhance it a bit further to make clear whether a connector may appear as a service, as a deployed software asset, as a physical server...
There was a problem hiding this comment.
It could be any of those, but they are implementation details. I was using "technology system" to avoid over-specifying what it is.
|
|
||
| - Versioning will be done via URLs. TBD. | ||
|
|
||
| ### 3.3 Pagination |
There was a problem hiding this comment.
Great to mention this! Let's also take a look together at http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_Preferencemaxpagesizeodatamaxpagesiz and http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ServerDrivenPaging
There was a problem hiding this comment.
Sure we can discuss it. OData is an older, complex technology. We may be able to get by with something much simpler and more RESTful.
|
|
||
| ### 4.1 Asynchronous Interactions | ||
|
|
||
| We may want to specify optional support for asynchronous callbacks for the catalog response. This would require addling a `callbackAddress` property and an `@id` to the request: |
There was a problem hiding this comment.
The @id attribute is always there even if it doesn't look like it. If omitted (making it a BlankNode), a random one is used implicitly. Better let's make @id mandatory.
|
|
||
| The catalog protocol is designed to be used by federated services without the need for a replication protocol. Each consumer is responsible for issuing requests | ||
| to 1..N catalog services, and managing the results. It follows that a specific replication protocol is not needed, or more precisely, each consumer replicates data from catalog | ||
| services by issuing `CatalogRequestMessages`. |
There was a problem hiding this comment.
That's sounds not very efficient for big catalogs. Do we need to think about a diff message, only exchanging the deltas?
There was a problem hiding this comment.
We can always add this once the base protocol is set since it will likely become complicated to do with DCAT.
| The catalog is a DCAT catalog with the following restrictions: | ||
|
|
||
| 1. Each ODRL `Offer` must be unique to a dataset since the target of the offer is derived from its enclosing context. | ||
| 2. Each ODRL `Offer` must NOT include an explicit `target` attribute. |
There was a problem hiding this comment.
I could think of having a filter statement or collection description as a target of an offer... Something like:
{
...
"@type": "Offer",
"target": {
"@id": "something",
"hasColor": "ex:green"
},
...
}
There was a problem hiding this comment.
An Offer only exists in the context of a DCAT 'Dataset' so it is a containment relation. Given that, a target does not make sense (there has been discussion in the DCAT working group on this topic). For example, an Offer would be invalid if it specified a target that was not the same as its containing Dataset.
|
|
||
| A `Dataspace` is a set of technical services that facilitate interoperable asset sharing between entities. | ||
|
|
||
| ### DataspaceAuthority |
There was a problem hiding this comment.
| ### DataspaceAuthority | |
| ### Dataspace Authority |
I would add spaces here and in the following.
There was a problem hiding this comment.
+1, let's see what others think
|
|
||
| ### DataspaceAuthority | ||
|
|
||
| A `DataspaceAuthority` is an entity that manages a `Dataspace`. |
There was a problem hiding this comment.
| A `DataspaceAuthority` is an entity that manages a `Dataspace`. | |
| A `Dataspace Authority` is an entity that manages a `Dataspace`. |
|
|
||
| A `Participant` is a `Dataspace` member that provides and/or consumes assets. | ||
|
|
||
| ### ParticipantAgent |
There was a problem hiding this comment.
| ### ParticipantAgent | |
| ### Participant Agent |
|
|
||
| ### ParticipantAgent | ||
|
|
||
| A `ParticipantAgent` is a technology system that performs operations on behalf of a `Participant`. |
There was a problem hiding this comment.
| A `ParticipantAgent` is a technology system that performs operations on behalf of a `Participant`. | |
| A `Participant Agent` is a technology system that performs operations on behalf of a `Participant`. |
|
|
||
| A `ParticipantAgent` is a technology system that performs operations on behalf of a `Participant`. | ||
|
|
||
| ### IdentityProvider |
There was a problem hiding this comment.
| ### IdentityProvider | |
| ### Identity Provider |
|
|
||
| A set of interactions between a provider `Connector` and consumer `Connector` that establish an `Agreement`. | ||
|
|
||
| ### Asset Transfer |
There was a problem hiding this comment.
| ### Asset Transfer | |
| ### Transfer Process |
To align with the process naming, just call this transfer process?
| or a participant itself (for example, in the case of decentralized identifiers). | ||
| - A `Credential Issuer` issues _verifiable credentials_ used by participant agents to allow access to assets and verify usage control. | ||
|
|
||
| The diagram below depicts the relationships between `ParticipantAgent` types: |
There was a problem hiding this comment.
| The diagram below depicts the relationships between `ParticipantAgent` types: | |
| The diagram below depicts the relationships between `Participant Agent` types: |
|
|
||
|  | ||
|
|
||
| - A `CatalogService` is a `Participant Agent` that makes a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) available to other participants. |
There was a problem hiding this comment.
| - A `CatalogService` is a `Participant Agent` that makes a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) available to other participants. | |
| - A `Catalog Service` is a `Participant Agent` that makes a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog) available to other participants. |
|
|
||
| - An ODRL `uid` that is a unique UUID. (ODRL PROFILE) | ||
| - The `Offer` must be unique to a dataset since the target of the offer is derived from its enclosing context. | ||
| - The `Offer` must NOT include an explicit `target` attribute. |
There was a problem hiding this comment.
| - The `Offer` must NOT include an explicit `target` attribute. | |
| - The `Offer` must NOT include an explicit `target` attribute. | |
| - An `Offer` is to be handled immutable. If an `Offer` needs to be corrected, a new `Offer` should be added to the negotiation process, or the process is cancelled and a new one is started. |
Maybe add the same hint as for the agreement (suggestion below).
| An `Agreement` is an [ODRL Agreement](https://www.w3.org/TR/odrl-model/#policy-agreement) with the following attributes: | ||
|
|
||
| - The `Agreement` class must include one `target` attribute that is the UUID of the asset the agreement is associated with. An agreement is therefore associated with **EXACTLY | ||
| ONE** asset. (ODRL PROFILE) |
There was a problem hiding this comment.
| ONE** asset. (ODRL PROFILE) | |
| ONE** asset. (ODRL PROFILE) | |
| - An `Agreement` MUST NOT be changed after its creation but MUST be recreated with a new identifier if needed. This is to be done by initiating a new negotiation process. |
Picking up the comment from @sebbader.
There was a problem hiding this comment.
I think if we use this text or something similar, it should be in the contract negotiation protocol spec, not here.
There was a problem hiding this comment.
@jimmarino and I agreed on removing catalog.error.message.json as the catalog sequence is handled synchronously. An error handling of the request therefore is part of the protocol binding.
|
This is now continued in the Dataspace Protocol specification see https://github.com/International-Data-Spaces-Association/ids-specification |
No description provided.