Modeling Travel Use Case as an extension example

[dlongley]

The aim of this issue is to hash out some example VCs that would address the Travel Use Case. To close this issue out we'd create a PR that adds the examples we get consensus on to a "guidance on writing extensions" section in the data model spec.

There are potentially four VCs to model here: Malathi's passport, Anand's passport, Anand's birth certificate, and Rajesh's child travel pass ("permission to travel").

I've modeled Malathi's passport in two different ways to get some feedback. The first way is simpler in that it just makes claims about Malathi without any concept of an additional "passport document". This deviates from how people understand passports to work today so I've included a second model that makes a claim that Malathi holds a "passport document" with a certain identifier etc. Our data model supports both approaches.

Malathi's passport (simple model):

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.com/travel-vocab/v1"
  ],
  "id": "urn:uuid:9f6878c8-73c7-11e8-ab37-23a1a3504fd0",
  "type": ["VerifiableCredential", "PassportCredential"],
  /* gov't DID */
  "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV",
  "expires": "2028-01-01T00:00:00Z",
  "claim": {
    "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4",
    "givenName": "Malathi",
    "familyName": "Hamal",
    "citizenship": "US",
    /* any other claims made by gov't */
  },
  "proof": {/* signature by gov't */}
}

Malathi's passport (passport is a document model):

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.com/travel-vocab/v1"
  ],
  "id": "urn:uuid:9f6878c8-73c7-11e8-ab37-23a1a3504fd0",
  "type": ["VerifiableCredential", "PassportCredential"],
  /* gov't DID */
  "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV",
  "expires": "2028-01-01T00:00:00Z",
  "claim": {
    "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4",
    "passport": {
      "id": "urn:uuid:79c181dc-73c7-11e8-8c1f-2bb1fd2d268a",
      "type": "Passport",
      "traveler": {
        "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4",
        "givenName": "Malathi",
        "familyName": "Hamal",
        "citizenship": "US"
      },      
      /* any other passport fields */
    }
  },
  "proof": {/* signature by gov't */}
}

Anand's passport:

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.com/travel-vocab/v1"
  ],
  "id": "urn:uuid:b306614c-73c7-11e8-b596-47e8c5ce9144",
  "type": ["VerifiableCredential", "PassportCredential"],
  /* gov't DID */
  "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV",
  "expires": "2020-01-01T00:00:00Z",
  "claim": {
    "id": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu",
    "givenName": "Anand",
    "familyName": "Hamal"
    "citizenship": "US",
    /* any other claims made by gov't */
  },
  "proof": {/* signature by gov't */}
}

Anand's birth certificate:

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.com/travel-vocab/v1"
  ],
  "id": "urn:uuid:05a47fe2-73c8-11e8-ac1e-7fe0051a1d75",
  "type": ["VerifiableCredential", "PassportCredential"],
  /* gov't DID */
  "issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV",
  "expires": "2020-01-01T00:00:00Z",
  "claim": {
    "id": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu",
    "citizenship": "US",
    "birthDate": "2017-10-01T00:00:00Z",
    "birthPlace": {
      "type": "Hospital",
      "address": {
        "addressLocality": "Denver",
        "addressRegion": "CO",
        "postalCode": "80209",
        "streetAddress": "123 Main St."
      }      
    },
    "givenName": "Anand",
    "familyName": "Hamal",
    "parent": [{
      "id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4",
      "type": "Person",
      "givenName": "Malathi",
      "familyName": "Hamal",
      "maidenName": "Holla"
    }, {
      "id": "did:example:BgXRjB4RPrrsUVoVNaYNwzfznKsWep7AWrZkiyVcorEN",
      "type": "Person",
      "givenName": "Rajesh",
      "familyName": "Hamal"
    }]
  },
  "proof": {/* signature by gov't */}
}

Permission to travel from Rajesh
Used schema.org vocab here -- could have used activitystreams vocab

{
  "@context": [
    "https://w3id.org/credentials/v1",
    "https://example.com/travel-vocab/v1"
  ],
  "id": "urn:uuid:58c08196-73c6-11e8-b030-3bd8a829a356",
  "type": ["VerifiableCredential", "ChildTravelPass"],
  "issuer": "did:example:BgXRjB4RPrrsUVoVNaYNwzfznKsWep7AWrZkiyVcorEN",
  "expires": "2018-07-01T00:00:00Z",
  "claim": {
    "id": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu",
    "potentialAction": {
      "type": "TravelAction",
      "agent": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu",
      "participant": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4",
      "location": {
        "type": "Country",
        "address": {
          "addressCountry": "CA"
        }
      }
    }
  },
  "proof": {/* signature by Rajesh proving control of DID */}
}

[David-Chadwick]

These are broadly OK. Comments I have on the various VCs are

1. Birth certificate

The type property in the birth certificate should of course be

"type": ["VerifiableCredential", "BirthCertificate"],

and not

"type": ["VerifiableCredential", "PassportCredential"],

and the address object also ideally needs a type property because this address is US centric and not globally recognised, which leads to the following

{
	"@context": [
		"https://w3id.org/credentials/v1",
		"https://example.com/travel-vocab/v1"
	],
	"id": "urn:uuid:05a47fe2-73c8-11e8-ac1e-7fe0051a1d75",
	"type": ["VerifiableCredential", "BirthCertificate"],
	"issuer": "did:example:CCnF3zFaXkPN4zB94XaomRdvw2zX3XHPVX3aExcgo6PV",
	"expires": "2020-01-01T00:00:00Z",
	"claim": {
		"id": "did:example:8vFBbPrhBUyG6DEzVncBZpzBNsmRrbfsQKXQKPLskBCu",
		"citizenship": "US",
		"birthDate": "2017-10-01T00:00:00Z",
		"birthPlace": {
			"type": "Hospital",
			"address": {
				"type": "US address",
				"addressLocality": "Denver",
				"addressRegion": "CO",
				"postalCode": "80209",
				"streetAddress": "123 Main St."
			}
		},
		"givenName": "Anand",
		"familyName": "Hamal",
		"parent": [{
			"id": "did:example:BcRisGnqV4QPb6bRmDCqEjyuubBarS1Y1nhDwxBMTXY4",
			"type": "Person",
			"givenName": "Malathi",
			"familyName": "Hamal",
			"maidenName": "Holla"
		}, {
			"id": "did:example:BgXRjB4RPrrsUVoVNaYNwzfznKsWep7AWrZkiyVcorEN",
			"type": "Person",
			"givenName": "Rajesh",
			"familyName": "Hamal"
		}]
	},
	"proof": {/* signature by gov't */}
}

2. Permission to Travel.

I would say the claim property should be "childTravelPass" and not "potentialAction". The latter semantics are too vague.

3. Use of type property

Please also see my comment in #182 concerning the use of the type property.

[stonematt]

Types like the one you call out on address are in the domain of @context and will be agreed upon between the issuer and verifier. As long as the data model supports this sort of industry specific negotiation, then we've done what's required to move ahead.

The Type at the top level "VerifiableCredential" is one that we specify w/ some bare minimum content. Types such as "BirthCertificate" not ours to define, as long as the issuer can declare it in a way that the verifier can accept it, the data model is good.

I recommend that @dlongley make a PR with this example in the data model spec, incorporating @David-Chadwick tweaks.

[stonematt]

There was a suggestion on the weekly call to make an example document that shows how the specification addresses (some or all of) the use cases.

we'll have to remember to keep them aligned with the data model spec as it evolves over time.

[stonematt]

will work to either

1. integrate the example into the use case document or
2. make a separate example document that references the UC doc.

[stonematt]

Added as an appendix section in the Use Case document in PR86 w3c/vc-use-cases#86