mirror of
https://github.com/oceanprotocol/docs.git
synced 2024-11-26 19:49:26 +01:00
Merge pull request #724 from oceanprotocol/issue723-oep7-dids
#723 - Fix oep7 (did) and oep8 (ddo)
This commit is contained in:
Trent McConaghy
GitHub
commit
e44cf80881
@ -67,6 +67,14 @@ module.exports = {
|
||||
{
|
||||
from: '/concepts/connect-to-networks/',
|
||||
to: '/concepts/networks/'
|
||||
},
|
||||
{
|
||||
from: '/concepts/oeps-did/',
|
||||
to: '/concepts/did-ddo/'
|
||||
},
|
||||
{
|
||||
from: '/concepts/oeps-asset-ddo/',
|
||||
to: '/concepts/ddo-metadata/'
|
||||
}
|
||||
],
|
||||
swaggerComponents: [
|
||||
|
||||
@ -1,115 +1,76 @@
|
||||
# OEP-8: Assets Metadata Ontology
|
||||
|
||||
```text
|
||||
shortname: 8/ASSET-DDO
|
||||
name: Assets Metadata Ontology
|
||||
type: Standard
|
||||
status: Draft
|
||||
version: 0.5
|
||||
editor: Alex Coseru <alex@oceanprotocol.com>
|
||||
contributors: Aitor Argomaniz <aitor@oceanprotocol.com>
|
||||
Enrique Ruiz <enrique@oceanprotocol.com>,
|
||||
Matthias Kretschmann <matthias@oceanprotocol.com>,
|
||||
Jose Pablo Fernandez <jose@oceanprotocol.com>,
|
||||
Marcus Jones <marcus@oceanprotocol.com>,
|
||||
Troy McConaghy <troy@oceanprotocol.com>
|
||||
```
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
- [Motivation](#motivation)
|
||||
- [Life Cycle of Metadata](#life-cycle-of-metadata)
|
||||
- [Local Metadata](#local-metadata)
|
||||
- [Remote Metadata](#remote-metadata)
|
||||
- [Metadata Attributes](#metadata-attributes)
|
||||
- [Main Attributes](#main-attributes)
|
||||
- [File Attributes](#file-attributes)
|
||||
- [Additional Attributes](#additional-attributes)
|
||||
- [Other Suggested Additional Attributes](#other-suggested-additional-attributes)
|
||||
- [Status Attributes](#status-attributes)
|
||||
- [Example of Local Metadata](#example-of-local-metadata)
|
||||
- [Example of Remote Metadata](#example-of-remote-metadata)
|
||||
- [Specific attributes per asset type](#specific-attributes-per-asset-type)
|
||||
- [Algorithm attributes](#algorithm-attributes)
|
||||
- [References](#references)
|
||||
- [Change Process](#change-process)
|
||||
- [Language](#language)
|
||||
|
||||
---
|
||||
title: DDO Metadata
|
||||
description: Specification of the DDO subset dedicated to asset metadata
|
||||
slug: /concepts/ddo-metadata/
|
||||
section: concepts
|
||||
---
|
||||
|
||||
## Motivation
|
||||
## Overview
|
||||
|
||||
Every asset (dataset, algorithm) in the Ocean Network has an associated Decentralized Identifier (DID) and DID document / DID Descriptor Object (DDO). Because assets without proper descriptive metadata have poor visibility and discoverability.
|
||||
This page defines the schema for asset _metadata_. Metadata is the subset of an Ocean DDO that holds information about the asset.
|
||||
|
||||
See [OEP 7/DID](../../7/) for information about the overall structure of Ocean DDOs and DIDs.
|
||||
The schema is based on public schema.org [DataSet schema](https://schema.org/Dataset).
|
||||
|
||||
This OEP is about one particular part of Ocean DDOs: the asset metadata, a JSON object with information about the asset.
|
||||
Standardizing labels is key to effective searching, sorting and filtering (curation).
|
||||
|
||||
This OEP defines the assets metadata ontology, i.e. the schema for the asset metadata. It's based on the public schema.org [DataSet schema](https://schema.org/Dataset).
|
||||
This page specifies metadata attributes that _must_ be included, and that _may_ be included. These attributes are organized hierarchically, from top-layer attributes like `"main"` to sub-level attributes like `"main.type"`. This page also provides DDO metadata examples.
|
||||
|
||||
This OEP doesn't detail the exact method of registering assets on-chain or storing DDOs.
|
||||
## Rules for Metadata Storage and Control in Ocean
|
||||
|
||||
The main motivations of this OEP are to:
|
||||
The publisher publishes an asset DDO (including metadata) onto the chain.
|
||||
|
||||
- Specify the common attributes that MUST be included in any asset metadata stored in the Ocean Network
|
||||
- Normalize the attributes to use in any curation process, to provide a common structure to sort and filter the DDOs
|
||||
- Identify the recommended additional attributes that SHOULD be included in a DDO to facilitate asset search
|
||||
- Provide an example of an asset metadata object and additional links for reference
|
||||
Asset DDO metadata is stored in plaintext by default. File URLs are stored encrypted on the chain. All metadata may be encrypted, though at a severe cost to discoverability.
|
||||
|
||||
## Life Cycle of Metadata
|
||||
The publisher may be the asset owner, or a marketplace acting on behalf of the owner.
|
||||
|
||||
### Local Metadata
|
||||
Most metadata fields may be modified after creation. The blockchain records the provenance of changes.
|
||||
|
||||
Metadata is first created by the publisher of the asset. The publisher has knowledge of the file URLs, and they are stored in plaintext in the `files` object. This initial metadata is the _local metadata_.
|
||||
The master reference for the DDO is the on-chain version, aka _remote_ version. Off-chain metadata caches like Aquarius are _local_ versions.
|
||||
|
||||
### Remote Metadata
|
||||
Aquarius can be used to help read and write data to the chain. Its local cache has decrypted information that was encrypted on-chain.
|
||||
|
||||
A publisher publishes (registers) an asset using [Ocean-lib](https://docs.oceanprotocol.com/concepts/components/#squid-libraries), which might be running on their local machine or remotely. When they do, the local metadata is passed to Squid, which makes some changes and additions in the metadata, puts it into a DDO, and sends that DDO to a metadata store (Aquarius).
|
||||
## Attributes for Metadata
|
||||
|
||||
Aquarius may also make some changes and additions to the metadata, such as the `datePublished` or parts of the `curation` object. The metadata that finally gets stored by Aquarius is the _remote metadata_.
|
||||
|
||||
> A marketplace can and might also act as a publisher. [OEP-11](../../11) describes the publishing flow in more detail.
|
||||
|
||||
## Metadata Attributes
|
||||
|
||||
An asset is the representation of different type of resources in Ocean Protocol. Typically can asset could be one of the following asset types:
|
||||
|
||||
- _Dataset_. An asset representing a dataset or data resource. It could be for example a CSV file or a multiple JPG files.
|
||||
- _Algorithm_. An asset representing a piece of software. It could be a python script using tensorflow, a spark job, etc.
|
||||
|
||||
Each kind of asset require a different subset of metadata attributes. The distintion between the type of asset (dataset, algorithm) is given by the attribute `DDO.services["metadata"].main.type`
|
||||
An asset represents a resource in Ocean, e.g. a dataset or an algorithm.
|
||||
|
||||
A `metadata` object has the following attributes, all of which are objects.
|
||||
|
||||
| Attribute | Required | Description |
|
||||
| --------------------------- | -------- | ---------------------------------------------------------- |
|
||||
| **`main`** | Yes | Main attributes used to calculate the service checksum |
|
||||
| **`main`** | Yes | Main attributes |
|
||||
| **`status`** | No. | Status attributes |
|
||||
| **`additionalInformation`** | No | Optional attributes |
|
||||
| **`encryptedFiles`** | (remote) | Encrypted string of the `attributes.main.files` object. |
|
||||
| **`encryptedServices`** | (remote) | Encrypted string of the `attributes.main.services` object. |
|
||||
|
||||
The `main`, `curation` and `additionalInformation` attributes are independent of the asset type, all assets have those metadata sections.
|
||||
The `main` and `additionalInformation` attributes are independent of the asset type. All assets have those metadata sections.
|
||||
|
||||
### Main Attributes
|
||||
## Attributes for Metadata.Main
|
||||
|
||||
**This list of attributes can't be modified after creation**, because these are considered as the metadata essence of the asset created. This information is used to calculate the unique checksum of the asset. If any change would be necessary in the following attributes, it would be necessary to create a new asset derived from the existing one.
|
||||
|
||||
The `main` object has the following attributes, not all are required. Some are required by only the metadata store (_remote_) and others are mandatory for _local_ metadata only. If required or not by both, they are marked with _Yes/No_ in the _Required_ column.
|
||||
The `main` object has the following attributes. Not all are required. Some are required by only the metadata store (_remote_) and others are mandatory for _local_ metadata only. If required or not by both, they are marked with _Yes/No_ in the _Required_ column.
|
||||
|
||||
| Attribute | Type | Required | Description |
|
||||
| ------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`name`** | Text | Yes | Descriptive name or title of the asset. |
|
||||
| **`type`** | Text | Yes | Type of the asset. Helps to filter by the type of asset. It could be for example ("dataset", "algorithm"). |
|
||||
| **`type`** | Text | Yes | Type of the asset. E.g. "dataset", "algorithm". |
|
||||
| **`dateCreated`** | DateTime | Yes | The date on which the asset was created by the originator. ISO 8601 format, Coordinated Universal Time, e.g. `2019-01-31T08:38:32Z`. |
|
||||
| **`datePublished`** | DateTime | (remote) | The date on which the asset DDO is registered into the metadata store (Aquarius) |
|
||||
| **`author`** | Text | Yes | Name of the entity generating this data (e.g. Tfl, Disney Corp, etc.). |
|
||||
| **`license`** | Text | Yes | Short name referencing the license of the asset (e.g. Public Domain, CC-0, CC-BY, No License Specified, etc. ). If it's not specified, the following value will be added: "No License Specified". |
|
||||
| **`files`** | Array of files object | Yes | Array of `File` objects including the encrypted file urls. Further metadata about each file is stored, see [File Attributes](#file-attributes) |
|
||||
| **`files`** | Array of files object | Yes | Array of `File` objects including the encrypted file urls. |
|
||||
|
||||
#### File Attributes
|
||||
## Attributes for Metadata.Main.Type
|
||||
|
||||
File attributes are a subset of the `main` section.
|
||||
_Asset types_ include:
|
||||
|
||||
- `dataset` - represents a dataset or data resource. It could be for example a CSV file or a multiple JPG files.
|
||||
- `algorithm` - represents a piece of software. It could be a python script using tensorflow, a spark job, etc.
|
||||
|
||||
Each _asset type_ needs a different subset of metadata attributes.
|
||||
|
||||
## Attributes for Metadata.Main.File
|
||||
|
||||
A file object has the following attributes, with the details necessary to consume and validate the data.
|
||||
|
||||
@ -129,7 +90,7 @@ A file object has the following attributes, with the details necessary to consum
|
||||
| **`resourceId`** | no | Remote identifier of the file in the external provider. It is typically the remote id in the cloud provider. |
|
||||
| **`attributes`** | no | Key-Value hash map with additional attributes describing the asset file. It could include details like the Amazon S3 bucket, region, etc. |
|
||||
|
||||
### Additional Attributes
|
||||
## Attributes for Metadata.AdditionalInformation
|
||||
|
||||
All the additional information will be stored as part of the `additionalInformation` section.
|
||||
|
||||
@ -143,7 +104,7 @@ All the additional information will be stored as part of the `additionalInformat
|
||||
| **`links`** | Array of Link | No | Mapping of links for data samples, or links to find out more information. Links may be to either a URL or another Asset. We expect marketplaces to converge on agreements of typical formats for linked data: The Ocean Protocol itself does not mandate any specific formats as these requirements are likely to be domain-specific. The links array can be an empty array, but if there is a link object in it, then an "url" is required in that link object. |
|
||||
| **`inLanguage`** | Text | No | The language of the content. Please use one of the language codes from the [IETF BCP 47 standard](https://tools.ietf.org/html/bcp47). |
|
||||
|
||||
#### Other Suggested Additional Attributes
|
||||
## Attributes - Other Suggestions
|
||||
|
||||
These are examples of attributes that can enhance the discoverability of a resource:
|
||||
|
||||
@ -157,9 +118,9 @@ These are examples of attributes that can enhance the discoverability of a resou
|
||||
| **`keyword`** | A list of keywords/tags describing a dataset. |
|
||||
| **`structuredMarkup`** | A link to machine-readable structured markup (such as ttl/json-ld/rdf) describing the dataset. |
|
||||
|
||||
The publisher of a DDO MAY add additional attributes or change the above object definition.
|
||||
The publisher of a DDO _may_ add additional attributes or change the above object definition.
|
||||
|
||||
### Status Attributes
|
||||
## Attributes for Metadata.Status
|
||||
|
||||
A `status` object has the following attributes.
|
||||
|
||||
@ -169,7 +130,9 @@ A `status` object has the following attributes.
|
||||
| **`isRetired`** | Boolean | No | Flag retired content. False by default. If it's true, the content may either not be returned, or returned with a note about retirement. |
|
||||
| **`isOrderDisabled`** | Boolean | No | For temporarily disabling ordering assets, e.g. when file host is in maintenance. False by default. If it's true, no ordering of assets for download or compute should be allowed. |
|
||||
|
||||
## Example of Local Metadata
|
||||
## DDO Metadata Example - All fields in plaintext (local)
|
||||
|
||||
This is what the DDO metadata looks like with all fields in plaintext. This is before it's stored on-chain or when it's retrieved and decrypted into a local cache.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -207,9 +170,13 @@ A `status` object has the following attributes.
|
||||
}
|
||||
```
|
||||
|
||||
## Example of Remote Metadata
|
||||
## DDO Metadata Example - Some fields encrypted (on-chain / remote)
|
||||
|
||||
Similarly, this is how the metadata file would look as a response to querying Aquarius (remote metadata). Note that `url` is removed from all objects in the `files` array, and `encryptedFiles` & `curation` are added.
|
||||
The previous example gave all fields in plaintext. Here's the same example, with some fields encrypted and changed for on-chain storage.
|
||||
|
||||
This is how the metadata looks as a response to querying Aquarius (remote metadata).
|
||||
|
||||
url` is removed from all objects in the `files` array, and `encryptedFiles` is added.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -256,11 +223,7 @@ Similarly, this is how the metadata file would look as a response to querying Aq
|
||||
}
|
||||
```
|
||||
|
||||
### Specific attributes per asset type
|
||||
|
||||
Depending on the asset type (dataset, algorithm), there are different metadata attributes supported:
|
||||
|
||||
#### Algorithm attributes
|
||||
## Attributes when Metadata.Main.Type = Algorithm
|
||||
|
||||
An asset of type `algorithm` has the following additional attributes under `main.algorithm`:
|
||||
|
||||
@ -325,7 +288,7 @@ The `container` object has the following attributes:
|
||||
}
|
||||
```
|
||||
|
||||
#### Compute datasets attributes
|
||||
## Attributes when Metadata.Main.Type = Compute
|
||||
|
||||
An asset with a service of type `compute` has the following additional attributes under `main.privacy`:
|
||||
|
||||
@ -343,7 +306,7 @@ The `publisherTrustedAlgorithms ` is an array of objects with the following stru
|
||||
| **`filesChecksum`** | `string` | yes | Hash of ( algorithm's encryptedFiles + files section (as string) ) |
|
||||
| **`containerSectionChecksum`** | `string` | yes | Hash of the algorithm container section (as string) |
|
||||
|
||||
To produce filesChecksum:
|
||||
To produce `filesChecksum`:
|
||||
|
||||
```javascript
|
||||
sha256(
|
||||
@ -352,7 +315,7 @@ sha256(
|
||||
)
|
||||
```
|
||||
|
||||
To produce containerSectionChecksum:
|
||||
To produce `containerSectionChecksum`:
|
||||
|
||||
```javascript
|
||||
sha256(
|
||||
@ -362,7 +325,7 @@ sha256(
|
||||
)
|
||||
```
|
||||
|
||||
Example of a compute service
|
||||
### Example of a compute service
|
||||
|
||||
```json
|
||||
{
|
||||
@ -396,19 +359,3 @@ Example of a compute service
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
[Schema.org](https://schema.org/) is a collaborative, community activity with a mission to create, maintain, and promote schemas for structured data on the Internet. Data types use the [Schema.org primitive data types](https://schema.org/DataType).
|
||||
|
||||
- [Schema.org: DataSet](https://schema.org/Dataset)
|
||||
- [Schema.org: FileSize](https://schema.org/fileSize)
|
||||
- [Common license types for datasets](https://help.data.world/hc/en-us/articles/115006114287-Common-license-types-for-datasets)
|
||||
|
||||
## Change Process
|
||||
|
||||
This document is governed by [OEP 2/COSS](../2/README.md).
|
||||
|
||||
## Language
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) \[[RFC2119](https://tools.ietf.org/html/rfc2119)\] \[[RFC8174](https://tools.ietf.org/html/rfc8174)\] when, and only when, they appear in all capitals, as shown here.
|
||||
173
content/concepts/did-ddo.md
Normal file
173
content/concepts/did-ddo.md
Normal file
@ -0,0 +1,173 @@
|
||||
---
|
||||
title: DIDs & DDOs - Asset Identifiers & Objects
|
||||
description: Specification of Ocean asset identifiers and objects using DIDs & DDOs
|
||||
slug: /concepts/did-ddo/
|
||||
section: concepts
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes how Ocean assets follow the DID/DDO spec, such that Ocean assets can inherit DID/DDO benefits and enhance interoperability.
|
||||
|
||||
Decentralized identifiers (DIDs) are a new type of identifier that enables verifiable, decentralized digital identity. Each DID is associated with a unique entity. DIDs may represent humans, objects, and more.
|
||||
|
||||
A DID Document (DDO) is JSON blob that holds information about the DID. Given a DID, a _resolver_ will return the DDO of that DID.
|
||||
|
||||
If a DID is the index key in a key-value pair, then the DID Document is the value to which the index key points.
|
||||
The combination of a DID and its associated DID Document forms the root record for a decentralized identifier.
|
||||
|
||||
DIDs and DDOs follow [this specification](https://w3c-ccg.github.io/did-spec/) defined by the World Wide Web Consurtium (W3C).
|
||||
|
||||
## Rules for DIDs & DDOs in Ocean
|
||||
|
||||
- An _asset_ in Ocean represents a downloadable file, compute service, or similar. Each asset is a _resource_ under control of a _publisher_. The Ocean network itself does _not_ store the actual resource (e.g. files).
|
||||
- An asset should have a DID and DDO. The DDO should include metadata about the asset.
|
||||
- The DDO can only can be modified by _owners_ or _delegated users_.
|
||||
- There _must_ be at least one client library acting as _resolver_, to get a DDO from a DID.
|
||||
- The DDO is stored on-chain. It's stored in in plaintext, with two exceptions: (1) the field for resource-access url is encrypted (2) the whole DDO may be encrypted, if the publisher is willing to lose 100% of discoverability.
|
||||
- A metadata cache like Aquarius can help in reading and writing DDO data from the chain.
|
||||
|
||||
## DID Structure
|
||||
|
||||
In Ocean, a DID is a string that looks like:
|
||||
|
||||
```text
|
||||
did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
|
||||
```
|
||||
|
||||
It follows [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-generic-did-scheme).
|
||||
|
||||
The part after `did:op:` is the asset's on-chain Ethereum address (minus the "0x"). One can be computed from the other; therefore there is a 1:1 mapping between did and Ethereum address.
|
||||
|
||||
## DDO Attributes
|
||||
|
||||
|
||||
|
||||
A DDO has these standard attributes:
|
||||
|
||||
- `@context`
|
||||
- `id`
|
||||
- `created`
|
||||
- `updated`
|
||||
- `publicKey`
|
||||
- `authentication`
|
||||
- `proof`
|
||||
- `verifiableCredential`
|
||||
|
||||
In Ocean, the DDO also has:
|
||||
|
||||
- `dataToken`
|
||||
- `service`
|
||||
- `credentials` - optional flag, which describes the credentials needed to access a dataset (see below)
|
||||
|
||||
Asset metadata must be included as one of the objects inside the `"service"` array, with type `"metadata"`.
|
||||
|
||||
## DDO Service Types
|
||||
|
||||
There are many possible service types for a DDO.
|
||||
|
||||
- `metadata` - describing the asset
|
||||
- `access` - describing how the asset can be downloaded
|
||||
- `compute` - describing how the asset can be computed upon
|
||||
|
||||
Each asset has a `metadata` service and at least one other service.
|
||||
|
||||
Each service is distinguished by the `DDO.service.type` attribute.
|
||||
|
||||
Each service has an `attributes` section holding the information related to the service. That section _must_ have a `main` sub-section, holding all the mandatory information that a service has to provide.
|
||||
|
||||
A part of the `attributes.main` sub-section, other optional sub-sections like `attributes.extra` can be added. These depend on the service type.
|
||||
|
||||
Each service has a `timeout` (in seconds) section describing how long the sevice can be used after consumption is initiated. A timeout of 0 represents no time limit.
|
||||
|
||||
The `cost` attribute is obsolete, as of Ocean V3. As of V3, to consume an asset, one sends exactly 1.0 datatokens of the asset, so a `cost` is not needed.
|
||||
|
||||
## DDO Service Example
|
||||
|
||||
Here is an example DDO service:
|
||||
|
||||
```json
|
||||
"service": [
|
||||
{
|
||||
"index": 0,
|
||||
"type": "metadata",
|
||||
"serviceEndpoint": "https://service/api/v1/metadata/assets/ddo/did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea",
|
||||
"attributes": {
|
||||
"main": {},
|
||||
"additionalInformation": {},
|
||||
"curation": {}
|
||||
}
|
||||
},
|
||||
{
|
||||
"index": 1,
|
||||
"type": "access",
|
||||
"serviceEndpoint": "http://localhost:8030/api/v1/brizo/services/consume",
|
||||
"attributes": {
|
||||
"main": {
|
||||
"cost":"10",
|
||||
"timeout":0
|
||||
},
|
||||
"additionalInformation": {}
|
||||
}
|
||||
},
|
||||
{
|
||||
"index": 2,
|
||||
"type": "compute",
|
||||
"serviceEndpoint": "http://localhost:8030/api/v1/brizo/services/compute",
|
||||
"attributes": {
|
||||
"main": {
|
||||
"cost":"10",
|
||||
"timeout":3600
|
||||
},
|
||||
"additionalInformation": {}
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## DDO Credentials for Fine-Grained Permissions
|
||||
|
||||
By default, a consumer can access a resource if they have 1.0 datatokens. _Credentials_ allow the publisher to optionally specify finer-grained permissions.
|
||||
|
||||
Consider a medical data use case, where only a credentialed EU researcher can legally access a given dataset. Ocean supports this as follows: a consumer can only access the resource if they have 1.0 datatokens _and_ one of the specified `"allow"` credentials.
|
||||
|
||||
This is like going to an R-rated movie, where you can only get in if you show both your movie ticket (datatoken) _and_ some some id showing you're old enough (credential).
|
||||
|
||||
Only credentials that can be proven are supported. This includes Ethereum public addresses, and (in the future) W3C Verifiable Credentials and more.
|
||||
|
||||
Ocean also supports `"deny"` credentials: if a consumer has any of these credentials, they cannot access the resource.
|
||||
|
||||
Here's an example object with both `"allow"` and `"deny"` entries.
|
||||
|
||||
```json
|
||||
"credentials":{
|
||||
"allow":[
|
||||
{
|
||||
"type":"address",
|
||||
"values":[
|
||||
"0x123",
|
||||
"0x456"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"deny":[
|
||||
{
|
||||
"type":"address",
|
||||
"values":[
|
||||
"0x2222",
|
||||
"0x333"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
For future usage, we can extend that with different credentials types. Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "credential3Box",
|
||||
"values": ["profile1", "profile2"]
|
||||
}
|
||||
```
|
||||
BIN
content/concepts/images/ddo-content.png
Normal file
BIN
content/concepts/images/ddo-content.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
@ -1,243 +0,0 @@
|
||||
# OEP-7: Decentralized Identifiers
|
||||
|
||||
```text
|
||||
shortname: 7/DID
|
||||
name: Decentralized Identifiers
|
||||
type: Standard
|
||||
status: Draft
|
||||
version: 0.3
|
||||
editor: Alex Coseru <alex@oceanprotocol.com>
|
||||
contributors: Matthias Kretschmann <matthias@oceanprotocol.com>,
|
||||
Ahmed Ali <ahmed@oceanprotocol.com>
|
||||
```
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
- [Motivation](#motivation)
|
||||
- [Specification](#specification)
|
||||
- [Proposed Solution](#proposed-solution)
|
||||
- [Decentralized IDs (DIDs)](#decentralized-ids-dids)
|
||||
- [DID Documents (DDOs)](#did-documents-ddos)
|
||||
- [DDO Services](#ddo-services)
|
||||
- [Credentials](#credentials)
|
||||
- [Integrity](#integrity)
|
||||
- [How to compute the integrity checksum](#how-to-compute-the-integrity-checksum)
|
||||
- [DID Document Proof](#did-document-proof)
|
||||
- [Length of a DID](#length-of-a-did)
|
||||
- [How to compute a DID](#how-to-compute-a-did)
|
||||
- [References](#references)
|
||||
- [Change Process](#change-process)
|
||||
- [Language](#language)
|
||||
|
||||
---
|
||||
|
||||
This specification is based on:
|
||||
|
||||
- the [W3C DID specification](https://w3c-ccg.github.io/did-spec/), which was at version 0.11 as of August 2018,
|
||||
- the [Ocean Protocol technical whitepaper](https://github.com/oceanprotocol/whitepaper),
|
||||
- [3/ARCH](../3/README.md), and
|
||||
- [4/AGENT](../4/README.md).
|
||||
|
||||
## Motivation
|
||||
|
||||
The main motivations of this OEP are:
|
||||
|
||||
- Design a solution to extend the current architecture to use **Decentralized Identifiers (DIDs)** and **DID Documents (DDOs)**
|
||||
- Understand how to resolve DIDs into DDOs
|
||||
- Establishing the mechanism to know if the DDO associated with a DID was modified
|
||||
- Defining the common mechanisms, interfaces and APIs to implemented the designed solution
|
||||
- Define how Ocean assets, agents and domains can be modeled with a DID/DDO data model
|
||||
- Understand how DID hubs are formed, and how they integrate a business and storage layer
|
||||
|
||||
## Specification
|
||||
|
||||
Requirements are:
|
||||
|
||||
- The DID resolving capabilities MUST be exposed in the client libraries, enabling to resolve a DDO directly in a totally transparent way
|
||||
- ASSETS are DATA objects describing RESOURCES under control of a PUBLISHER
|
||||
- PROVIDERS store the ASSET metadata off-chain
|
||||
- OCEAN doesn't store ASSET contents (e.g. files)
|
||||
- An ASSET is modeled in OCEAN as off-chain information stored in AQUARIUS
|
||||
- ASSETS information only can be modified by OWNERS or DELEGATED USERS
|
||||
- ASSETS can be resolved using a Decentralized ID (DID)
|
||||
- A DID Document (DDO) should include the ASSET metadata
|
||||
- Any kind of object registered in Ocean SHOULD have a DID allowing one to uniquely identify that object in the system
|
||||
- ASSET DDO (and the metadata included as part of the DDO) is associated to the ASSET information stored using a common DID
|
||||
- A DID can be resolved to get access to a DDO
|
||||
- The function to calculate the HASH MUST BE standard
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
### Decentralized IDs (DIDs)
|
||||
|
||||
A DID is a unique identifier that can be resolved or de-referenced to a standard resource describing the entity (a DID Document or DDO).
|
||||
If we apply this to Ocean, the DID would be the unique identifier of an object represented in Ocean (i.e. the Asset ID of an ASSET or the Actor ID of a USER).
|
||||
The DDO SHOULD include the METADATA information associated with this object.
|
||||
The DDO is stored off-chain in Ocean.
|
||||
|
||||
In Ocean, a DID is a string that looks like:
|
||||
|
||||
```text
|
||||
did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea
|
||||
```
|
||||
|
||||
which follows [the generic DID scheme](https://w3c-ccg.github.io/did-spec/#the-generic-did-scheme).
|
||||
Details about how to compute the DID are given below.
|
||||
|
||||
### DID Documents (DDOs)
|
||||
|
||||
If a DID is the index key in a key-value pair, then the DID Document is the value to which the index key points.
|
||||
The combination of a DID and its associated DID Document forms the root record for a decentralized identifier.
|
||||
|
||||
|
||||
|
||||
A DDO document is composed of standard DDO attributes:
|
||||
|
||||
- `@context`
|
||||
- `id`
|
||||
- `created`
|
||||
- `updated`
|
||||
- `publicKey`
|
||||
- `authentication`
|
||||
- `proof`
|
||||
- `verifiableCredential`
|
||||
- `dataToken`
|
||||
- `service`
|
||||
- `credentials` - optional flag, which describes the credentials needed to access a dataset (see below)
|
||||
|
||||
Asset metadata must be included as one of the objects inside the `"service"` array, with type `"metadata"`.
|
||||
|
||||
#### DDO Services
|
||||
|
||||
Each type of asset (dataset, algorithm, workflow, etc, ..) typically will have associated different kind of services. There are multiple type of services that are commonly added to all the assets:
|
||||
|
||||
- metadata - describing the asset
|
||||
- provenance - describing the asset provenance
|
||||
- access - describing how the asset can be downloaded
|
||||
- compute - describing how the asset can be computed upon
|
||||
|
||||
Each service is distinguished by the `DDO.service.type` attribute.
|
||||
|
||||
Each service has an `attributes` section where all the information related to the service is added. As mandatory content, the attributes section will have a `main` sub-section. This one is important because it must include all the mandatory information that a service has to provide.
|
||||
|
||||
A part of the `attributes.main` sub-section, other optional sub-sections can be added (like: `attributes.curation` or `attributes.extra`) depending on the service type.
|
||||
|
||||
Each service has an `cost` and `timeout` (in seconds) section describing the cost (how much datatokens needs to be transferred) and how long the sevice can be used after payment. A timeout of 0 represents no time limit.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
"service": [
|
||||
{
|
||||
"index": 0,
|
||||
"type": "metadata",
|
||||
"serviceEndpoint": "https://service/api/v1/metadata/assets/ddo/did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea",
|
||||
"attributes": {
|
||||
"main": {},
|
||||
"additionalInformation": {},
|
||||
"curation": {}
|
||||
}
|
||||
},
|
||||
{
|
||||
"index": 1,
|
||||
"type": "access",
|
||||
"serviceEndpoint": "http://localhost:8030/api/v1/brizo/services/consume",
|
||||
"attributes": {
|
||||
"main": {
|
||||
"cost":"10",
|
||||
"timeout":0
|
||||
},
|
||||
"additionalInformation": {}
|
||||
}
|
||||
},
|
||||
{
|
||||
"index": 2,
|
||||
"type": "compute",
|
||||
"serviceEndpoint": "http://localhost:8030/api/v1/brizo/services/compute",
|
||||
"attributes": {
|
||||
"main": {
|
||||
"cost":"10",
|
||||
"timeout":3600
|
||||
},
|
||||
"additionalInformation": {}
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
- You can find a [complete example of a DDO](ddo-example.json).
|
||||
- You can find a complete reference of the asset metadata in [OEP-8](8).
|
||||
- You can find a complete [real world example of a DDO](https://w3c-ccg.github.io/did-spec/#real-world-example) with extended services added, as part of the W3C DID spec.
|
||||
|
||||
#### Credentials
|
||||
|
||||
In order to support credentials based access. the following optional object is used:
|
||||
|
||||
```json
|
||||
"credentials":{
|
||||
"allow":[
|
||||
{
|
||||
"type":"address",
|
||||
"values":[
|
||||
"0x123",
|
||||
"0x456"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"deny":[
|
||||
{
|
||||
"type":"address",
|
||||
"values":[
|
||||
"0x2222",
|
||||
"0x333"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
- "allow" - will control who can consume this asset. If array it's empty, means anyone can consume
|
||||
- "deny" - if there is a match, consumption is denied
|
||||
|
||||
For future usage, we can extend that with different credentials types. Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "credential3Box",
|
||||
"values": ["profile1", "profile2"]
|
||||
}
|
||||
```
|
||||
|
||||
#### DID Document Proof
|
||||
|
||||
Since V3, the metadata is stored on chain, so we don't need additional proofs, because we already have the transaction sender.
|
||||
|
||||
#### Length of a DID
|
||||
|
||||
The length of a DID must be compliant with the underlying storage layer and function calls. Given that decentralized virtual machines make use of contract languages such as Solidity and WASM, it is advised to fit the DID in structures such as `bytes32`.
|
||||
|
||||
It would be nice to store the `did:op:` prefix in those 32 bytes, but that means fewer than 32 bytes would be left for storing the rest (25 bytes since "did:op:" takes 7 bytes if using UTF-8). If the rest is a secure hash, then we need a 25-byte secure hash, but secure hashes typically have 28, 32 or more bytes, so that won't work.
|
||||
|
||||
Only the hash value _needs_ to be stored, not the `did:op:` prefix, because it should be clear from context that the value is an Ocean DID.
|
||||
|
||||
#### How to compute a DID
|
||||
|
||||
The DID (`id`) string begins with `did:op:` and is followed by a string representation of a bytes32.
|
||||
|
||||
In V3, the DID is based on the datatoken address.
|
||||
|
||||
## References
|
||||
|
||||
- [DID Spec from the W3C Credentials Community Group](https://w3c-ccg.github.io/did-spec/)
|
||||
- [DID Spec from _Rebooting the Web of Trust_](https://github.com/WebOfTrustInfo/rebooting-the-web-of-trust-fall2016/blob/master/topics-and-advance-readings/did-spec-working-draft-03.md)
|
||||
|
||||
## Change Process
|
||||
|
||||
This document is governed by [OEP 2/COSS](../2/README.md).
|
||||
|
||||
## Language
|
||||
|
||||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) \[[RFC2119](https://tools.ietf.org/html/rfc2119)\] \[[RFC8174](https://tools.ietf.org/html/rfc8174)\] when, and only when, they appear in all capitals, as shown here.
|
||||
@ -18,12 +18,12 @@
|
||||
- title: Compute-to-Data Overview
|
||||
link: /concepts/compute-to-data/
|
||||
|
||||
- group: OEPs
|
||||
- group: Specifying Assets
|
||||
items:
|
||||
- title: DID
|
||||
link: /concepts/oeps-did/
|
||||
- title: Asset DDO
|
||||
link: /concepts/oeps-asset-ddo/
|
||||
- title: DIDs & DDOs
|
||||
link: /concepts/did-ddo/
|
||||
- title: DDO Metadata
|
||||
link: /concepts/ddo-metadata/
|
||||
|
||||
- group: Contribute
|
||||
items:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user