Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

CHIP-0017: VC Metadata Structure #66

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

CHIP-0017: VC Metadata Structure #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
093231a
Add CHIP-17 and update status to Draft
danieljperry May 19, 2023
0b869a5
Update CHIP number
danieljperry May 19, 2023
060c378
Add reference to chip-17 schema
danieljperry May 21, 2023
70386b0
Add evidence property
danieljperry May 31, 2023
ea66bfa
Moving CHIP-17 to Stagnant status as it has been inactive for over si…
danieljperry Jan 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
193 changes: 193 additions & 0 deletions CHIPs/chip-0017.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,193 @@
CHIP Number | 0017
:-------------|:----
Title | Chia Verifiable Credentials Structure
Description | A standard for formatting metadata in Verifiable Credentials on Chia's blockchain
Author | [E-ming Saung](https://github.com/esaung)
Editor | [Dan Perry](https://github.com/danieljperry)
Comments-URI | [PR #66](https://github.com/Chia-Network/chips/pull/66)
Status | Stagnant
Category | Process
Sub-Category | Other
Created | 2023-04-25
Requires | [0016](https://github.com/Chia-Network/chips/pull/65)
Replaces | None
Superseded-By | None

## Abstract
This CHIP describes a standard off-chain metadata structure for verifiable credentials that are conformant with the Chia VC1 standard. It borrows heavily from the [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model).

## Definitions
Throughout this document, we'll use the following terms:
* **Must, required, shall** – These words indicate an absolute requirement of the specification
* **Must not, shall not** – These phrases indicate an absolute prohibition of the specification
* **Should, recommended** – These words indicate something that is not a requirement of the specification, but the implications of not following it should be carefully considered beforehand
* **Should not, not recommended** – These phrases indicate something that is not a prohibition of the specification, but the implications of following it should be carefully considered beforehand
* **May** – This word indicates something that is optional. Interoperability between implementations must not be broken because of the choice to implement, or not to implement, this feature

## Motivation
The VC1 standard does not reference any specific format for VCs. In order for credential issuers, security issuers, wallet developers, etc to be able to display and interact with VCs in a consistent manner, a standard metadata structure for VCs is needed.

This CHIP presents a standardized VC metadata structure that conforms to the VC1 standard. It contains an off-chain metadata format, which VCs can reference.

Note that this CHIP is meant to be used as a template for various proof types; it is not intended to function as a standalone metadata standard for VCs. Therefore, this standard does not describe any specific proof values. Instead, complete metadata structures will be standardized in additional CHIPs, starting with [CHIP-18](https://github.com/Chia-Network/chips/pull/67) (KYC VC Structure).

## Backwards Compatibility
This CHIP does not introduce any backward incompatibilities.

## Rationale
The [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/#basic-concepts) provides the industry standard for the metadata structure of VCs. To achieve a wide distribution for Chia VCs, we decided to base the VC1 structure on this model.

## Specification
This section lists each of the properties contained within a VC, including their type, description, and whether they are required.

### @context

| Property | Type | Required | Description |
|:-----------|:---------|:---------|:---------------------------------------------------------------------|
| `@context` | string[] | **Yes** | A mapping of short-form aliases to the URIs required by specific VCs |

A @context is a standardized terminology used by VCs and applications to facilitate the communication of information. The recommended format of the @context property is JSON-LD, though plain JSON is also allowed.

The value of the @context property must be an ordered set where the first item is a URI with the value [https://www.w3.org/2018/credentials/v1](https://www.w3.org/2018/credentials/v1). Subsequent items in the array must express context information and be composed of any combination of URIs or objects.

### Identifier

| Property | Type | Required | Description |
|:---------|:-------|:---------|:---------------------------------------------------------------------------------|
| `id` | string | **No** | An unambiguous referral to an object, such as a person, product, or organization |

In order to allow for pseudonymity, as well as for other considerations, the `id` property is not required.

If the `id` property is used, it must express an identifier that others are expected to use when referencing it. It must be a single URI.

### Format

| Property | Type | Required | Description |
|:---------|:-------|:---------|:--------------------------------|
| `format` | string | **Yes** | CHIP number of the VC structure |

The `format` property identifies the CHIP used to describe the structure of the VC. It must list a single CHIP number. While this CHIP is the first to describe a VC's structure, others may be created in the future. Therefore, the `format` property may point to a CHIP other than this one.

### Type

| Property | Type | Required | Description |
|:---------|:---------|:---------|:---------------------------------------------------------|
| `type` | string[] | **Yes** | Used to determine whether the provided VC is appropriate |

The type is required because it is used to verify the credential. It must be, or map to (through interpretation of the @context property), one or more URIs. If more than one URI is provided, the URIs must be interpreted as an unordered set.

### Credential Subject

| Property | Type | Required | Description |
|:--------------------|:---------|:---------|:-----------------------------|
| `credentialSubject` | object[] | **Yes** | The object of the VC's claim |

A verifiable credential contains claims about one or more subjects. The `credentialSubject` property is a set of objects that contain one or more properties that are each related to a subject of the VC. Each object may contain an `id` such as a DID ID.

### Issuer

| Property | Type | Required | Description |
|:---------|:-----------------|:---------|:---------------------|
| `issuer` | string or object | **Yes** | The issuer of the VC |

The `issuer` property must be either a URI or an object containing an `id` such as a DID.

### Issuance Date

| Property | Type | Required | Description |
|:--------------------|:--------------|:---------|:---------------------------------------|
| `issuanceDate` | string | **Yes** | The date and time the VC becomes valid |

The `issuanceDate` property may be set to a future date/time. It must be a string value of an [XMLSCHEMA11-2](https://www.w3.org/TR/xmlschema11-2/#dateTime) combined date-time string.

### Evidence

Evidence (e.g. a driver's license) can be included by an issuer to provide the verifier with additional supporting information (as opposed to machine-verifiable mathematical proofs from the `proof` property) in a VC. The verifier can then use this evidence to establish the confidence with which it relies on the VC's claims.

The `evidence` property is optional. In cases where this property is used, its value must be one or more evidence schemes providing enough information for a verifier to determine whether the evidence gathered by the issuer meets its confidence requirements for relying on the credential.

The following table lists the required properties, as well as some optional properties. Note that additional properties may also be added as desired:

| Property | Type | Required | Description |
|:-------------------|:---------|:---------|:-----------------------------------------------------------------------------------------------------------------|
| `id` | string | **No** | If used, should contain a URL that points to where more information about this instance of evidence can be found |
| `type` | string[] | **Yes** | The type of evidence used. This property is used to identify the precise contents of each evidence scheme |
| `verifier` | string | **No** | If used, should contain a URL that points to more information about the verifier |
| `evidenceDocument` | string | **No** | The type of document used for this piece of evidence, e.g. "DriversLicense" |
| `subjectPresence` | string | **No** | The subject's location when the evidence was provided, e.g. "Physical" or "Remote" |
| `documentPresence` | string | **No** | The document's presence when the evidence was provided, e.g. "Physical" or "Photocopy" |

### Proof
All W3C conformant VCs require at least one proof mechanism, along with the details necessary to evaluate that proof. This CHIP specifically requires the use of an embedded proof mechanism, where the proof is included in the data.

The following table lists the required `proof` properties for the embedded proof mechanism:

| Property | Type | Required | Description |
|:---------------------|:---------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
| `type` | string | **Yes** | This proof's type |
| `created` | string | **Yes** | The date and time this proof was created. Must be formatted according to [XMLSCHEMA11-2](https://www.w3.org/TR/xmlschema11-2/#dateTime) |
| `verificationMethod` | string | **Yes** | The method to be used to verify this proof. Must be a URI |
| `proofPurpose` | string | **Yes** | The function this proof performs |
| `proofValue` | string | **Yes** | A unique value for this proof. Recommended to be a digital signature |

The following table lists the recommended proof properties for the embedded proof mechanism:

| Property | Type | Required | Description |
|:---------------------|:---------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------|
| `values` | object | No | The specific proofs, the format of which is not specified here |

Additional proof properties also may be added.

### Expiration Date

| Property | Type | Required | Description |
|:-----------------|:-------|:---------|:---------------------------------|
| `expirationDate` | string | No | The date and time the VC expires |

If present, the `expirationDate` property must be a string value of an [XMLSCHEMA11-2](https://www.w3.org/TR/xmlschema11-2/#dateTime) combined date-time string.

### Status

| Property | Type | Required | Description |
|:-------------------|:-------|:---------|:--------------------------------------------------------------------|
| `credentialStatus` | object | No | Gives information about the VC, such as whether it has been revoked |

The `credentialStatus` property is expected to contain enough information to determine the status of the credential. It must contain:
* An `id` property, which must be a URI
* A `type` property, which must be a string. This property expresses the credential status type

### Terms of Use
Can be utilized by an issuer to communicate the terms under which a VC was issued. The value of the `termsOfUse` property must specify one or more terms of use policies under which the creator issued the credential.

| Property | Type | Required | Description |
|:--------------|:-------|:---------|:-----------------------------------------------------------|
| `type` | string | **Yes** | The type of this term of use, for example `IssuerPolicy` |
| `id` | string | No | The unique ID for this term of use. If used, must be a URI |
| `profile` | string | No | The profile for this term of use. If used, must be a URI |
| `obligation` | object | No | An action the verifier is required to perform |
| `prohibition` | object | No | An action the verifier is not allowed to perform |
| `permission` | object | No | An action the verifier is allowed to perform |

#### Actions
Each term of use must specify at least one of `obligation`, `prohibition`, or `permission`. The following table shows the properties associated with these actions:

| Property | Type | Required | Description |
|:-----------|:---------|:---------|:------------------------------------------------------------|
| `assigner` | string | **Yes** | The entity that assigned this action. Must be a single URI |
| `assignee` | string | **Yes** | Specifies to whom this action applies |
| `target` | string | **Yes** | A unique target URI for this action |
| `action` | string[] | **Yes** | The type of action to perform |

## Reference Implementation
See the [Additional Assets](#additional-assets) section of this CHIP.

## Security
The format presented in this CHIP is intended to be conformant with the [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model). As of this writing, this CHIP has yet to be registered with the W3C, so there is a risk that it will not be deemed conformant with the aformentioned Data Model.

## Additional Assets
* JSON Schema dialect: [assets/chip-0017/schema.json](/assets/chip-0017/schema.json)
* Example off-chain metadata file: [assets/chip-0017/example.json](/assets/chip-0017/example.json)


## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
53 changes: 53 additions & 0 deletions assets/chip-0017/example.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://raw.githubusercontent.com/Chia-Network/chips/main/assets/chip-0017/schema.json"
],
"id": "http://example.edu/credentials/3732",
"format": "CHIP-0017",
"type": [
"VerifiableCredential",
"KYCCredential"
],
"credentialSubject": {
"id": "did:chia:1dqpypv6ysru7czlm6vy4vestcjh2ajevp76lgq45yuxsmyw7u5yqxv8fzy"
},
"issuer": "https://example.com/",
"issuanceDate": "2023-01-01T12:00:00Z",
"evidence": [{
"id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231",
"type": ["DocumentVerification"],
"verifier": "https://example.edu/issuers/14",
"evidenceDocument": "DriversLicense",
"subjectPresence": "Remote",
"documentPresence": "Photocopy"
}],
"proof": {
"type": "Signature",
"created": "2023-03-03T12:00:00Z",
"verificationMethod": "https://example.edu/issuers/14#key-1",
"proofPurpose": "KYCCredential",
"proofValue": "0xa61c48269f197a391472791dc409e71e5a8ccd419eb66007699346cd29f7f665691485c63333d88778e2bb37751ec33717c14ffe8b0b8291ce961e0652921a335ada6bf375e7c5d4ae646140646323de893623ccca04d66ce5023217b4ecff43",
"values": {
"over_18": "true",
"nationality": "US",
"residency": "FR"
}
},
"expirationDate": "2028-03-03T12:00:00Z",
"credentialStatus": {
"id": "https://example.edu/status/24",
"type": "KYCCredential"
},
"termsOfUse": [{
"type": "IssuerPolicy",
"id": "http://example.com/policies/credential/4",
"profile": "http://example.com/profiles/credential",
"prohibition": [{
"assigner": "https://example.edu/issuers/14",
"assignee": "AllVerifiers",
"target": "http://example.edu/credentials/3732",
"action": ["Archival"]
}]
}]
}
73 changes: 73 additions & 0 deletions assets/chip-0017/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
{
"$id": "https://raw.githubusercontent.com/Chia-Network/chips/main/assets/chip-0017/schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "CHIP-0017",
"description": "Chia Verifiable Credentials Structure",
"type": "object",
"properties": {
"credentialSchema": {
"@context": {
"@version": 1.1,
"@protected": true,

"id": "@id",
"type": "@type",

"cred": "https://www.w3.org/2018/credentials#",

"JsonSchemaValidator2018": "cred:JsonSchemaValidator2018"
},
"@id": "cred:credentialSchema",
"format": "CHIP-0017",
"@type": "@id",
"credentialSubject": {"@id": "cred:credentialSubject", "@type": "@id"},
"issuer": {"@id": "cred:issuer", "@type": "@id"},
"issuanceDate": {"@id": "cred:issuanceDate", "@type": "xsd:dateTime"},

"evidence": {
"@id": "cred:evidence",
"@type": "@id"
},

"proof": {
"@type": "@vocab",
"created": {"@id": "cred:created", "@type": "xsd:dateTime"},
"verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"},
"proofPurpose": {
"@id": "sec:proofPurpose",
"@type": "@vocab",
"@context": {
"@version": 1.1,
"@protected": true,

"id": "@id",
"type": "@type",

"sec": "https://w3id.org/security#",

"assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
"authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
}
},
"proofValue": "sec:proofValue",
"values": {
"type": [
"string",
"string"
]
}
},
"expirationDate": {
"@id": "cred:expires",
"@type": "xsd:dateTime"}
},
"credentialStatus": {
"@id": "@id",
"@type": "@type"
},
"termsOfUse": {
"@id": "cred:termsOfUse",
"@type": "@id"
}
}
}
Loading