RFC 0067: Correct JSON-LD context usage DID document conventions

[tplooker]

On the last Aries WG call we discussed the current state of the DID communication DID document conventions, @talltree raised the point that the current defined convention omits a JSON-LD context notation in the service declaration.

Im opening this issue to ask how this aspect should be expressed.

As defined in the RFC currently we have the below

{
  "service": [{
    "id": "did:example:123456789abcdefghi#did-communication",
    "type": "did-communication",
    "priority" : 0,
    "recipientKeys" : [ "did:example:123456789abcdefghi#1" ],
    "routingKeys" : [ "did:example:123456789abcdefghi#1" ],
    "serviceEndpoint": "https://agent.example.com/"
  }]
}

Note we have type which is different to the @type used by JSON-LD, are these intended to be different?

If so would adding JSON-LD support at a service block level look like the following?

{
  "service": [{
    "@context": "https://schema.org",
    "@type": "DidCommunication",
    "id": "did:example:123456789abcdefghi#did-communication",
    "type": "did-communication",
    "priority" : 0,
    "recipientKeys" : [ "did:example:123456789abcdefghi#1" ],
    "routingKeys" : [ "did:example:123456789abcdefghi#1" ],
    "serviceEndpoint": "https://agent.example.com/"
  }]
}

The alternative is to opt for a syntax similar to the following

{
    "id": "did:example:123456789abcdefghi#did-communication",
    "type": "did-communication",
    "serviceEndpoint": {
      "@context": "https://schema.org",
      "@type": "DidCommunication",
      "recipientKeys": [ "did:example:789#key-1"],
      "routingKeys": [ "did:example:789#key-1"],
      "endpoint": "https://agent.endpoint.org"
  }
}

@peacekeeper @talltree your expertise on the DID spec and how it currently defines services would be greatly appreciated :)

[tplooker]

@peacekeeper @talltree are you able to advise on this syntax, I have noted from the examples in the did spec that none of them use JSON-LD at the root of a service block e.g the following.

{
  "service": [{
    "@context": "https://schema.org",
    "@type": "DidCommunication",
    "id": "did:example:123456789abcdefghi#did-communication",
    "type": "did-communication",
    "priority" : 0,
    "recipientKeys" : [ "did:example:123456789abcdefghi#1" ],
    "routingKeys" : [ "did:example:123456789abcdefghi#1" ],
    "serviceEndpoint": "https://agent.example.com/"
  }]
}

With this example from the did spec

{
    "id": "did:example:123456789abcdefghi#inbox",
    "type": "SocialWebInboxService",
    "serviceEndpoint": "https://social.example.com/83hfh37dj",
    "description": "My public social inbox",
    "spamCost": {
      "amount": "0.50",
      "currency": "USD"
    }

How do I resolve the context here e.g know about the presence of the description field and spam cost sub object, the type field defined in this example is not a JSON-LD related is it? So where does the context for this object come from? I think the following syntax makes the most sense personally.

{
    "id": "did:example:123456789abcdefghi#did-communication",
    "type": "did-communication",
    "serviceEndpoint": {
      "@context": "https://schema.org",
      "@type": "DidCommunication",
      "recipientKeys": [ "did:example:789#key-1"],
      "routingKeys": [ "did:example:789#key-1"],
      "endpoint": "https://agent.endpoint.org"
  }
}

[peacekeeper]

@tplooker sorry for not responding sooner, and thanks for pinging again as a reminder!

What makes this a bit complicated is that you have to distinguish between 1. the underlying RDF graph model, 2. the JSON-LD format, and 3. the DID Document format.

On the RDF level, there's no difference between type and @type, the actual underlying data is the same. That's because on the JSON-LD level the Context defines type as an alias for @type (which is a built-in JSON-LD feature). On the DID Document level, the spec is currently requiring type, so that's what I would use in this RFC - don't use @type at all. I would certainly not mix the two as you have in your last example - even though this would be valid JSON-LD, I think it's confusing on the DID Document level.

All the terms have to be defined in a JSON-LD Context, including e.g. recipientKeys, routingKeys, and yes also the value of the type field. Per convention I think that value should be DidCommunication rather than did-communication. You need to create your own Context for this, i.e. https://schema.org won't work because it doesn't define those terms.

JSON-LD allows you to specify a @context at any level of your JSON structure, however the DID Spec currently assumes this to occur only at the top level of the DID Document, not inside a service or serviceEndpoint object. However I don't really see a problem with that; perhaps we should change the DID Spec accordingly so you could specify a @context wherever you want; this could be useful especially if you want to re-use the service or publicKey structures outside of a DID Document.

Perhaps an example could look like this:

{
  "@context": ["https://www.w3.org/2019/did/v1", "https://hyperledger.org/aries/2019/didcomm/v1"],
  "id": "did:example:123456789",
  "publicKey": [{
    "id": "did:example:123456789#keys-1",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:example:123456789",
    "publicKeyBase58" : "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }],
  "service": [{
    "id": "did:example:123456789#didcomm",
    "type": "DidCommunication",
    "priority" : 0,
    "recipientKeys" : [ "did:example:123456789#keys-1" ],
    "routingKeys" : [ "did:example:123456789#keys-1" ],
    "serviceEndpoint": "https://agent.endpoint.org"
  }]
}

You also have an example where the serviceEndpoint is a nested object; that's valid too, personally I would slightly prefer this option here.

[peacekeeper]

Also note that there's an open issue whether the id values for public keys and services should be fully qualified (e.g. did:example:123456789#keys-1) or relative (e.g. #keys-1): w3c-ccg/did-spec#97

[talltree]

Tobias: Markus has given such a superb answer I can't add anything to it. Let us know if you have other questions.

…

On Mon, Aug 26, 2019 at 7:39 PM Markus Sabadello ***@***.***> wrote: Also note that there's an open issue whether the id values for public keys and services should be fully qualified (e.g. did:example:123456789#keys-1) or relative (e.g. #keys-1): w3c-ccg/did-spec#97 <w3c-ccg/did-spec#97> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#125?email_source=notifications&email_token=AAZOITJYXBPA37BPYTTX64DQGSHUXA5CNFSM4ICS6PGKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD5GJAWQ#issuecomment-525111386>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAZOITIJCOPVUSOA4GQZDWDQGSHUXANCNFSM4ICS6PGA> .

[dhh1128]

I think this issue should be revisited when the abstract data model and JSON-LD-in-did-docs discussions settle down after the W3C DID WG F2F this week. For now, I'm assuming that this is closable. If not, please reopen.