§ DID Attested Resources
v0.1 / Editor’s Draft

Specification Status: v0.1 / EDITORS DRAFT

At this time, the Editor’s Draft contains the initial version of the specification.

Current Specification: Editor’s Draft

Specification Version: v0.1 (see Changelog)

Source of Latest Draft: https://github.com/decentralized-identity/did-attested-resources/spec

Previous Versions:

Editors:
Patrick St. Louis
Stephen Curran
John Jordan
Andrew Whitehead
Brian Richter
Participate:
GitHub repo
File a bug
Commit history
Implementations:
didwebvh Server in Python
ACA-Py
Credo-TS

§ Abstract

A DID Attested Resource is a verifiable JSON envelope, identified by a DID URL, that carries: (1) an arbitrary JSON content object (the “resource”), (2) minimal metadata used for dereferencing, (3) optional links to related material, and (4) a [[spec:DATA-INTEGRITY]] proof over the whole envelope.

The identifier of a DID Attested Resource is bound to its content by embedding a deterministic digest in the DID URL, allowing resolvers to independently verify that the dereferenced resource has not been altered. By associating resources with a DID, DID Attested Resources inherit the trust model of the DID and its Controller: the DID establishes control, while the DID Attested Resource proof binds that control to the specific resource.

This specification defines the data model, identifier construction, digest calculation, proof requirements, creation/publishing steps, and resolver behavior for DID Attested Resources. It is independent of any particular resource type (e.g., AnonCreds objects) and any particular DID Method. Specifications (such as AnonCreds Objects as DID Attested Resources) may impose additional constraints outside this document.

§ Design Goals (Non-Normative)

§ DID Attested Resource Specification

§ Data Model

A DID Attested Resource is a JSON object with the following attributes:

{
  "@context": [
    "https://identity.foundation/did-attested-resources/context/{specVersion}",
    "https://w3id.org/security/data-integrity/v2"
  ],
  "type": ["AttestedResource"],
  "id": "did:<method>:<method-specific-id>/<path...>/{digestMultibase}",
  "version": "{specVersion}",
  "content": { /* arbitrary JSON resource */ },
  "metadata": {
    "resourceId": "{digestMultibase}",
    "resourceType": "",
    "resourceName": "",
    "resourceVersion": ""
  },
  "links": [
    {
      "id": "did:<...> or https://<...>",
      "mediaType": "",
      "resourceType": "",
      "timestamp": "",
      "digestMultibase": "{digestMultibase}"
    }
  ],
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "verificationMethod": "did:<method>:<...>#<key-id>",
    "proofPurpose": "assertionMethod",
    "proofValue": "..."
  }
}

Requirements

§ Identifier and Addressing

The identifier of a DID Attested Resource is always a DID URL.

Resolution from a DID URL to a retrievable transport URL is DID Method–specific.

A DID Document service entry MAY advertise the base URI for DID Attested Resources.

Thus, DID Attested Resources combine the self-verifying content hash with the trust anchoring of a DID.

§ Calculating the digestMultibase

Publishers and Resolvers MUST compute digestMultibase for the content as:

Where:

The calculated digestMultibase MUST matches both the metadata.resourceId and the final path segment of the DID URL.

The algorithms listed above to calculate the digestMultibase, including multibase, multihash, jcs, sha256 and b58btc MUST be be as defined above. Future versions of this specification, identified by a metadata version attribute, could use other algorithms.

§ Data Integrity Proof

A DID Attested Resource MUST include a Data Integrity proof in the proofJSON item.

proof.verificationMethod MUST be a key in the DID URL's DID Document, ensuring that only the DID Controller can publish valid DID Attested Resources under that DID.

§ Creation and Publishing (Publisher Behavior)

To create a DID Attested Resource:

§ Resolving DID Attested Resources (Resolver Behavior)

To resolve a DID Attested Resource:

The links JSON attribute is a possibly empty array. Its items MUST include:

Its items MAY include:

Profiles MAY define additional fields such as timestamp or digestMultibase.

Resolvers MAY use links to discover related DID Attested Resources (e.g., updated versions). For example, in the [spec:DIDWEBVH-ANONCREDS] specification, links in AnonCreds RevRegDef DID Attested Resources list the associated RevRegEntry DID Attested Resources, each of which defines the state of the AnonCreds Revocation Registry at a given timestamp.

Since the links item is outside of the context (the attested resource), the digestMultibase for the DID Attested Resource will not change if the links item is changed. However, the links items is covered by the [[spec:DATA-INTEGRITY]] proof.

§ JSON-LD Context

The DID Attested Resources JSON-LD context is as follows:

{
  "@context": {
    "@protected": true,
    "id": "@id",
    "type": "@type",

    "digestMultibase": {
      "@id": "https://w3id.org/security#digestMultibase",
      "@type": "https://w3id.org/security#multibase"
    },

    "AttestedResource": {
      "@id": "https://example.com/attested-resource#AttestedResource",
      "@protected": true,
      "@context": {
        "content": {
          "@id": "https://example.com/attested-resource#content",
          "@type": "@json"
        },
        "metadata": {
          "@id": "https://example.com/attested-resource#metadata",
          "@type": "@json"
        },
        "links": {
          "@id": "https://example.com/attested-resource#links",
          "@type": "@json"
        }
      }
    }
  }
}

§ Interoperability Notes (Non-Normative)

Profiles: Communities can define DID Attested Resource profiles for specific ecosystems (e.g., AnonCreds). Such profiles define the metadata type values, and the associated resources listed in the links array of a given DID Attested Resource type.

§ Security and Privacy Considerations

TO BE ADDED

§ Definitions

DID Controller
The entity that controls (create, updates, deletes) a given DID, as defined in the [DID-CORE].
DID Document
The JSON document returned from resolved as part of the process of resolving a DID URL.
DID URL
A DID URL as defined in the [[spec:DID-RESOLUTION]] specification. A DID URL is resolved by first resolving the DID, and then the specified resource.
version
A string indicating the version of the specification which was used when creating the attested resource.
content
Arbitrary json object which is immutable and bound to the ressourceId.
metadata
Additional data provided about the DID Attested Resource, including at least the resourceType, and resourceId.
Profiles
Semantic information about one or more related DID Attested Resources defined by a community for use within an ecosystem.
links
A (possibly empty) list of URLs related to a given DID Attested Resource within the Attested Resource file. The URLs may themselves be DID Attested Resources. The links are not part of the resource, and so changing the list does not alter the digestMultibase of the DID Attested Resource. The links attribute is covered by the Data Integrity proof that is included in the DID Attested Resource.

§ References

DID-CORE
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.
RFC8785
JSON Canonicalization Scheme (JCS). A. Rundgren; B. Jordan; S. Erdtman; 2020-06. Status: Informational.

§ DID Attested Resources Change Log

The following lists the substantive changes in each version of the specification.

✕
Table of Contents ✕