Skip to main content

CTypes

CTypes are data types specific to KILT that define the structure of a claim (i.e., its data model). CTypes are based on JSON Schema, a standard used to annotate and validate JSON documents. The schema defines which properties exist and what their type should be, e.g., a string, a number, an object, etc.

JSON Schema​

KILT uses JSON Schema (currently draft-07) to validate and annotate data in a strict format. This data format is used to define CType models. The following are all required properties of the schema, with no additional properties allowed:

  • Identifier: $id in the format kilt:ctype:0x{cTypeHash}.
  • KILT specific JSON-Schema: Accessible at http://kilt-protocol.org/draft-01/ctype#.
  • Title: Defines a user-friendly name for the CType that makes it easier for users to contextualize.
  • Properties: Set of fields (e.g., name, birthdate) that the CType can contain, and hence that the Claimer can have attested.

Properties​

When creating a new CType schema, the following properties are required:

  • One of the following fields: type or $ref
  • A type of string, integer, number or boolean to define the attribute
  • Nested JSON schemas can be referenced by a uri using $ref (giving the advantage of being able to reference previously-created CTypes)
  • The format field is optionally:
CType schema example
{
  "$schema": "http://kilt-protocol.org/draft-01/ctype#",
  "title": "Drivers License by did:kilt:4t9FPVbcN42UMxt3Z2Y4Wx38qPL8bLduAB11gLZSwn5hVEfH",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "id": {
      "type": "string"
    }
  },
  "type": "object"
}

The CType schema is afterwards hashed to generate its own identifier, and it becomes the full CType object:

Full CType example
{
  "$id": "kilt:ctype:0x4f1d68ac46daf4613181b33b16faaf10cf94879dc2246d7485dc2ccbb843641d",
  "$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/",
  "additionalProperties": false,
  "properties": {
    "age": {
      "type": "integer"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "title": "Drivers License by did:kilt:4t9FPVbcN42UMxt3Z2Y4Wx38qPL8bLduAB11gLZSwn5hVEfH",
  "type": "object"
}

CType Metadata​

CType Metadata can be linked to a given CType to provide title and descriptions in different languages for the whole CType and its properties.

Hashing​

The hash of the CType is used to identify and anchor it to the KILT blockchain.

Constructing the hash for the $id​

KILT uses the hashing algorithm blake2b256 to compute the hash of CTypes. Before hashing, the CType object is sorted by a canonicalization algorithm to ensure that semantically equivalent CTypes with different order of their properties result in the same final hash.

The hash is computed from the following fields of the CType schema:

  • $schema
  • properties
    • key
    • $ref
    • type
    • format
  • title
  • type

A typical CType ID would look like this: kilt:ctype:0xda3861a45e0197f3ca145c2c209f9126e5053fas503e459af4255cf8011d5101.

Storing and Querying CTypes​

As of the KILT runtime 1.9.0, CTypes can be queried directly from any KILT archive node!

After creating a CType, its full content is included only in the blockchain block history, while its hash and creation block number is anchored to the blockchain state.

Querying the full content of a CType then becomes trivial, since the CType hash can be used to look up its creation block number, and then that information can be used to ask any KILT archive node for the extrinsic information about the CType creation. The information includes the whole CType, which is now available for the user to, e.g., verify credentials against it.

For adding a CType, a constant fee of 0.001 KILT is required.

For a detailed developer-oriented guide to KILT CTypes, see our CType Cookbook section.