📁 Select a Credential Schema

How to use existing credential schemas with Disco.

What is a Schema?

A schema is central to Verifiable Credentials as it defines the structure and content. Specifically, schemas are representations of a particular type of credential. See more details on the credential data model here#verifiable-credentials.

Credential schemas generally have these components:

$id - the URL where the schema is located

description - a long description of the credential type that this schema was defined for

credentialSubject - this section is unique to the credential and holds the fields relevant for creating a particular credential type, see detailed examples below

expirationDate - the expiration date of the credential, if applicable

issuanceDate the date and time the credential was issued

title - the short description of the credential type

Benefit

A schema enables you to have a consistent structure that can be easily verified by a third party (ie. data verification)

CredentialSubject

Schemas per W3C Verifiable Credential spec includes a vast amount of metadata. With that in mind we will be focusing on pieces relevant to most developers - credentialSubject.

The credentialSubject is the entity like person or organization which the credential makes claims about such as their name, age, or contributions.

Selecting a Schema

We have 45+ Schemas available in our GitHub Repo

Using Membership Schema to issue Credential via our API

Always use Schema's versioned files ../SchemaName/x-x-x.json, for example.

I'm going to use the Membership Schema, found in our Repo, as a Usage example

Curl

Organization field Required

curl --location 'https://api.disco.xyz/v1/credential' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Authorization: Bearer <your Disco API key>' \
--data '{
    "issuer": "did:3:123abcexample",
    "schemaUrl": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
    "recipientDID": "did:3:456defexample",
    "subjectData": {
        "memberId": "123XYZ",
        "membershipDescription": "Demo membership to showcase Disco API",
        "membershipLevel": "Permanent",
        "membershipType": "Developer",
        "": "Disco.xyz"
    },
    "expirationDate": ""
}'

Javascript

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Accept", "*/*");
myHeaders.append("Authorization", "Bearer <your Disco API key>");

var raw = JSON.stringify({
  "issuer": "did:3:123abcexample",
  "schemaUrl": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
  "recipientDID": "did:3:456defexample",
  "subjectData": {
    "memberId": "123XYZ",
    "membershipDescription": "Demo membership to showcase Disco API",
    "membershipLevel": "Permanent",
    "membershipType": "Developer",
    "organization": "Disco.xyz"
  },
  "expirationDate": ""
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.disco.xyz/v1/credential", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Schema Example

{
  "$id": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/MembershipCredential/1-0-0.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "General Membership attests that the subject is a member in good standing of the issuing organization or group.",
  "properties": {
    "@context": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array"
        },
        {
          "type": "object"
        }
      ]
    },
    "credentialSchema": {
      "properties": {
        "id": {
          "format": "uri",
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "type": "object"
    },
    "credentialSubject": {
      "properties": {
        "expiration": {
          "format": "date",
          "title": "Expiration",
          "type": "string"
        },
        "id": {
          "format": "uri",
          "title": "Member DID",
          "type": "string"
        },
        "memberId": {
          "title": "Member ID",
          "type": "string"
        },
        "membershipDescription": {
          "title": "Membership Description",
          "type": "string"
        },
        "membershipLevel": {
          "title": "Membership Level",
          "type": "string"
        },
        "membershipType": {
          "title": "Membership Type",
          "type": "string"
        },
        "organization": {
          "title": "Organization Name",
          "type": "string"
        }
      },
      "required": [
        "id",
        "organization"
      ],
      "type": "object"
    },
    "expirationDate": {
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "format": "uri",
      "type": "string"
    },
    "issuanceDate": {
      "format": "date-time",
      "type": "string"
    },
    "issuer": {
      "anyOf": [
        {
          "format": "uri",
          "type": "string"
        },
        {
          "properties": {
            "id": {
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        }
      ]
    },
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ]
    }
  },
  "required": [
    "@context",
    "type",
    "issuer",
    "issuanceDate",
    "credentialSubject"
  ],
  "title": "Membership Credential",
  "type": "object"
}

Example Description

{ 
  ...
    "credentialSubject": { // The Verifiable Credential payload object. This is where all fields pertaining to the specific credential type resides. 
      "properties": { 
        "expiration": { // Standard to the W3C VC protocol - an optional expiration date for the Credential.
          "format": "date",
          "title": "Expiration",
          "type": "string"
        },
        "id": ... , // Standard to the W3C VC protocol - a unique credential identifier assigned by the system. As a developer you do NOT include this in API calls for creating your Credential.
        "memberId": { // Optional and unique to this particular schema - use whatever membership ID you want to refer to - or may be left out if not used.
          "title": "Member ID",
          "type": "string"
        },
        "membershipDescription": { // Optional and unique to this particular schema - describe what the membership is for to the recipient and verifiers - or may be left out if not used.
          "title": "Membership Description",
          "type": "string"
        },
        "membershipLevel": { // Optional and unique to this particular schema - if your membership is hierarchical you can use this to indicate the level - or may be left out if not used.
          "title": "Membership Level",
          "type": "string"
        },
        "membershipType": { // Optional and unique to this particular schema - can be used to describe the membership type issued- or may be left out if not used.
          "title": "Membership Type",
          "type": "string"
        },
        "organization": { // Required and unique to this particular schema - the name of the organization for which this membership is issued for.
          "title": "Organization Name",
          "type": "string"
        }
      },
      "required": [ // Required fields Unique to this particular schema
        "id", // ALWAYS system generated
        "organization" // Provided by you, the developer
      ],
      "type": "object"
    }, 
  ... 
  }

As mentioned above, much of this is boilerplate per W3C specification, what is unique to Membership Credential (and any other schemas for that matter) is in the CredentialSubject object. Note that the last object, named required in the CredentialSubject list the fields that must be provided for this particular schema.

Schema Examples

Proof of Mint: for users who are the first to mint an NFT

The payload object to use in API calls for Proof of Mint Credential - the rest is boilerplate.

"credentialSubject": {
      "properties": {
        "chain": { // Optional Proof of Mint field for credential creation
          "title": "Chain",
          "type": "string"
        },
        "contractAddress": { // Optional Proof of Mint field for credential creation
          "title": "Contract address",
          "type": "string"
        },
        "dateOfMint": { // Optional Proof of Mint field for credential creation
          "format": "date",
          "title": "Date of Mint",
          "type": "string"
        },
        "id": { // DO NOT INCLUDE - a unique credential identifier assigned by the system. As a developer you do NOT include this in API calls for creating your credential.
          "format": "uri",
          "title": "Recipient DID",
          "type": "string"
        },
        "tokenStandard": { // Optional Proof of Mint field for credential creation
          "title": "Token Standard",
          "type": "string"
        }
      },
      "required": [ // Note that no Proof of Mint specific fields are required 
        "id"
      ],
      "type": "object"
    },

Full Proof of Mint Schema

{
  "$id": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/ProofOfMintCredential/1-0-0.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Proof of Mint proves/recognizes the holder is an original minter of this NFT drop.",
  "properties": {
    "@context": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array"
        },
        {
          "type": "object"
        }
      ]
    },
    "credentialSchema": {
      "properties": {
        "id": {
          "format": "uri",
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "type": "object"
    },
    "credentialSubject": {
      "properties": {
        "chain": {
          "title": "Chain",
          "type": "string"
        },
        "contractAddress": {
          "title": "Contract address",
          "type": "string"
        },
        "dateOfMint": {
          "format": "date",
          "title": "Date of Mint",
          "type": "string"
        },
        "id": {
          "format": "uri",
          "title": "Recipient DID",
          "type": "string"
        },
        "tokenStandard": {
          "title": "Token Standard",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    },
    "expirationDate": {
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "format": "uri",
      "type": "string"
    },
    "issuanceDate": {
      "format": "date-time",
      "type": "string"
    },
    "issuer": {
      "anyOf": [
        {
          "format": "uri",
          "type": "string"
        },
        {
          "properties": {
            "id": {
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        }
      ]
    },
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ]
    }
  },
  "required": [
    "@context",
    "type",
    "issuer",
    "issuanceDate",
    "credentialSubject"
  ],
  "title": "Proof of Mint Credential",
  "type": "object"
}

Beta User Credential: for users who are or have used your Beta products

The payload object to use in API calls for Beta User Credentials - the rest is boilerplate.

"credentialSubject": {
      "properties": {
        "id": {{ // DO NOT INCLUDE - a unique credential identifier assigned by the system. As a developer you do NOT include this in API calls for creating your Credential.
          "title": "Recipient DID",
          "type": "string"
        },
        "name": { // Optional Beta User field for Credential creation
          "title": "Name",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    },

Full Beta User Schema

{
  "$id": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/BetaUserCredential/1-0-0.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "This credential is for our early beta users or testers who are testing our product before official launch. Thank you for your support and coninued patience!",
  "properties": {
    "@context": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array"
        },
        {
          "type": "object"
        }
      ]
    },
    "credentialSchema": {
      "properties": {
        "id": {
          "format": "uri",
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "type": "object"
    },
    "credentialSubject": {
      "properties": {
        "id": {
          "title": "Recipient DID",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        }
      },
      "required": [
        "id"
      ],
      "type": "object"
    },
    "expirationDate": {
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "format": "uri",
      "type": "string"
    },
    "issuanceDate": {
      "format": "date-time",
      "type": "string"
    },
    "issuer": {
      "anyOf": [
        {
          "format": "uri",
          "type": "string"
        },
        {
          "properties": {
            "id": {
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        }
      ]
    },
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ]
    }
  },
  "required": [
    "@context",
    "type",
    "issuer",
    "issuanceDate",
    "credentialSubject"
  ],
  "title": "Beta User Credential",
  "type": "object"
}

Contribution: For Users Who Contributed To Your Community or Project

The payload object to use in API calls for Contribution Credential - the rest is boilerplate.

"credentialSubject": {
      "properties": {
        "category": { // Required enum for Contribution Credential creation
          "enum": [
            "Content Creation",
            "Improved process",
            "Pull Request",
            "Reviewed code",
            "Research",
            "Discourse",
            "Financial Contribution",
            "Other"
          ],
          "title": "Category",
          "type": "string"
        },
        "description": { // Required field for Contribution Credential creation
          "title": "Description",
          "type": "string"
        },
        "id": { // DO NOT INCLUDE - a unique credential identifier assigned by the system. As a developer you do NOT include this in API calls for creating your Credential.
          "title": "Recipient DID",
          "type": "string"
        },
        "name": { // Required field for Contribution Credential creation
          "title": "Organization Name",
          "type": "string"
        },
        "url": { // Optional field for Contribution Credential creation
          "title": "Contribution URL",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "category",
        "description"
      ],
      "type": "object"
    },

Full Contribution Schema

{
  "$id": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/ContributionCredential/1-0-0.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Enables you to capture and contextualize contributions made by a person",
  "properties": {
    "@context": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array"
        },
        {
          "type": "object"
        }
      ]
    },
    "credentialSchema": {
      "properties": {
        "id": {
          "format": "uri",
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "type": "object"
    },
    "credentialSubject": {
      "properties": {
        "category": {
          "enum": [
            "Content Creation",
            "Improved process",
            "Pull Request",
            "Reviewed code",
            "Research",
            "Discourse",
            "Financial Contribution",
            "Other"
          ],
          "title": "Category",
          "type": "string"
        },
        "description": {
          "title": "Description",
          "type": "string"
        },
        "id": {
          "title": "Recipient DID",
          "type": "string"
        },
        "name": {
          "title": "Organization Name",
          "type": "string"
        },
        "url": {
          "title": "Contribution URL",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "category",
        "description"
      ],
      "type": "object"
    },
    "expirationDate": {
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "format": "uri",
      "type": "string"
    },
    "issuanceDate": {
      "format": "date-time",
      "type": "string"
    },
    "issuer": {
      "anyOf": [
        {
          "format": "uri",
          "type": "string"
        },
        {
          "properties": {
            "id": {
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        }
      ]
    },
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ]
    }
  },
  "required": [
    "@context",
    "type",
    "issuer",
    "issuanceDate",
    "credentialSubject"
  ],
  "title": "Contribution Credential",
  "type": "object"
}

Snaps: Send Snaps To Celebrate Someone Doing Something Positive and Helpful

The payload object to use in API calls for Snaps Credential - the rest is boilerplate.

"credentialSubject": {
      "properties": {
        "id": { // DO NOT INCLUDE - a unique credential identifier assigned by the system. As a developer you do NOT include this in API calls for creating your Credential.
          "title": "Recipient DID",
          "type": "string"
        },
        "snapsType": { // Required enum for Snaps Credential creation
          "enum": [
            "Immaculate Vibes: Thank you for your awesome energy",
            "Problem Solver: Thank you for working with me to solve a tough challenge together",
            "Miracle Worker: Thank you for unexpectedly and proactively doing something awesome that impacted my day for the better!"
          ],
          "title": "Snaps Type",
          "type": "string"
        }
      },
      "required": [
        "id",
        "snapsType"
      ],
      "type": "object"
    },

Full Snaps Schema

{
  "$id": "https://raw.githubusercontent.com/discoxyz/disco-schemas/main/json/SnapsCredential/1-0-0.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Send snaps to celebrate a friend or colleague doing something positive and helpful.",
  "properties": {
    "@context": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array"
        },
        {
          "type": "object"
        }
      ]
    },
    "credentialSchema": {
      "properties": {
        "id": {
          "format": "uri",
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "type": "object"
    },
    "credentialSubject": {
      "properties": {
        "id": {
          "title": "Recipient DID",
          "type": "string"
        },
        "snapsType": {
          "enum": [
            "Immaculate Vibes: Thank you for your awesome energy",
            "Problem Solver: Thank you for working with me to solve a tough challenge together",
            "Miracle Worker: Thank you for unexpectedly and proactively doing something awesome that impacted my day for the better!"
          ],
          "title": "Snaps Type",
          "type": "string"
        }
      },
      "required": [
        "id",
        "snapsType"
      ],
      "type": "object"
    },
    "expirationDate": {
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "format": "uri",
      "type": "string"
    },
    "issuanceDate": {
      "format": "date-time",
      "type": "string"
    },
    "issuer": {
      "anyOf": [
        {
          "format": "uri",
          "type": "string"
        },
        {
          "properties": {
            "id": {
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        }
      ]
    },
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      ]
    }
  },
  "required": [
    "@context",
    "type",
    "issuer",
    "issuanceDate",
    "credentialSubject"
  ],
  "title": "Snaps Credential",
  "type": "object"
}