LogoLogo
WebsitePredictoorData ChallengesData FarmingOcean.pyOcean.js
  • 👋Ocean docs
  • 🌊Discover Ocean
    • Why Ocean?
    • What is Ocean?
    • What can you do with Ocean?
    • OCEAN: The Ocean token
    • Networks
    • Network Bridges
    • FAQ
    • Glossary
  • 📚User Guides
    • Basic concepts
    • Using Wallets
      • Set Up MetaMask
    • Host Assets
      • Uploader
      • Arweave
      • AWS
      • Azure Cloud
      • Google Storage
      • Github
    • Liquidity Pools [deprecated]
  • 💻Developers
    • Architecture Overview
    • Ocean Nodes
      • Node Architecture
    • Contracts
      • Data NFTs
      • Datatokens
      • Data NFTs and Datatokens
      • Datatoken Templates
      • Roles
      • Pricing Schemas
      • Fees
    • Publish Flow Overview
    • Revenue
    • Fractional Ownership
    • Community Monetization
    • Metadata
    • Identifiers (DIDs)
    • New DDO Specification
    • Obsolete DDO Specification
    • Storage Specifications
    • Fine-Grained Permissions
    • Retrieve datatoken/data NFT addresses & Chain ID
    • Get API Keys for Blockchain Access
    • Barge
      • Local Setup
    • Ocean.js
      • Configuration
      • Creating a data NFT
      • Publish
      • Mint Datatokens
      • Update Metadata
      • Asset Visibility
      • Consume Asset
      • Run C2D Jobs
    • Ocean CLI
      • Install
      • Publish
      • Edit
      • Consume
      • Run C2D Jobs
    • DDO.js
      • Instantiate a DDO
      • DDO Fields interactions
      • Validate
      • Edit DDO Fields
    • Compute to data
    • Compute to data
    • Uploader
      • Uploader.js
      • Uploader UI
      • Uploader UI to Market
    • VSCode Extension
    • Old Infrastructure
      • Aquarius
        • Asset Requests
        • Chain Requests
        • Other Requests
      • Provider
        • General Endpoints
        • Encryption / Decryption
        • Compute Endpoints
        • Authentication Endpoints
      • Subgraph
        • Get data NFTs
        • Get data NFT information
        • Get datatokens
        • Get datatoken information
        • Get datatoken buyers
        • Get fixed-rate exchanges
        • Get veOCEAN stats
    • Developer FAQ
  • 📊Data Scientists
    • Ocean.py
      • Install
      • Local Setup
      • Remote Setup
      • Publish Flow
      • Consume Flow
      • Compute Flow
      • Ocean Instance Tech Details
      • Ocean Assets Tech Details
      • Ocean Compute Tech Details
      • Datatoken Interface Tech Details
    • Join a Data Challenge
    • Sponsor a Data Challenge
    • Data Value-Creation Loop
    • What data is valuable?
  • 👀Predictoor
  • 💰Data Farming
    • Predictoor DF
      • Guide to Predictoor DF
    • FAQ
  • 🔨Infrastructure
    • Set Up a Server
    • Deploy Aquarius
    • Deploy Provider
    • Deploy Ocean Subgraph
    • Deploy C2D
    • For C2D, Set Up Private Docker Registry
  • 🤝Contribute
    • Collaborators
    • Contributor Code of Conduct
    • Legal Requirements
Powered by GitBook
LogoLogo

Ocean Protocol

  • Website
  • Blog
  • Data Challenges

Community

  • Twitter
  • Discord
  • Telegram
  • Instagram

Resources

  • Whitepaper
  • GitHub
  • Docs

Copyright 2024 Ocean Protocol Foundation Ltd.

On this page
  • New DDO Schema - High Level
  • Required Attributes
  • Aquarius Enhanced DDO Response
  • Compute to data
  • New DDO Schema - Detailed

Was this helpful?

Edit on GitHub
Export as PDF
  1. Developers

New DDO Specification

Specification of decentralized identifiers for assets in Ocean Protocol using the DDO standard.

Last updated 24 days ago

Was this helpful?

New DDO Schema - High Level

The below diagram shows the high-level DDO schema depicting the content of each data structure and the relations between them.

Please note that some data structures apply only on certain types of services or assets.

Required Attributes

A DDO in Ocean has these required attributes:

Attribute
Type
Description

@context

Array of string

Contexts used for validation.

id

string

Computed as sha256(address of ERC721 contract + chainId).

version

string

chainId

number

Stores the chainId of the network the DDO was published to.

nftAddress

string

NFT contract linked to this asset

metadata

Stores an object describing the asset.

services

Stores an array of services defining access to the asset.

credentials

Describes the credentials needed to access a dataset in addition to the services definition.

Full Enhanced DDO Example
{
  "@context": ["https://w3id.org/did/v1"],
  "id": "did:op:ACce67694eD2848dd683c651Dab7Af823b7dd123",
  "version": "4.1.0",
  "chainId": 1,
  "nftAddress": "0x123",
  "metadata": {
    "created": "2020-11-15T12:27:48Z",
    "updated": "2021-05-17T21:58:02Z",
    "description": "Sample description",
    "name": "Sample asset",
    "type": "dataset",
    "author": "OPF",
    "license": "https://market.oceanprotocol.com/terms"
  },
  "services": [
    {
      "id": "1",
      "type": "access",
      "files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735",
      "name": "Download service",
      "description": "Download service",
      "datatokenAddress": "0x123",
      "serviceEndpoint": "https://myprovider.com",
      "timeout": 0,
      "consumerParameters": [
        {
          "name": "surname",
          "type": "text",
          "label": "Name",
          "required": true,
          "default": "NoName",
          "description": "Please fill your name"
        },
        {
          "name": "age",
          "type": "number",
          "label": "Age",
          "required": false,
          "default": 0,
          "description": "Please fill your age"
        }
      ]
    },
    {
      "id": "2",
      "type": "compute",
      "files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735",
      "name": "Compute service",
      "description": "Compute service",
      "datatokenAddress": "0x124",
      "serviceEndpoint": "https://myprovider.com",
      "timeout": 3600,
      "compute": {
        "allowRawAlgorithm": false,
        "allowNetworkAccess": true,
        "publisherTrustedAlgorithmPublishers": ["0x234", "0x235"],
        "publisherTrustedAlgorithms": [
          {
            "did": "did:op:123",
            "filesChecksum": "100",
            "containerSectionChecksum": "200"
          },
          {
            "did": "did:op:124",
            "filesChecksum": "110",
            "containerSectionChecksum": "210"
          }
        ]
      }
    }
  ],
  "credentials": {
    "allow": [
      {
        "type": "address",
        "values": ["0x123", "0x456"]
      }
    ],
    "deny": [
      {
        "type": "address",
        "values": ["0x2222", "0x333"]
      }
    ]
  },
  "indexedMetadata": {
    "stats": [
            {
                "datatokenAddress": "0x35f74f653Dcb291838aa8AF8Be1E1eF30e749bb7",
                "name": "BDT1",
                "symbol": "DT1",
                "serviceId": "0",
                "orders": 1,
                // this service has one dispenser available
                "prices": [
                    {  
                        "type": "dispenser",
                        "price": "0",
                        "contract": "0x457"
                    }
                ]
            },
            {
                "datatokenAddress": "0x34e84f653Dcb291838aa8AF8Be1E1eF30e749ba0",
                "name": "BDT2",
                "symbol": "DT2",
                "serviceId": "1",
                "orders": 5,
                // this service accepts OCEAN for payment, costs 1 token per access
                "prices":
                [
                        {
                            "type": "fixedrate",
                            "price": "1",
                            "token":"0x967da4048cD07aB37855c090aAF366e4ce1b9F48",
                            "contract": "0x978da4048cD07aB37855c090aAF366e4ce1b9e48",  "exchangeId":  "23434"
                        }
                ]
            },
            {
                "datatokenAddress": "0x1234565",
                "name": "BDT3",
                "symbol": "DT3",
                "serviceId": "2",
                "orders": 5,
                // this service accepts either 2 OCEAN or 1 FETCH for payment
                "prices":
                [  
                   {
                    "type": "fixedrate", 
                    "price": "2",
                    "token":"0x967da4048cD07aB37855c090aAF366e4ce1b9F48",
                    "contract": "0x978da4048cD07aB37855c090aAF366e4ce1b9e48",
                    "exchangeId":  "23434"
                    },
                   {
                    "type": "fixedrate",
                    "price": "1",
                    "token":"0xaea46A60368A7bD060eec7DF8CBa43b7EF41Ad85",
                    "contract": "0x978da4048cD07aB37855c090aAF366e4ce1b9e48",
                    "exchangeId":  "4535"
                   }
            ]
        }
    ],
    "nft": {
        "address": "0x123",
        "name": "Ocean Protocol Asset",
        "symbol": "OCEAN-A",
        "owner": "0x0000000",
        "state": 0,
        "created": "2000-10-31T01:30:00",
        "tokenURI": "xxx"
  },

    "event": {
        "tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c",
        "block": 12831214,
        "from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83",
        "contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf",
        "datetime": "2000-10-31T01:30:00"
    },

    "purgatory": {
        "state": false
    }
 },

 "datatokens": [
    {
      "address": "0x000000",
      "name": "Datatoken 1",
      "symbol": "DT-1",
      "serviceId": "1"
    },
    {
      "address": "0x000001",
      "name": "Datatoken 2",
      "symbol": "DT-2",
      "serviceId": "2"
    }
  ]
  
}

Metadata

This object holds information describing the actual asset.

Attribute
Type
Description

created

ISO date/time string

Contains the date of the creation of the dataset content in ISO 8601 format preferably with timezone designators, e.g. 2000-10-31T01:30:00Z.

updated

ISO date/time string

Contains the date of last update of the dataset content in ISO 8601 format preferably with timezone designators, e.g. 2000-10-31T01:30:00Z.

description*

string

Details of what the resource is. For a dataset, this attribute explains what the data represents and what it can be used for.

copyrightHolder

string

The party holding the legal copyright. Empty by default.

name*

string

Descriptive name or title of the asset.

type*

string

Asset type. Includes "dataset" (e.g. csv file), "algorithm" (e.g. Python script). Each type needs a different subset of metadata attributes.

author*

string

Name of the entity generating this data (e.g. Tfl, Disney Corp, etc.).

license*

string

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 string

Mapping of URL strings for data samples, or links to find out more information. Links may be to either a URL or another asset.

contentLanguage

string

tags

Array of string

Array of keywords or tags used to describe this content. Empty by default.

categories

Array of string

Array of categories associated to the asset. Note: recommended to use tags instead of this.

additionalInformation

Object

Stores additional information, this is customizable by publisher

algorithm**

Information about asset of type algorithm

* Required

** Required for algorithms only

Metadata Example
{
  "metadata": {
    "created": "2020-11-15T12:27:48Z",
    "updated": "2021-05-17T21:58:02Z",
    "description": "Sample description",
    "name": "Sample asset",
    "type": "dataset",
    "author": "OPF",
    "license": "https://market.oceanprotocol.com/terms"
  }
}

Services

Services define the access for an asset, and each service is represented by its respective datatoken.

An asset should have at least one service to be actually accessible and can have as many services which make sense for a specific use case.

Attribute
Type
Description

id*

string

Unique ID

type*

string

Type of service access, compute, wss etc.

name

string

Service friendly name

description

string

Service description

datatokenAddress*

string

Datatoken

serviceEndpoint*

string

Provider URL (schema + host)

files*

Encrypted file.

timeout*

number

Describing how long the service can be used after consumption is initiated. A timeout of 0 represents no time limit. Expressed in seconds.

compute**

If service is of type compute, holds information about the compute-related privacy settings & resources.

consumerParameters

An object the defines required consumer input before consuming the asset

additionalInformation

Object

Stores additional information, this is customizable by publisher

* Required

** Required for compute assets only

Files

The files field is returned as a string which holds the encrypted file URLs.

Files Example
{
  "files": "0x044736da6dae39889ff570c34540f24e5e084f4e5bd81eff3691b729c2dd1465ae8292fc721e9d4b1f10f56ce12036c9d149a4dab454b0795bd3ef8b7722c6001e0becdad5caeb2005859642284ef6a546c7ed76f8b350480691f0f6c6dfdda6c1e4d50ee90e83ce3cb3ca0a1a5a2544e10daa6637893f4276bb8d7301eb35306ece50f61ca34dcab550b48181ec81673953d4eaa4b5f19a45c0e9db4cd9729696f16dd05e0edb460623c843a263291ebe757c1eb3435bb529cc19023e0f49db66ef781ca692655992ea2ca7351ac2882bf340c9d9cb523b0cbcd483731dc03f6251597856afa9a68a1e0da698cfc8e81824a69d92b108023666ee35de4a229ad7e1cfa9be9946db2d909735"
}

Credentials

By default, a consumer can access a resource if they have 1 datatoken. Credentials allow the publisher to optionally specify more fine-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 datatoken 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 identification showing you're old enough (credential).

Ocean also supports deny credentials: if a consumer has any of these credentials, they can not access the resource.

Here's an example object with both allow and deny entries:

Credentials Example
{
  "credentials": {
    "allow": [
      {
        "type": "address",
        "values": ["0x123", "0x456"]
      }
    ],
    "deny": [
      {
        "type": "address",
        "values": ["0x2222", "0x333"]
      }
    ]
  }
}

DDO Checksum

In order to ensure the integrity of the DDO, a checksum is computed for each DDO:

const checksum = sha256(JSON.stringify(ddo));

The checksum hash is used when publishing/updating metadata using the setMetaData function in the ERC721 contract, and is stored in the event generated by the ERC721 contract.

MetadataCreated and MetadataUpdated smart contract events
event MetadataCreated(
  address indexed createdBy,
  uint8 state,
  string decryptorUrl,
  bytes flags,
  bytes data,
  bytes metaDataHash,
  uint256 timestamp,
  uint256 blockNumber
);

event MetadataUpdated(
  address indexed updatedBy,
  uint8 state,
  string decryptorUrl,
  bytes flags,
  bytes data,
  bytes metaDataHash,
  uint256 timestamp,
  uint256 blockNumber
);

Aquarius should always verify the checksum after data is decrypted via a Provider API call.

State

Each asset has a state, which is held by the NFT contract. The possible states are:

State
Description
Discoverable in Ocean Market
Ordering allowed
Listed under profile

0

Active

Yes

Yes

Yes

1

End-of-life

Yes

No

No

2

Deprecated (by another asset)

No

No

No

3

Revoked by publisher

No

No

No

4

Ordering is temporary disabled

Yes

No

Yes

5

Asset unlisted.

No

Yes

Yes

States details:

  1. Active: Assets in the "Active" state are fully functional and available for discovery in Ocean Market, and other components. Users can search for, view, and interact with these assets. Ordering is allowed, which means users can place orders to purchase or access the asset's services.

  2. End-of-life: Assets in the "End-of-life" state remain discoverable but cannot be ordered. This state indicates that the assets are usually deprecated or outdated, and they are no longer actively promoted or maintained.

  3. Deprecated (by another asset): This state indicates that another asset has deprecated the current asset. Deprecated assets are not discoverable, and ordering is not allowed. Similar to the "End-of-life" state, deprecated assets are not listed under the owner's profile.

  4. Revoked by publisher: When an asset is revoked by its publisher, it means that the publisher has explicitly revoked access or ownership rights to the asset. Revoked assets are not discoverable, and ordering is not allowed.

  5. Ordering is temporarily disabled: Assets in this state are still discoverable, but ordering functionality is temporarily disabled. Users can view the asset and gather information, but they cannot place orders at that moment. However, these assets are still listed under the owner's profile.

  6. Asset unlisted: Assets in the "Asset unlisted" state are not discoverable. However, users can still place orders for these assets, making them accessible. Unlisted assets are listed under the owner's profile, allowing users to view and access them.

Aquarius Enhanced DDO Response

The following fields are added by Aquarius in its DDO response for convenience reasons, where an asset returned by Aquarius inherits the DDO fields stored on-chain.

Datatokens

Attribute
Type
Description

address

string

Contract address of the deployed ERC20 contract.

name

string

Name of NFT set in contract.

symbol

string

Symbol of NFT set in contract.

serviceId

string

ID of the service the datatoken is attached to.

Datatokens Array Example
{
  "datatokens": [
    {
      "address": "0x000000",
      "name": "Datatoken 1",
      "symbol": "DT-1",
      "serviceId": "1"
    },
    {
      "address": "0x000001",
      "name": "Datatoken 2",
      "symbol": "DT-2",
      "serviceId": "2"
    }
  ]
}

IndexedMetadata

Indexed Metadata contains off-chain data that helps storing assets pricing details and displaying them properly within decenterlized applications.

Indexed Metadata is composed of the following objects:

  • NFT

  • Event

  • Purgatory

  • Stats

When hashing is performed against a document, indexedMeatadata object has to be removed from the DDO structure, its off-chain data being stored and maintained only in the Indexer database, within DDO collection.

NFT

The nft object contains information about the ERC721 NFT contract which represents the intellectual property of the publisher.

Attribute
Type
Description

address

string

Contract address of the deployed ERC721 NFT contract.

name

string

Name of NFT set in contract.

symbol

string

Symbol of NFT set in contract.

owner

string

ETH account address of the NFT owner.

state

number

created

ISO date/time string

Contains the date of NFT creation.

tokenURI

string

tokenURI

NFT Object Example
{
  "nft": {
    "address": "0x000000",
    "name": "Ocean Protocol Asset",
    "symbol": "OCEAN-A",
    "owner": "0x0000000",
    "state": 0,
    "created": "2000-10-31T01:30:00Z"
  }
}

Event

The event section contains information about the last transaction that created or updated the DDO.

Event Example
{
  "event": {
    "tx": "0x8d127de58509be5dfac600792ad24cc9164921571d168bff2f123c7f1cb4b11c",
    "block": 12831214,
    "from": "0xAcca11dbeD4F863Bb3bC2336D3CE5BAC52aa1f83",
    "contract": "0x1a4b70d8c9DcA47cD6D0Fb3c52BB8634CA1C0Fdf",
    "datetime": "2000-10-31T01:30:00"
  }
}

Purgatory

Attribute
Type
Description

state

boolean

If true, asset is in purgatory.

reason

string

If asset is in purgatory, contains the reason for being there as defined in list-purgatory.

Purgatory Example
{ 
    "purgatory": {
      "state": true,
      "reason": "Copyright violation" 
      } 

}
{
  "purgatory": {
    "state": false
  }
}

Statistics

The stats section contains a list of different statistics fields.

Attribute
Type
Description

datatokenAddress

string

Datatoken address which has the pricing schema attached.

name

string

Name of the datatoken with pricing schema.

symbol

string

Symbol of the datatoken with pricing schema.

serviceId

string

Service ID of the datatoken with pricing schema.

orders

number

How often an asset was ordered, meaning how often it was either downloaded or used as part of a compute job.

prices

array

Pricing schemas list for this datatoken (a fixedrate and dispenser can co-exist for the same datatoken).

type

string

Static values: "fixedrate", "dispenser".

price

string

Price for schema (for dispenser is default "0").

contract

string

Contract address of pricing schema contract.

token

string

Basetoken for fixedrate, Datatoken for dispenser.

exchangeId

string

Just for fixedrate.

Statistics Example
{
  "stats":
  [
    {
        "datatokenAddress": "0x123",
        "name": "Branin dataset: DT1",
        "symbol": "DT1",
        "serviceId": "0",
        "orders": 1,
        "prices":
        [
            {
                "type": "fixedrate", // or "dispenser"
                "price": "123",
                "contract": "<contractAddress>",
                "token": "0x89777", // token accepted for payment
                "exchangeId":  "xx" // only for fre, this is exhangeID
            }
        ]
    }
  ]
}

Compute to data

For algorithms and datasets that are used for compute to data, there are additional fields and objects within the DDO structure that you need to consider. These include:

  • compute attributes

  • publisherTrustedAlgorithms

  • consumerParameters

New DDO Schema - Detailed

The below diagram shows the detailed DDO schema depicting the content of each data structure and the relations between them.

Please note that some data structures apply only on certain types of services or assets.

Version information in notation referring to this DDO spec version, like 4.1.0.

The language of the content. Use one of the language codes from the

Only credentials that can be proven are supported. This includes Ethereum public addresses and in the future and more.

These additional fields are never stored on-chain and are never taken into consideration when .

The datatokens array contains information about the ERC20 datatokens attached to .

State of the asset reflecting the NFT contract value. See

Contains information about an asset's purgatory status defined in . Marketplace interfaces are encouraged to prevent certain user actions like adding liquidity on assets in purgatory.

Details for each of these are explained on the .

💻
W3C Verifiable Credentials
list-purgatory
Compute Options page
SemVer
IETF BCP 47 standard
Algorithm Metadata
Compute
Consumer Parameters
Files
hashing the DDO
asset services
Metadata
Services
Credentials
State