Credential Schemas

Schemas are useful when enforcing a specific structure on a collection of data like a Verifiable Credential. Data Verification schemas, for example, are used to verify that the structure and contents of a Verifiable Credential conform to a published schema. On the other hand, Data Encoding schemas are used to map the contents of a Verifiable Credential to an alternative representation format, such as a binary format used in a zero-knowledge proof.

Endpoints

POST /schemas GET /schemas GET /schemas/{schemaId}\

Create Schema

Schemas are used to describe the structure of credentials, specifically the credential subject. It helps the issuer, holder, and verifier to unambiguously determine the claims contained within the credential. To create a schema, you need to define the object body using JSON schema.

Parameters

NameInTypeRequiredDescription

body

body

object

true

JSON-schema.

POST /schemas REQUEST

curl --location --request POST https://api.dock.io/schemas \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
 "$schema": "http://json-schema.org/draft-07/schema#",
 "description": "Dock Schema Example",
 "type": "object",
 "properties": {
  "id": {
    "type": "string"
 },
 "emailAddress": {
  "type": "string",
  "format": "email"
 },
 "alumniOf": {
  "type": "string"
 }
 },
 "required": [
  "emailAddress",
  "alumniOf"
 ],
 "additionalProperties": false,
 "author": "{{did}}"
}'

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Dock Schema Example",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "emailAddress": {
      "type": "string",
      "format": "email"
    },
    "alumniOf": {
      "type": "string"
    }
  },
  "required": [
    "emailAddress",
    "alumniOf"
  ],
  "additionalProperties": false,
  "author": "{{did}}"
}

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will try to create schema.

400

The request was unsuccessful, because of invalid params, e.g., size not supported or not JSON.

402

Transaction limit reached or upgrade required to proceed

200 Response

{
  "id": "1082",
  "data": {
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "description": "Dock Schema Example 3",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "emailAddress": {
          "type": "string",
          "format": "email"
        },
        "alumniOf": {
          "type": "string"
        }
      },
      "required": [
        "emailAddress",
        "alumniOf"
      ],
      "additionalProperties": false
    },
    "author": "did:dock:5FBZNTZ4eg2EBuvEcYdkEtAhCXhCEA8zmPzYTwexM3g13fkF",
    "signature": {
      "Secp256k1": "..."
    },
    "id": "https://schema.dock.io/TestSchema-V1-1695817897561.json",
    "uri": "https://schema.dock.io/TestSchema-V1-1695817897561.json"
  }
}

List Schemas

Return a list of all schemas created by the authenticated user.

Parameters

NameInTypeRequiredDescription

offset

query

integer

false

How many items to offset by for pagination

limit

query

integer

false

How many items to return at one time (max 64)

GET /schemas REQUEST

curl --location --request GET https://api.dock.io/schemas \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

Responses

StatusMeaningDescriptionSchema

200

The request was successful and will return all schemas created by the user.

Inline

402

Transaction limit reached or upgrade required to proceed

200 Response

[
  {
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "description": "Dock Schema Example",
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "emailAddress": {
          "type": "string",
          "format": "email"
        },
        "alumniOf": {
          "type": "string"
        }
      },
      "required": [
        "emailAddress",
        "alumniOf"
      ],
      "additionalProperties": false
    },
    "author": "did:dock:5HcbppP8LjoJFYRV7PTLEyPy3ZUK9JCkzC4PQHuVF34gRhe6",
    "id": "https://schema.dock.io/TestSchema-V1-1695817897561.json",
    "uri": "https://schema.dock.io/TestSchema-V1-1695817897561.json"
  }
]

Get Schema

Reading a Schema from the Dock chain can easily be achieved by using the get method which will return the JSON schema to a specific schema ID. The schemaIdneeds to be URL encoded (e.g. /schemas/https%3A%2F%2Fschema.dock.io%2FTestSchema-V1-1695817897561.json)

Parameters

NameInTypeRequiredDescription

schemaId

path

String

true

A URL encoded schema id.

GET /schemas/{schemaId} REQUEST

curl --location --request GET https://api.dock.io/schemas/{schemaId} \
  --header 'DOCK-API-TOKEN: API_KEY' \
  --data-raw ''

Responses

StatusMeaningDescriptionSchema

200

The request was successful and returns the requested Schema.

Inline

404

The request was unsuccessful, because the schema was not found.

402

Transaction limit reached or upgrade required to proceed

200 Response

{
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "Dock Schema Example",
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "emailAddress": {
        "type": "string",
        "format": "email"
      },
      "alumniOf": {
        "type": "string"
      }
    },
    "required": [
      "emailAddress",
      "alumniOf"
    ],
    "additionalProperties": false
  },
  "author": "did:dock:5HcbppP8LjoJFYRV7PTLEyPy3ZUK9JCkzC4PQHuVF34gRhe6",
  "id": "https://schema.dock.io/TestSchema-V1-1695817897561.json",
  "uri": "https://schema.dock.io/TestSchema-V1-1695817897561.json"
}

Last updated