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 | The string of 20 bytes that uniquely identify an Ethereum account | Identifies a specific account to which the payload's data relates. |
score | 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 | string | 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 | datetime string | The date and time of the request. ISO 8601, "2023-04-28T09:35:49.159Z" | Can be used to identify when the snapshot of this data occured. |
expiration_timestamp | datetime string | 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.ISO 8601, "2023-04-28T09:35:49.159Z" | 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 | 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. |
stamp_scores | struct | Contains key:value pairs with Stamp names as keys and their weights for the scoring algoithm as values. This struct was introduced on December 29th, 2023, and is not available via the historical score endpoint before this point. | Can be used to understand how the score was calculated. |
The Stamp object
| Value | Type | Description | How to use |
|---|---|---|---|
credential | struct | 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 | struct | Metadata is a struct 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 struct 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 structure for a given credential type. This is usually going to have the value VerifiableCredential. |
proof | struct | A struct 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 | struct | 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 structs for each individual Stamp. Each Stamp has name, description and hash fields | Included in Stamp metadata. Used to identify specific instances of individual Stamps |