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.
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.
The following use cases outline a number of key scenarios that readers might find useful:
This vocabulary assumes all classes and terms specified in the base Verifiable Credentials [[VC-DATA-MODEL]] context.
The following classes are available for specifying information related to residency, employment, and citizenship status.
| Class | Description |
|---|---|
| QuantitativeValue | A point value or interval for product characteristics and other purposes. Used with `height`. |
| PostalAddress | A mailing address. |
| Person | Specifies that the subject of the credential is a person. |
| PermanentResident | Specifies that the subject of the credential is a permanent resident. |
| PermanentResidentCard | Specifies that the object is a Permanent Resident Card. |
| PermanentResidentCardCredential | Specifies that the credential is a permanent resident card credential. |
| EmployablePerson | Specifies that the subject of the credential is authorized for employment. |
| EmploymentAuthorizationDocument | Specifies that the object is a Employment Authorization Document. |
| EmploymentAuthorizationDocumentCredential | Specifies that the credential is a Employment Authorization Document credential. |
| NaturalizedPerson | Specifies that the subject of the credential is a naturalized person. |
| CertificateOfNaturalization | Specifies that the object is a Certificate of Naturalization. |
| CertificateOfNaturalizationCredential | Specifies that the credential is a Certificate of Naturalization credential. |
| Citizen | Specifies that the subject of the credential is a citizen. |
| CertificateOfCitizenship | Specifies that the object is a Certificate of Citizenship. |
| CertificateOfCitizenshipCredential | Specifies that the credential is a Certificate of Citizenship credential. |
This document also specifies the following terms for expressing residency, employment, and citizenship status:
| Term | Description |
|---|---|
| additionalName | An additional name for a Person, can be used for a middle name. |
| addressCountry | The country code provided as a two-letter ISO 3166-1 alpha-2 country code. |
| addressLocality | The locality of within an `addressRegion`. |
| addressRegion | The region within an `addressCountry`. |
| birthCountry | The country in which a individual was born. |
| birthDate | The date on which a individual was born. |
| certificateOfNaturalization | The `CertificateOfNaturalization` of the Person. |
| certificateOfCitizenship | The `CertificateOfCitizenship` of the Person. |
| cisRegistrationNumber | The registration identifier which is used to identify the citizen by the country's official body for making such a determination. |
| commuterClassification | A code that specifies whether an individual lives in a specific country or commutes across a border to work. |
| employmentAuthorizationDocument | The EmploymentAuthorizationDocument of the Person. |
| familyName | The name of the family with which the individual identifies. |
| filingLocation | The `PostalAddress` where paperwork was filled. |
| formerNationality | The Person's country of former nationality presented as a two-letter ISO 3166-1 alpha-2 country code. |
| gender | The gender of the individual. |
| givenName | The non-family name with which the individual identifies. |
| height | The height of the item. |
| image | A representative image of the individual. |
| insRegistrationNumber | The registration identifier which is used to identify the naturalized person by the country's official body for making such a determination. |
| 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. |
| maritalStatus | The current marital relationship status of the Person. Example: married, single, divorced, widowed, previously married, etc. |
| marriageCertificateNumber | Certificate of Marriage identification number. |
| marriageLocation | The `PostalAddress` of the previously performed marriage ceremony. |
| naturalizationLocation | The `PostalAddress` where naturalization occurred. |
| naturalizedBy | The entity that performed the naturalization. |
| permanentResidentCard | The permanent resident card of the Person. |
| residence | The `PostalAddress` in which the `Person` currently resides. |
| residentSince | The date from which the individual is considered a resident. |
| unitCode | The unit of measurement given using the UN/CEFACT Common Code (3 characters) or a URL. Other codes than the UN/CEFACT Common Code may be used with a prefix followed by a colon. Used with `height`. |
| value | The value of a `QuantitativeValue`. Used with `height`. |
An additional name for a Person, can be used for a middle name.
| Term | additionalName |
| URL | https://schema.org/additionalName |
| Expected Value | string |
The country code provided as a two-letter ISO 3166-1 alpha-2 country code.
| Term | addressCountry |
| URL | https://schema.org/addressCountry |
| Expected Value | string |
The locality of within an `addressRegion`.
| Term | addressLocality |
| URL | https://schema.org/addressLocality |
| Expected Value | string |
The region within an `addressCountry`.
| Term | addressRegion |
| URL | https://schema.org/addressRegion |
| Expected Value | string |
The country in which a individual was born.
| Term | birthCountry |
| URL | https://schema.org/birthCountry |
| Expected Value | string |
The date on which a individual was born.
| Term | birthDate |
| URL | https://schema.org/birthDate |
| Expected Value | Datetime |
Specifies that the object is a Certificate of Citizenship.
| Term | CertificateOfCitizenship |
| URL | https://w3id.org/citizenship#CertificateOfCitizenship |
The `CertificateOfCitizenship` of the Person.
| Term | certificateOfCitizenship |
| URL | https://w3id.org/citizenship#certificateOfCitizenship |
| Expected Value | CertificateOfCitizenship |
Specifies that the credential is a Certificate of Citizenship credential.
| Term | CertificateOfCitizenshipCredential |
| URL | https://w3id.org/citizenship#CertificateOfCitizenshipCredential |
Specifies that the object is a Certificate of Naturalization.
| Term | CertificateOfNaturalization |
| URL | https://w3id.org/citizenship#CertificateOfNaturalization |
The `CertificateOfNaturalization` of the Person.
| Term | certificateOfNaturalization |
| URL | https://w3id.org/citizenship#certificateOfNaturalization |
| Expected Value | CertificateOfNaturalization |
Specifies that the credential is a Certificate of Naturalization credential.
| Term | CertificateOfNaturalizationCredential |
| URL | https://w3id.org/citizenship#CertificateOfNaturalizationCredential |
The registration identifier which is used to identify the citizen by the country's official body for making such a determination.
| Term | cisRegistrationNumber |
| URL | https://w3id.org/citizenship#cisRegistrationNumber |
| Expected Value | string |
Specifies that the subject of the credential is a citizen.
| Term | Citizen |
| URL | https://w3id.org/citizenship#Citizen |
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 |
Specifies that the subject of the credential is authorized for employment.
| Term | EmployablePerson |
| URL | https://w3id.org/citizenship#EmployablePerson |
Specifies that the object is a Employment Authorization Document.
| Term | EmploymentAuthorizationDocument |
| URL | https://w3id.org/citizenship#EmploymentAuthorizationDocument |
The EmploymentAuthorizationDocument of the Person.
| Term | employmentAuthorizationDocument |
| URL | https://w3id.org/citizenship#employmentAuthorizationDocument |
| Expected Value | EmploymentAuthorizationDocument |
Specifies that the credential is a Employment Authorization Document credential.
| Term | EmploymentAuthorizationDocumentCredential |
| URL | https://w3id.org/citizenship#EmploymentAuthorizationDocumentCredential |
The name of the family with which the individual identifies.
| Term | familyName |
| URL | https://schema.org/familyName |
| Expected Value | string |
The `PostalAddress` where paperwork was filled.
| Term | filingLocation |
| URL | https://w3id.org/citizenship#filingLocation |
| Expected Value | string |
The Person's former nationality presented as a two-letter ISO 3166-1 alpha-2 country code.
| Term | formerNationality |
| URL | https://w3id.org/citizenship#formerNationality |
| Expected Value | string |
The gender of the individual.
| Term | gender |
| URL | https://schema.org/gender |
| Expected Value | string |
The non-family name with which the individual identifies.
| Term | givenName |
| URL | https://schema.org/givenName |
| Expected Value | string |
The height of the item expressed as a QuantitativeValue.
| Term | height |
| URL | https://schema.org/height |
| Expected Value | QuantitativeValue |
An alternate identifier used by the issuer of the credential to refer to information associated with the credential.
| Term | identifier |
| URL | https://schema.org/identifier |
| Expected Value | string |
A representative image of the individual.
| Term | image |
| URL | https://schema.org/image |
| Expected Value | URL |
The registration identifier which is used to identify the naturalized person by the country's official body for making such a determination.
| Term | insRegistrationNumber |
| URL | https://w3id.org/citizenship#insRegistrationNumber |
| Expected Value | string |
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 |
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 |
The current marital relationship status of the Person. Example: married, single, divorced, widowed, previously married, etc.
| Term | maritalStatus |
| URL | https://w3id.org/citizenship#maritalStatus |
| Expected Value | string |
Certificate of Marriage identification number.
| Term | marriageCertificateNumber |
| URL | https://w3id.org/citizenship#marriageCertificateNumber |
| Expected Value | string |
The `PostalAddress` of the previously performed marriage ceremony.
| Term | marriageLocation |
| URL | https://w3id.org/citizenship#marriageLocation |
| Expected Value | PostalAddress |
The `PostalAddress` where naturalization occurred.
| Term | naturalizationLocation |
| URL | https://w3id.org/citizenship#naturalizationLocation |
| Expected Value | PostalAddress |
The entity that performed the naturalization.
| Term | naturalizedBy |
| URL | https://w3id.org/citizenship#naturalizedBy |
| Expected Value | URL |
Specifies that the subject of the credential is a naturalized person.
| Term | NaturalizedPerson |
| URL | https://w3id.org/citizenship#NaturalizedPerson |
Specifies that the subject of the credential is a permanent resident.
| Term | PermanentResident |
| URL | https://w3id.org/citizenship#PermanentResident |
Specifies that the credential is a permanent resident card.
| Term | PermanentResidentCard |
| URL | https://w3id.org/citizenship#PermanentResidentCard |
The permanent resident card of a legal permanent resident.
| Term | permanentResidentCard |
| URL | https://w3id.org/citizenship#permanentResidentCard |
| Expected Value | PermanentResidentCard |
Specifies that the credential is a permanent resident card credential.
| Term | PermanentResidentCardCredential |
| URL | https://w3id.org/citizenship#PermanentResidentCardCredential |
Specifies that the subject of the credential is a person.
| Term | Person |
| URL | https://schema.org/Person |
A mailing address.
| Term | PostalAddress |
| URL | https://schema.org/PostalAddress |
A point value or interval for product characteristics and other purposes.
| Term | QuantitativeValue |
| URL | https://schema.org/QuantitativeValue |
The `PostalAddress` in which the `Person` currently resides.
| Term | residentSince |
| URL | https://w3id.org/citizenship#residence |
| Expected Value | PostalAddress |
The date from which the individual is considered a resident.
| Term | residentSince |
| URL | https://w3id.org/citizenship#residentSince |
| Expected Value | Datetime |
The unit of measurement given using the UN/CEFACT Common Code (3 characters) or a URL. Other codes than the UN/CEFACT Common Code may be used with a prefix followed by a colon. Used with `height`.
| Term | unitCode |
| URL | https://schema.org/unitCode |
| Expected Value | string |
The value of a `QuantitativeValue`. Used with `height`.
| Term | value |
| URL | https://schema.org/unitCode |
| Expected Value | Number |
This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.
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.
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.
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.
Note: `v2` is deprecated in favor of v3.