This specification describes a Linked Data vocabulary for asserting Verifiable Credentials related to residency and citizenship information, such as given name, family name, country of citizenship, birthday, and other attributes used to determine the citizenship status of a citizen.

Introduction

This specification describes a Linked Data vocabulary for asserting Verifiable Credentials related to citizenship information, such as given name, family name, country of citizenship, birthday, and other attributes used to determine the citizenship status of a citizen.

Use Cases and Requirements

The following use cases outline a number of key scenarios that readers might find useful:

Example

The following example is provided as a simple example of when this vocabulary is useful:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/citizenship/v1"
    // optional country-specific context can be added below
    // e.g., https://uscis.gov/prc/v1
  ],
  "id": "https://issuer.oidp.uscis.gov/credentials/83627465",
  "type": ["VerifiableCredential", "PermanentResidentCard"],
  "issuer": "did:example:28394728934792387",
  "identifier": "83627465",
  "name": "Permanent Resident Card",
  "description": "Government of Example Permanent Resident Card.",
  "issuanceDate": "2019-12-03T12:19:52Z",
  "expirationDate": "2029-12-03T12:19:52Z",
  "credentialSubject": {
    "id": "did:example:b34ca6cd37bbf23",
    "type": ["PermanentResident", "Person"],
    "givenName": "JOHN",
    "familyName": "SMITH",
    "gender": "Male",
    "image": "data:image/png;base64,iVBORw0KGgo...kJggg==",
    "residentSince": "2015-01-01",
    "lprCategory": "C09",
    "lprNumber": "999-999-999",
    "commuterClassification": "C1",
    "birthCountry": "Bahamas",
    "birthDate": "1958-07-17"
  },
  "proof": {
     "type": "Ed25519Signature2018",
     "created": "2020-01-30T03:32:15Z",
     "jws": "eyJhbGciOiJFZERTQSIsI...wRG2fNmAx60Vi4Ag",
     "proofPurpose": "assertionMethod",
     "verificationMethod": "did:example:28394728934792387#keys-7f83he7s8"
  }
}
        

Terminology

The Citizenship Vocabulary

This vocabulary assumes all terms specified in the base Verifiable Credentials [[VC-DATA-MODEL]] context. In addition, the following classes are available for specifying information related to residency and citizenship status.

Class Description
PermanentResident Specifies that the subject of the credential is a permanent resident.
PermanentResidentCard Specifies that the credential is a permanent resident card.
Person Specifies that the subject of the credential is a person.

This document also specifies the following terms for expressing residency and citizenship status:

Term Description
birthCountry The country in which a individual was born.
birthDate The date on which a individual was born.
commuterClassification A code that specifies whether an individual lives in a specific country or commutes across a border to work.
familyName The name of the family with which the individual identifies.
gender The gender of the individual.
givenName The non-family name with which the individual identifies.
image A representative image of the individual.
lprCategory The category for a legal permanent resident as specified by the country's official body for making such a determination.
lprNumber The identifier which is used to identify the legal permanent resident by the country's official body for making such a determination.
residentSince The date from which the individual is considered a resident.

birthCountry

The country in which a individual was born.

Term birthCountry
URL http://schema.org/birthCountry
Expected Value string

birthDate

The date on which a individual was born.

Term birthDate
URL http://schema.org/birthDate
Expected Value Datetime

commuterClassification

A code that specifies whether an individual lives in a particular country or commutes across a border to work.

Term commuterClassification
URL https://w3id.org/citizenship#commuterClassification
Expected Value String

familyName

The name of the family with which the individual identifies.

Term familyName
URL http://schema.org/familyName
Expected Value string

gender

The gender of the individual.

Term gender
URL http://schema.org/gender
Expected Value string

givenName

The non-family name with which the individual identifies.

Term givenName
URL http://schema.org/givenName
Expected Value string

identifier

An alternate identifier used by the issuer of the credential to refer to information associated with the credential.

Term identifier
URL http://schema.org/identifier
Expected Value string

image

A representative image of the individual.

Term image
URL http://schema.org/image
Expected Value string

lprCategory

The category for a legal permanent resident as specified by the country's official body for making such a determination.

Term lprCategory
URL https://w3id.org/citizenship#lprCategory
Expected Value string

lprNumber

The identifier which is used to identify the legal permanent resident by the country's official body for making such a determination.

Term lprNumber
URL https://w3id.org/citizenship#lprNumber
Expected Value string

PermanentResidentCard

Specifies that the credential is a permanent resident card.

Term PermanentResidentCard
URL https://w3id.org/citizenship#PermanentResidentCard
Expected Value Class

PermanentResident

Specifies that the subject of the credential is a permanent resident.

Term PermanentResident
URL https://w3id.org/citizenship#PermanentResident
Expected Value Class

Person

Specifies that the subject of the credential is a person.

Term Person
URL http://schema.org/Person
Expected Value Class

residentSince

The date from which the individual is considered a resident.

Term residentSince
URL https://w3id.org/citizenship#residentSince
Expected Value Datetime

Privacy Considerations

This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.

Security Considerations

There are a number of security considerations that implementers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.

While this section attempts to highlight a broad set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.

Accessibility Considerations

There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standards or protocols implementation, ignoring accessibility issues makes this information unusable to a large subset of the population. It is important to follow accessibility guidelines and standards, such as [[WCAG21]], to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.

This section details the general accessibility considerations to take into account when utilizing this data model.

Internationalization Considerations

There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.

This section outlines general internationalization considerations to take into account when utilizing this data model.