Evidence, Related Links, Related Documents and Hashlinks what should we use?

[mkhraisha]

This issue is meant as a continuation of the thread on the mailing list with the goal of attempting to find a solution that we can standardize around in this vocabulary.

The Issue:

How do we reference a supply chain credential from another credential?
To illustrate the use case consider a Transportation Event Credential that represents a Transportation Event that a Product underwent, and has an associated Bill Of Lading Credential. The Transportation Event Credential wants to reference the Product Credential and the Bill of Lading Credential.

There are two parts to this question, how can we reference other credentials and where can we put that reference.

Ways to reference other credentials:

1. URI that points to a hosted VC with the Product and Bill Of Lading objects

{
    // rest of VC
    "credentialSubject": {
        "type": [
            "TransportationEvent"
        ],
        // rest of eventVC
        "product": "example.com/product/123",
        "BillOfLading": "example.com/billoflading/123"
    }
}

2. Hashlink that points to the hosted VCs

{
    // rest of VC
    "credentialSubject": {
        "type": [
            "TransportationEvent"
        ],
        // rest of eventVC
        "product": "http://example.com/product/123?hl=zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e",
        "BillOfLading": "http://example.org/billoflading/123?hl=zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e"
    }
}

3. Directly embed the other credential // this seems pretty awful

Places to put the reference

1. In the credential directly under a vocabulary defined property such as product or bill of lading

{
    // rest of VC
    "credentialSubject": {
        "type": [
            "TransportationEvent"
        ],
        // rest of eventVC
        "product": "REFERENCE HERE"
        "BillOfLading": "REFERENCE HERE"
    }
}

2. In the Evidence property as defined by the VC data model

{
    // rest of VC
    "credentialSubject": {
           "type": [
            "TransportationEvent"
        ],
        // rest of eventVC
    },
    "evidence": [
    // obviously this will need to be compliant with VC data model evidence property
        {
          "REFERENCE HERE for product"
        },
        {
            "REFERENCE HERE for the event"
        }
    ]
}

3. as a Related Link

{
    // rest of VC
    "credentialSubject":{
        "type": [
            "TransportationEvent"
        ],
        "relatedLink": [
            {
              "type": [
                "LinkRole"
              ],
              "target": "REFERENCE HERE",
              "linkRelationship": "Product"
            },
            {
              "type": [
                "LinkRole"
              ],
              "target": "REFERENCE HERE",
              "linkRelationship": "Bill of Lading"
            }
          ]
          // rest of eventVC
    }
}

4. as a Related Document // I have not found an example of this would love it if anyone can point to it.

Considerations:

1. You might want to change that data being referenced without breaking the signature
2. You might want the signature to break if the data behind it changes
3. You might want to add new data behind the URI after the credential was issued
4. The data behind the URI might be several orders of magnitude larger than the credential (like a large ML model / or training set).

Personal Opinion

I think it is probably best NOT to go with a hash link as it adds another layer of complexity and makes it harder for adoption.
I think it is probably best NOT to go with evidence in its current state, however, I think this is probably the best long-term place for it if we can fix the numerous issues around evidence property.

I think it is probably best to go with a URI in either the related links or in the property directly defined in the object.

[mkhraisha]

@OR13 @mprorock we talked about this issue on a call, did either of you have any opinions on this?

[OR13]

@nissimsan @BenjaminMoe please weigh in first

[OR13]

See also: https://github.com/digitalbazaar/vc-js/blob/a15758709d71bd49346e62c80b250853da041e41/test/10-verify.spec.js#L444

[OR13]

Of these options evidence seems the most relevant... related links has semantics inherited from schema.org...

https://schema.org/relatedLink

[BenjaminMoe]

Looks like we should be using related link?

[TallTed]

There appear to be two things being discussed here.

First, what are the semantics of the relation to be expressed? These should be compared to the semantics of the relation denoted by the identifier being contemplated. If they match, that relation can be used. If they do not match, that relation must not be used. Evidence should be a fairly strong relation; Related Links (schema:relatedLink) and/or Related Documents are expected to be a fairly weak relation. Hashlinks are not a relation, and so are irrelevant to this question

Second, there is the question of the the structure of the URI to be used for this related entity, and how deep and/or refined it may be. Evidence, Related Links (schema:relatedLink), and Related Documents are relations, not entity identifiers. Hashlinks can be used for precise identification of entities, but it's not clear whether they are appropriate for the relations being contemplated.

In all of these cases, we should be discussing things that are clearly identified by URI (dereferencing which leads to their definition/description) — not things that are ambiguously identified by string literals which have no clear definition/description and/or which definition/description vary with each commenter and each comment.

[nissimsan]

I need an example with ids to respond to this.

Given a PO from a buyer:

{
  "type": ["PurchaseOrder"],
  "id": "did:web:buyer.example.com:purchaseOrder:123",
  "itemsOrdered": [...],
}

And countering CI from the seller:

  "type": ["CommercialInvoice"], 
  "id": "did:web:seller.example.com:commercialInvoice:abc",
  "purchaseOrder": "did:web:buyer.example.com:purchaseOrder:123",
  "relatedLink": [
      {
        "type": ["LinkRole"],
        "target": "https://buyer.example.com/purchaseOrder/123.json",
        "linkRelationship": "Purchase Order"
      }
  "itemsShipped": [...]

I propose that we separate links to where a VC might be hosted from references to other VCs:

References are done by referencing verifiableCredential.id. In the example, the CI refers to did:web:buyer.example.com:purchaseOrder:123.

Indication of where a VC might be hosted is captured with a relatedLink. In the example the Purchase Order is available on https://buyer.example.com/purchaseOrder/123.json.

evidence is meant to describe "additional supporting information" about the process in which a VC was issued. It would be inappropriate to overload it with VC references.

[mkhraisha]

We have external resource in the vocab right now, is it a good idea to switch everything over to it?
Disadvantage of using external resource is you go from:

{
   "product": "http://example.com/product/123?hl=zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e"
}

to:

{
   "product": {
       "type" : ["ExternalResource"],
       "uri": "http://example.com/product/123",
       "hash": "zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e"
}

@OR13 @mprorock

[nissimsan]

Shame, @BenjaminMoe and @nissimsan

[mkhraisha]

@BenjaminMoe @nissimsan any updates on this?

[mkhraisha]

VC dat amodel 2.0 provides a solution which is: https://www.w3.org/TR/vc-data-model-2.0/#integrity-of-related-resources