Data dictionary (v2)
On this page you will find definitions and explanations for the data types used in the Passport XYZ stack. The Scorer, Stamp , Credential and Stamp-metadata objects require the most explanation so they are handled separately here.
The Scorer object
| Value | Type | Description | How to use |
|---|---|---|---|
address | String (hexadecimal address) | The string of 20 bytes that uniquely identify an Ethereum account | Identifies a specific account to which the payload's data relates. |
score | String (numeric value as a string) | The registry/score endpoint returns a string that should be parsed as a float. It represents the result of adding the weights of all a user's Stamps. | If you'd like to use your own score threshold, you can compare this score against that threshold to identify which users should be provided access. |
passing_score | Boolean | Passing score will return either true or false as its value, depending on whether the user's score exceeded the threshold score of 20, as recommended by the Passport team. You can also choose your own score threshold and use the score value if you'd prefer. | If you'd like to use the Passport recommended score threshold, you can use this value to identify which users should be provided access. |
last_score_timestamp | String (ISO 8601 datetime) | The date and time of the request. | Can be used to identify when the snapshot of this data occured. |
expiration_timestamp | String (ISO 8601 datetime) | The date and time that the next Stamp will expire, which will subsequently reduce the score. To see when each specific Stamp expires, please use the GET /v2/stamps{address} endpoint. | You might want to display this score expiration to the user to remind them to return to the Passport app to refresh their score before it expires |
threshold | String (numeric value as a string) | The Passport recommended score threshold that the user's score must exceed to be considered passing. The current recommended threshold is 20. You can also choose your own score threshold and use the score value if you'd prefer. | If you'd like to use the Passport recommended score threshold, you can use this value to identify which users should be provided access. |
error | String | Describes any error returned by the server. Refer to the API status and error codes page for more information. | Can be used to understand why a request failed. |
stamps | Object | Contains simplified credential objects for each credential that has been validated by the specified user. This object was introduced on December 29th, 2023, and is not available via the historical score endpoint before this point. | The included credential objects within this object are the credentials that the user has verified. |
stamps.<credential_name>.score | String (numeric value as a string) | The specific weight, or score, that this verified credential contributes to your overall unique humanity score, or score, above.If this specific credential is deduped, this score will be zero (0). | Can be used to understand how the overall unique humanity score was calculated. |
stamps.<credential_name>.dedup | Boolean | If this specific credential has been deduplicated (in other words, if this same credential has been verified by another address), this boolean will come back as true.IF true, the credential's score will be zero (0) and the credential's expiration date will represent when the credential verified by the other address will expire, rather than when this credential will expire. | This information can be used both to identify why a user's score is lower than expected and to publicly communicate these reasons to the user. |
stamps.<credential_name>.expiration_date | String (ISO 8601 datetime) | Notes when this specific credential will expire. If this specific credential is deduped, this expiration date will represent when the credential verified by the other address will expire, rather than when this credential will expire. | This information can be displayed to users to help them understand when their credential will expire. |
The Stamp object
| Value | Type | Description | How to use |
|---|---|---|---|
credential | object | Message displayed in the Passport Scorer app alongside a button to trigger verification of a specific Stamp See Credentials table below for more details. | This is what a Stamp actually comprises. It is associated with an Ethereum address. |
items | array<stamp> | An array containing data for each individual Stamp. | Each object in this array represents a specific Stamp. |
metadata | object | Metadata is a object containing id, icon, name, description, and connectMessage fields for each provider and then more granular data for each of the provider's Stamps | Returned from the GET /v2/stamps/{address} endpoint if the parameter include-metadata=true is also passed. Returned from GET v2/stamps/metadata endpoint for all Stamps |
next | string | A pointer to the next page of returned data, if the returned data has been paginated. | You can use this is a request to access a page and the subsequent page of results for a paginated response. If the value is null you are already seeing all the available information. |
prev | string | A pointer to the preceding page of returned data, if the returned data has been paginated. | You can use this is a request to access a page and the previous page of results for a paginated response. If the value is null you are already seeing all the available information. |
version | string | A version identifier for a Stamp | Returned for each Stamp from GET /v2/stamps{address} |
Credentials
A credential is a object returned in the Stamp object. Learn more about Verifiable Credentials via their w3 specification (opens in a new tab).
This object has its own sub-fields as follows:
| Value | Type | Description | How to use |
|---|---|---|---|
type | string | A descriptor that shows what type of credential is present | Can be used to check that the returned data is of the expected objecture for a given credential type. This is usually going to have the value VerifiableCredential. |
proof | object | A object containing several fields comprising the proof that a certain action was taken, for example a signed auth token proving that an account was unlocked. | Used to verify ownership of a specific Stamp |
issuer | hash | Each Stamp issuer has a specific identifying hash provided in this field. | Used to identify a Stamp issuer |
@context | url | Link to the credential definition documentation. | Can be used to access reference documentation for the credential type |
issuanceDate | datetime string | The date and time that the Stamp was minted. ISO 8601, "2023-04-28T09:35:49.159Z" | Can be used to check the age of a Stamp |
expirationDate | datetime string | The date and time the Stamp should expire. ISO 8601, "2023-04-28T09:35:49.159Z" | Can be used to automatically expire a Stamp |
credentialSubject | object | Contains anonymized information about the user that the Stamp is issued to. This includes a unique ID, a hash, link to the data schema and the Stamp provider name in plaintext. | Can be used to connect Stamps to a user in a privacy preserving way |
Stamp metadata
| Value | Type | Description | How to use |
|---|---|---|---|
connectMessage | string | Message displayed in the Passport scorer app alongside a button to trigger verification of a specific Stamp | Mainly used in the Passport app, but could be used to provide appropriate message for verification in other contexts |
description | string | Short description of what a specific Stamp demonstrates. For example, ownership of >0.5 ETH | Returned in Stamp metadata, can be used to understand a specific Stamp |
groups | string | Identifier for top-level groupings of Stamps for a given provider | Each provider may issue many Stamps which can be grouped together by theme, for example the Passport Provider groups Stamps by Self GTC-staking and Community GTC-staking |
hash | string | A unique hash representing a specific instance of a credential | Used to prevent the same Stamp being used multiple times in a specific Scorer instance |
icon | string | A URL for an image to represent each Stamp provider | Returned in Stamp metadata, can be used to load an icon for a Stamp provider |
id | string | An identifier for a Stamp | Returned in Stamp metadata, can be used to scrape data for a specific Stamp |
name | string | Name of the provider issuing a given Stamp | Returned as part of the Stamp metadata, can be used to scrape information for specific providers |
stamps | array | Array containing Stamp objects for each individual Stamp. Each Stamp has name, description and hash fields | Included in Stamp metadata. Used to identify specific instances of individual Stamps |