From 3d873de972d676c542a8e6e0a91cabaa99abc011 Mon Sep 17 00:00:00 2001 From: alexcos20 Date: Tue, 28 Sep 2021 09:07:27 -0700 Subject: [PATCH] draft v4 ddo --- content/concepts/ddo-metadata.md | 349 ------------------------------- content/concepts/did-ddo.md | 258 ++++++++++++++++------- 2 files changed, 185 insertions(+), 422 deletions(-) delete mode 100644 content/concepts/ddo-metadata.md diff --git a/content/concepts/ddo-metadata.md b/content/concepts/ddo-metadata.md deleted file mode 100644 index 94dfb94f..00000000 --- a/content/concepts/ddo-metadata.md +++ /dev/null @@ -1,349 +0,0 @@ ---- -title: DDO Metadata -description: Specification of the DDO subset dedicated to asset metadata -slug: /concepts/ddo-metadata/ -section: concepts ---- - -## Overview - -This page defines the schema for asset _metadata_. Metadata is the subset of an Ocean DDO that holds information about the asset. - -The schema is based on public schema.org [DataSet schema](https://schema.org/Dataset). - -Standardizing labels is key to effective searching, sorting and filtering (discovery). - -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. - -## Rules for Metadata Storage and Control in Ocean - -The publisher publishes an asset DDO (including metadata) onto the chain. - -The publisher may be the asset owner, or a marketplace acting on behalf of the owner. - -Most metadata fields may be modified after creation. The blockchain records the provenance of changes. - -DDOs (including metadata) are found in two places: - -- _Remote_ - main storage, on-chain. File URLs are always encrypted. One may actually encrypt all metadata, at a severe cost to discoverability. -- _Local_ - local cache. All fields are in plaintext. - -Ocean Aquarius helps manage metadata. It can be used to write DDOs to the chain, read from the chain, and has a local cache of the DDO in plaintext with fast search. - -## Fields for Metadata - -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. Some are only required for local or remote, and are specified as such. - -| Attribute | Required | Description | -| --------------------------- | -------- | ---------------------------------------------------------- | -| **`main`** | **Yes** | Main attributes | -| **`encryptedFiles`** | Remote | Encrypted string of the `attributes.main.files` object. | -| **`encryptedServices`** | Remote | Encrypted string of the `attributes.main.services` object. | -| **`status`** | No | Status attributes | -| **`additionalInformation`** | No | Optional attributes | - -The `main` and `additionalInformation` attributes are independent of the asset type. - -## Fields for `attributes.main` - -The `main` object has the following attributes. - -| Attribute | Type | Required | Description | -| ------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`name`** | Text |**Yes** | Descriptive name or title of the asset. | -| **`type`** | Text |**Yes** | Asset type. Includes `"dataset"` (e.g. csv file), `"algorithm"` (e.g. Python script). Each type needs a different subset of metadata attributes. | -| **`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. | -| **`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) | - -## Fields for `attributes.main.files` - -The `files` object has a list of `file` objects. - -Each `file` object has the following attributes, with the details necessary to consume and validate the data. - -| Attribute | Required | Description | -| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`index`** |**Yes** | Index number starting from 0 of the file. | -| **`contentType`** |**Yes** | File format. | -| **`url`** | Local | Content URL. Omitted from the remote metadata. Supports `http(s)://` and `ipfs://` URLs. | -| **`name`** | No | File name. | -| **`checksum`** | No | Checksum of the file using your preferred format (i.e. MD5). Format specified in `checksumType`. If it's not provided can't be validated if the file was not modified after registering. | -| **`checksumType`** | No | Format of the provided checksum. Can vary according to server (i.e Amazon vs. Azure) | -| **`contentLength`** | No | Size of the file in bytes. | -| **`encoding`** | No | File encoding (e.g. UTF-8). | -| **`compression`** | No | File compression (e.g. no, gzip, bzip2, etc). | -| **`encrypted`** | No | Boolean. Is the file encrypted? If is not set is assumed the file is not encrypted | -| **`encryptionMode`** | No | Encryption mode used. Just valid if `encrypted=true` | -| **`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. | - -## Fields for `attributes.status` - -A `status` object has the following attributes. - -| Attribute | Type | Required | Description | -| --------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`isListed`** | Boolean | No | Use to flag unsuitable content. True by default. If it's false, the content must not be returned. | -| **`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. | - -## Fields for `attributes.additionalInformation` - -All the additional information will be stored as part of the `additionalInformation` section. - -| Attribute | Type | Required | -| --------------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`tags`** | Array of Text | No | Array of keywords or tags used to describe this content. Empty by default. | -| **`description`** | Text | No | Details of what the resource is. For a dataset, this attribute explains what the data represents and what it can be used for. | -| **`copyrightHolder`** | Text | No | The party holding the legal copyright. Empty by default. | -| **`workExample`** | Text | No | Example of the concept of this asset. This example is part of the metadata, not an external link. | -| **`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). | -| **`categories`** | Array of Text | No | Optional array of categories associated to the asset. Note: recommended to use `"tags"` instead of this. | - -## Fields - Other Suggestions - -Here are example attributes to help an asset's discoverability. - -| Attribute | Description | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **`updateFrequency`** | An indication of update latency - i.e. How often are updates expected (seldom, annually, quarterly, etc.), or is the resource static that is never expected to get updated. | -| **`structuredMarkup`** | A link to machine-readable structured markup (such as ttl/json-ld/rdf) describing the dataset. | - -## DDO Metadata Example - Local - -This is what the DDO metadata looks like. All fields are in plaintext. This is before it's stored on-chain or when it's retrieved and decrypted into a local cache. - -```json -{ - "main": { - "name": "Madrid Weather forecast", - "dateCreated": "2019-05-16T12:36:14.535Z", - "author": "Norwegian Meteorological Institute", - "type": "dataset", - "license": "Public Domain", - "price": "123000000000000000000", - "files": [ - { - "index": 0, - "url": "https://example-url.net/weather/forecast/madrid/350750305731.xml", - "contentLength": "0", - "contentType": "text/xml", - "compression": "none" - } - ] - }, - "additionalInformation": { - "description": "Weather forecast of Europe/Madrid in XML format", - "copyrightHolder": "Norwegian Meteorological Institute", - "categories": ["Other"], - "links": [], - "tags": [], - "updateFrequency": null, - "structuredMarkup": [] - }, - "status": { - "isListed": true, - "isRetired": false, - "isOrderDisabled": false - } -} -``` - -## DDO Metadata Example - Remote - -The previous example was for a local cache, with all fields in plaintext. - -Here's the same example, for remote on-chain storage. That is, it's how metadata looks as a response to querying Aquarius (remote metadata). - -How remote is changed, compared to local: - -- `url` is removed from all objects in the `files` array -- `encryptedFiles` is added. - -```json -{ - "service": [ - { - "index": 0, - "serviceEndpoint": "http://aquarius:5000/api/v1/aquarius/assets/ddo/{did}", - "type": "metadata", - "attributes": { - "main": { - "type": "dataset", - "name": "Madrid Weather forecast", - "dateCreated": "2019-05-16T12:36:14.535Z", - "author": "Norwegian Meteorological Institute", - "license": "Public Domain", - "files": [ - { - "contentLength": "0", - "contentType": "text/xml", - "compression": "none", - "index": 0 - } - ], - "datePublished": "2019-05-16T12:41:01Z" - }, - "encryptedFiles": "0x7a0d1c66ae861…df43aa9", - "additionalInformation": { - "description": "Weather forecast of Europe/Madrid in XML format", - "copyrightHolder": "Norwegian Meteorological Institute", - "categories": ["Other"], - "links": [], - "tags": [], - "updateFrequency": null, - "structuredMarkup": [] - }, - "status": { - "isListed": true, - "isRetired": false, - "isOrderDisabled": false - } - } - } - ] -} -``` - -## Fields when `attributes.main.type = algorithm` - -An asset of type `algorithm` has the following additional attributes under `main.algorithm`: - -| Attribute | Type | Required | Description | -| --------------- | -------- | -------- | --------------------------------------------- | -| **`container`** | `Object` |**Yes** | Object describing the Docker container image. | -| **`language`** | `string` | No | Language used to implement the software | -| **`format`** | `string` | No | Packaging format of the software. | -| **`version`** | `string` | No | Version of the software. | - -The `container` object has the following attributes: - -| Attribute | Type | Required | Description | -| ---------------- | -------- | -------- | ----------------------------------------------------------------- | -| **`entrypoint`** | `string` |**Yes** | The command to execute, or script to run inside the Docker image. | -| **`image`** | `string` |**Yes** | Name of the Docker image. | -| **`tag`** | `string` |**Yes** | Tag of the Docker image. | -| **`checksum`** | `string` |**Yes** | Checksum of the Docker image. | - -```json -{ - "index": 0, - "serviceEndpoint": "http://localhost:5000/api/v1/aquarius/assets/ddo/{did}", - "type": "metadata", - "attributes": { - "main": { - "author": "John Doe", - "dateCreated": "2019-02-08T08:13:49Z", - "license": "CC-BY", - "name": "My super algorithm", - "type": "algorithm", - "algorithm": { - "language": "scala", - "format": "docker-image", - "version": "0.1", - "container": { - "entrypoint": "node $ALGO", - "image": "node", - "tag": "10", - "checksum": "efb2c764274b745f5fc37f97c6b0e761" - } - }, - "files": [ - { - "name": "build_model", - "url": "https://raw.gith ubusercontent.com/oceanprotocol/test-algorithm/master/javascript/algo.js", - "index": 0, - "checksum": "efb2c764274b745f5fc37f97c6b0e761", - "contentLength": "4535431", - "contentType": "text/plain", - "encoding": "UTF-8", - "compression": "zip" - } - ] - }, - "additionalInformation": { - "description": "Workflow to aggregate weather information", - "tags": ["weather", "uk", "2011", "workflow", "aggregation"], - "copyrightHolder": "John Doe" - } - } -} -``` - -## Fields when `attributes.main.type = compute` - -An asset with a service of type `compute` has the following additional attributes under `main.privacy`: - -| Attribute | Type | Required | Description | -| --------------------------------- | ------------------ | -------- | ---------------------------------------------------------- | -| **`allowRawAlgorithm`** | `boolean` |**Yes** | If True, a drag & drop algo can be runned | -| **`allowNetworkAccess`** | `boolean` |**Yes** | If True, the algo job will have network access (stil WIP) | -| **`publisherTrustedAlgorithms `** | Array of `Objects` |**Yes** | If Empty , then any published algo is allowed. (see below) | - -The `publisherTrustedAlgorithms ` is an array of objects with the following structure: - -| Attribute | Type | Required | Description | -| ------------------------------ | -------- | -------- | ------------------------------------------------------------------ | -| **`did`** | `string` |**Yes** | The did of the algo which is trusted by the publisher. | -| **`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`: - -```javascript -sha256( - algorithm_ddo.service['metadata'].attributes.encryptedFiles + - JSON.Stringify(algorithm_ddo.service['metadata'].attributes.main.files) -) -``` - -To produce `containerSectionChecksum`: - -```javascript -sha256( - JSON.Stringify( - algorithm_ddo.service['metadata'].attributes.main.algorithm.container - ) -) -``` - -### Example of a compute service - -```json -{ - "type": "compute", - "index": 1, - "serviceEndpoint": "https://provider.oceanprotocol.com", - "attributes": { - "main": { - "name": "dataAssetComputingService", - "creator": "0xA32C84D2B44C041F3a56afC07a33f8AC5BF1A071", - "datePublished": "2021-02-17T06:31:33Z", - "cost": "1", - "timeout": 3600, - "privacy": { - "allowRawAlgorithm": true, - "allowNetworkAccess": false, - "publisherTrustedAlgorithms": [ - { - "did": "0xxxxx", - "filesChecksum": "1234", - "containerSectionChecksum": "7676" - }, - { - "did": "0xxxxx", - "filesChecksum": "1232334", - "containerSectionChecksum": "98787" - } - ] - } - } - } -} -``` diff --git a/content/concepts/did-ddo.md b/content/concepts/did-ddo.md index 5ceccff8..3620f097 100644 --- a/content/concepts/did-ddo.md +++ b/content/concepts/did-ddo.md @@ -24,8 +24,17 @@ DIDs and DDOs follow [this specification](https://w3c-ccg.github.io/did-spec/) d - 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. +- A metadata cache like Aquarius can help in reading and searching through DDO data from the chain. + +## Flow for publishing / retrieving DDOs + +- The DDO is stored on-chain. +- It's stored encrypted (using the private key of the provider). To resolve it, you must query the provider and you will might get the clear text ddo (depends on access rights, state, etc) +- Each DID has a state, which is held by the NFT Contract (also stored in the DDO.status.status). The possible states are: + * 0 = active + * 1 = end-of-life + * 2 = deprecated (by another asset) + * 3 = revoked by publisher ## DID Structure @@ -34,98 +43,120 @@ In Ocean, a DID is a string that looks like: ```text did:op:0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea ``` +where "0ebed8226ada17fde24b6bf2b95d27f8f05fcce09139ff5cec31f6d81a7cd2ea" is the address of the ERC721 contract that represents that asset. 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 -![DDO Content](images/ddo-content.png) A DDO has these standard attributes: -- `@context` -- `id` -- `created` -- `updated` -- `publicKey` -- `authentication` -- `proof` -- `verifiableCredential` +- `@context` = array, contexts used for validation +- `id` = string, address of ERC721 contract +- `created` = updated by aquarius, contains the date of publishing (block.timestamp) +- `updated` = updated by aquarius, contains the date of the update (block.timestamp) +- `proof` = proof of ownership + In Ocean, the DDO also has: -- `dataToken` -- `service` -- `credentials` - optional flag, which describes the credentials needed to access a dataset (see below) +- `version` - stores version information (`v4` for us) +- `metadata` - stores metadata information [Metadata](#metadata) +- `service` - stores an array of services [Service](#service) +- `credentials` - optional flag, which describes the credentials needed to access a dataset [Credentials](#credentials) +- `status` - stores status related fields [Status](#status) +- `files` and `encryptedFiles` - stores file(s) informations [Files](#files) +- `event` - stores the last event information [Event](#event) -Asset metadata must be included as one of the objects inside the `"service"` array, with type `"metadata"`. -## DDO Service Types +## Metadata +The object has the following attributes. -There are many possible service types for a DDO. +| Attribute | Type | Required | Description | +| ------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`description`** | Text | **Yes** | Details of what the resource is. For a dataset, this attribute explains what the data represents and what it can be used for.| +| **`copyrightHolder`** | Text | No | The party holding the legal copyright. Empty by default. +| **`name`** | Text |**Yes** | Descriptive name or title of the asset. | +| **`type`** | Text |**Yes** | Asset type. Includes `"dataset"` (e.g. csv file), `"algorithm"` (e.g. Python script). Each type needs a different subset of metadata attributes. | +| **`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". | +| **`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)| +| **`categories`** | Array of Text | No | Optional array of categories associated to the asset. Note: recommended to use `"tags"` instead of this. | +| **`tags`** | Array of Text | No | Array of keywords or tags used to describe this content. Empty by default. | +| **`additionalInformation`** | Object | No | Stores additional information, this is customizable by publisher | -- `metadata` - describing the asset -- `access` - describing how the asset can be downloaded -- `compute` - describing how the asset can be computed upon +Depending on the asset type (dataset, algorithm), there are different metadata attributes supported: -Each asset has a `metadata` service and at least one other service. +### Algorithm attributes -Each service is distinguished by the `DDO.service.type` attribute. +An asset of type `algorithm` has the following additional attributes under `algorithm` in metadata object: -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. +| Attribute | Type | Required | Description | +| ------------------- | ----------------------| ----------- |--------------------------------------------------- | +| **`language`** | `string` | no | Language used to implement the software | +| **`format`** | `string` | no | Packaging format of the software. | +| **`version`** | `string` | no | Version of the software. | +| **`container`** | `Object` | yes | Object describing the Docker container image. | -A part of the `attributes.main` sub-section, other optional sub-sections like `attributes.extra` can be added. These depend on the service type. +The `container` object has the following attributes: -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. +| Attribute | Type | Required | Description | +| ------------------- | -------- | --------- | --------------------------------------------------- | +| **`entrypoint`** | `string` | yes | The command to execute, or script to run inside the Docker image. | +| **`image`** | `string` | yes | Name of the Docker image. | +| **`tag`** | `string` | yes | Tag of the Docker image. | +| **`checksum`** | `string` | yes | Checksum of the Docker image. | -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/provider/services/consume", - "attributes": { - "main": { - "cost":"10", - "timeout":0 - }, - "additionalInformation": {} - } - }, - { - "index": 2, - "type": "compute", - "serviceEndpoint": "http://localhost:8030/api/v1/provider/services/compute", - "attributes": { - "main": { - "cost":"10", - "timeout":3600 - }, - "additionalInformation": {} - } - } -] + +## Service + +| Attribute | Type | Required | Description | +| ------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`type`** | Text | **Yes** | Type of service (access, compute, wss, etc | +| **`name`** | Text | No | Service friendly name | +| **`serviceEndpoint`** | Text | **Yes** | Provider URI | +| **`timeout`** | Number | **Yes** | describing how long the sevice can be used after consumption is initiated. A timeout of 0 represents no time limit. | +| **`files`** | Array of files object |**No ** | Array of `File` objects including the encrypted file urls that overwrites the root files object for this service [Files](#files) | + + +Depending on the service type, the following attributes are applied: + +### Compute datasets attributes + +An asset with a service of type `compute` has the following additional attributes under `privacy` object : + +| Attribute | Type | Required | Description | +| ---------------------------- | ----------------------| ----------- |---------------------------------------------------------- | +| **`allowRawAlgorithm`** | `boolean` | yes | If True, a drag & drop algo can be runned | +| **`allowNetworkAccess`** | `boolean` | yes | If True, the algo job will have network access (stil WIP) | +| **`publisherTrustedAlgorithmPublishers `** | Array of `String` | yes | If Empty , then any published algo is allowed. Otherwise, only published algorithms by some publishers are allowed | +| **`publisherTrustedAlgorithms `** | Array of `Objects` | yes | If Empty , then any published algo is allowed. (see below) | + +The `publisherTrustedAlgorithms ` is an array of objects with the following structure: + +| Attribute | Type | Required | Description | +| ---------------------------------------- | -------- | --------- | --------------------------------------------------- | +| **`did`** | `string` | yes | The did of the algo which is trusted by the publisher. | +| **`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: +``` +sha256(algorithm_ddo.service['metadata'].attributes.encryptedFiles + JSON.Stringify(algorithm_ddo.service['metadata'].attributes.main.files) ) ``` -## DDO Credentials for Fine-Grained Permissions +To produce containerSectionChecksum: +``` +sha256(JSON.Stringify(algorithm_ddo.service['metadata'].attributes.main.algorithm.container)) +``` + +## Credentials By default, a consumer can access a resource if they have 1.0 datatokens. _Credentials_ allow the publisher to optionally specify finer-grained permissions. @@ -140,7 +171,9 @@ Ocean also supports `"deny"` credentials: if a consumer has any of these credent Here's an example object with both `"allow"` and `"deny"` entries. ```json -"credentials":{ +{ + {...}, + "credentials":{ "allow":[ { "type":"address", @@ -150,19 +183,22 @@ Here's an example object with both `"allow"` and `"deny"` entries. ] } ] - }, - "deny":[ - { + }, + "deny":[ + { "type":"address", "values":[ "0x2222", "0x333" ] - } - ] + } + ] + } } ``` +``` + For future usage, we can extend that with different credentials types. Example: ```json @@ -171,3 +207,79 @@ For future usage, we can extend that with different credentials types. Example: "values": ["profile1", "profile2"] } ``` + + + + +## Status +The `status` object contains the following attributes: + +| Attribute | Type | Required | Description | +| ---------------------------------------- | -------- | --------- | --------------------------------------------------- | +| **`status`** | `number` | yes | Status of the asset (see above) | +| **`isListed`** | `boolean` | no | If this asset should be displayed | +| **`isOrderDisabled`** | `boolean` | no | If this asset has ordering disabled | + +```json +{ + {...}, + "status": { + "status": 0, + "isListed": true, + "isOrderDisabled": false + } +``` +## Files + +The `files` section contains a `file` object (that contains a list of `file` objects) and a `encryptedFiles` string which contains the encrypted urls + +Each `file` object has the following attributes, with the details necessary to consume and validate the data. + +| Attribute | Required | Description | +| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`contentType`** |**Yes** | File format. | +| **`url`** | Local | Content URL. Omitted from the remote metadata. Supports `http(s)://` and `ipfs://` URLs. | +| **`name`** | No | File name. | +| **`checksum`** | No | Checksum of the file using your preferred format (i.e. MD5). Format specified in `checksumType`. If it's not provided can't be validated if the file was not modified after registering. | +| **`checksumType`** | No | Format of the provided checksum. Can vary according to server (i.e Amazon vs. Azure) | +| **`contentLength`** | No | Size of the file in bytes. | +| **`encoding`** | No | File encoding (e.g. UTF-8). | +| **`compression`** | No | File compression (e.g. no, gzip, bzip2, etc). | +| **`encrypted`** | No | Boolean. Is the file encrypted? If is not set is assumed the file is not encrypted | +| **`encryptionMode`** | No | Encryption mode used. Just valid if `encrypted=true` | +| **`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. + +Exanple: + +```json +{ + {..}, + files:{ + "files": [ + { + "contentLength": "3975", + "contentType": "text/csv" + } + ], + "encryptedFiles": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735", + } +} +``` + +## Event +The `event` section contains informations about the latest transaction that created or update the ddo +This section is auto-completed by aquarius. + +```json +{ + {...}, + "event": { + "txid": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c", + "blockNo": 12831214, + "from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83", + "contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf", + "update": false, + "chainId": 1, + } +```