DIDs structure

DIDs are Unique Resource Identifiers (URIs) that follow the following pattern:

did:key example

Copy to clipboard.

DID methods

Different methods have different properties and are better suited to some use cases over others. There isn't a DID method that should be universally applied to every situation so getting a good understanding of the different offerings will help you decide which is going to work best for your use cases.

MATTR VII currently supports the following DID methods:

  • did:key: The most basic type of DID. The public key forms the DID and has no further data associated with it.

    Example: did:key:z6MkjBWPPa1njEKygyr3LR3pRKkqv714vyTkfnUdP6ToFSH5

  • did:web: This type of DID hosts requires hosting the DID document on a publicly accessible domain in order to make the document and contents available.

    Example: did:web:learn.vii.au01.mattr.global

DID document

Every DID can be resolved to a DID document. A fully resolved DID document typically includes information such as public keys, service endpoints and authentication mechanisms. It can include multiple public keys of different types to support various cryptographic algorithms or use cases.

Copy to clipboard.
2    "id": "did:web:learn.vii.au01.mattr.global",
3    "@context": [
4        "https://w3.org/ns/did/v1",
5        "https://w3id.org/security/suites/x25519-2019/v1",
6        "https://w3id.org/security/suites/jws-2020/v1",
7        "https://w3id.org/security/suites/ed25519-2018/v1",
8        "https://w3id.org/security/bbs/v1"
9    ],
10    "keyAgreement": [
11        {
12            "id": "did:web:learn.vii.au01.mattr.global#FZXtUmNERo",
13            "type": "X25519KeyAgreementKey2019",
14            "controller": "did:web:learn.vii.au01.mattr.global",
15            "publicKeyBase58": "FZXtUmNERow4qGYb4LnLAVETodg7j7LrGyR78keGemWk"
16        }
17    ],
18    "authentication": [
19        "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV"
20    ],
21    "assertionMethod": [
22        "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
23        "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
24        "did:web:learn.vii.au01.mattr.global#24QqAnwtn4"
25    ],
26    "verificationMethod": [
27        {
28            "id": "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
29            "type": "JsonWebKey2020",
30            "controller": "did:web:learn.vii.au01.mattr.global",
31            "publicKeyJwk": {
32                "x": "hLdNSMnIaT1h-fjft9zX-nd_khjG7LERGImyNhzAlqU",
33                "y": "ofu7wybOMA8ltzS3gYgdr0DMhlmJNmjhdYpwcHT1_O8",
34                "crv": "P-256",
35                "kty": "EC"
36            }
37        },
38        {
39            "id": "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
40            "type": "Ed25519VerificationKey2018",
41            "controller": "did:web:learn.vii.au01.mattr.global",
42            "publicKeyBase58": "Fo5mW6ivUVsVS8e6EWuTFguQxTGFDMAZ7JBLuVqPsf1e"
43        },
44        {
45            "id": "did:web:learn.vii.au01.mattr.global#24QqAnwtn4",
46            "type": "Bls12381G2Key2020",
47            "controller": "did:web:learn.vii.au01.mattr.global",
48            "publicKeyBase58": "24QqAnwtn4AkCwiJHyBBe1eiyo6UegLx6AK8c3XSDUnopaNJP3EZvzgn8fLTaSWFY9T59PxdMp5RqoBBpCg8nGUdJnTVcTX7BPs8ubu516CNxNUehzwyTYzNdRt6YVqQSRMw"
49        }
50    ],
51    "capabilityDelegation": [
52        "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
53        "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
54        "did:web:learn.vii.au01.mattr.global#24QqAnwtn4"
55    ],
56    "capabilityInvocation": [
57        "did:web:learn.vii.au01.mattr.global#z12L6Q6v",
58        "did:web:learn.vii.au01.mattr.global#Fo5mW6ivUV",
59        "did:web:learn.vii.au01.mattr.global#24QqAnwtn4"
60    ]

Verification relationships

Verification relationships are the building blocks in a DID document. They determine the relationship between a key and the different capabilities it can be used for. DID documents include the following verification relationships:

  • assertionMethod

  • authentication

  • keyAgreement

For example, when a credential proof is created, the used private key will be linked to the corresponding public key as referenced in the assertionMethod section. By resolving the DID document for the Issuer DID it’s possible for anyone to validate the credential proof, verifying that the Issuer has asserted the data in the credential to be true.

During a verification flow, these checks are handled automatically using secure industry-leading methods, providing a simple result.

DID key types

MATTR VII currently supports the following key types:

  • P-256

  • Ed25519

  • Bls12381G2 (ZKP-enabled)


When referencing a specific sub-resource inside a DID document, we use the common fragment URLs pattern. When a DID key is specified in a single string, this is usually known as a DID URL, as shown in the following example:

Copy to clipboard.

Strictly speaking, any DID is a URL. However, we generally have used the term DID URL to mean the more specific version, so in our API Reference, didUrl would mean providing a value of the DID with the # to reference an exact key.