PID

dPID • Persistent Identifiers • Content Adressing

The dPID system for research objects allows resolution to the underlying components in a consistent and granular way over HTTP and the IPFS network. You can learn more about the schema, syntax and variants below. Note that the system is under active development, and the specification is subject to change.

CID refers to Content Identifier according to the Multiformats CID Specification

dPID anatomy

HTTP URL = {Resolver}/{PID}/{version identifier OR CID}/{Component index}/{Component suffix}

ComponentComponent Description

Resolver

The DNS resolver, currently beta.dpid.org

PID

The registry's unique and version-invariant PID

Version identifier or CID

The version identifier (e.g. "v1" or "0") mapped to the CID of the manifest file or the manifest CID

Component index

The index of the component in the research object's data model, or the component ID

Component suffix

JSONPath to manifest component. Encoded with slashes and compact format for URL friendliness.

Example dPID Links for Data Access

TypeLink

Web

https://beta.dpid.org/46

Metadata

https://beta.dpid.org/46?jsonld and https://beta.dpid.org/46?raw

Past Metadata

https://beta.dpid.org/46/v1?raw

Code

https://beta.dpid.org/46/3/root/exploring-lupus/casa/J15430131-3409153_cont.py?raw

Data

https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt?raw

Note: Excluding ?raw results in resolving the human-accessible data in the Nodes App or another configured resolver application.

API for Research Objects

RouteBehavior

GET https://beta.dpid.org/api/v1/dpid

List all registered research objects

Query Params

page: number = 1 // first page

size: number = 100 // 100 items

sort: "asc" | "desc" = "desc" // sort descending

Response

{
    "dpid": "54",
    "id": "0x0...",
    "recentCid": "bafkre...",
    "researchObject": {
        "id": "0x0...",
        "versions": [
            {
                "id": "0x0...",
                "time": 1685098464,
                "cid": "bafkre...",
            },
            {
                "id": "0x0...",
                "time": 1685098776,
                "cid": "bafkre...",
            }
        ]
    }
}

GET https://beta.dpid.org/46/v1?raw

Get metadata for specific version of specific research object (application format) Response Typescript specification: https://github.com/desci-labs/nodes/blob/develop/desci-models/src/ResearchObject.ts

GET https://beta.dpid.org/46/v1?jsonld

Get metadata for specific version of specific research object (semantic format) Returns in RO-Crate 1.1 format Response Typescript specification: https://github.com/desci-labs/nodes/blob/develop/desci-models/src/RoCrate.ts

Navigating Data via dPID API

RouteBehavior

GET https://beta.dpid.org/46/root?raw GET https://beta.dpid.org/46/v1/root?raw deprecated GET https://beta.dpid.org/46/data?raw GET https://beta.dpid.org/46/v1/data?raw

These all do the same thing. Get the DAG-JSON encoded content of the root data folder. If version specified, uses that version, otherwise uses latest version.

GET https://beta.dpid.org/46/root/exploring-lupus-report.pdf?raw

Download the specific file specified, if not a file, but a folder, the DAG-JSON encoded content is shown

Valid PID syntax and variants

There are three different and valid variants of the PIDs that can be resolved over HTTP. These variants offer different levels of friendliness for humans.

Variant typesVariant syntax (human)Variant syntax (machine)

Short form URL variant (recommended)

https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt

https://beta.dpid.org/46/v4/data/exploring-lupus/output/data_lup.txt?raw

https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt

https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt?raw

dpid.org/42/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/1/measurements.csv

dpid.org/42/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/1/measurements.csv?raw

PreviousOpen State RepositoryNextData

Last updated