---
description: >-
  DiME, the open and trust-based data format building secure Application-based
  Public-Key Infrastructures (APKIs) in a breeze.
---

# Claims

DiME uses claims to communicate information to receiving parties. These claims are like other data formats as [JSON Web Tokens (JWT)](https://jwt.io/), although availability and usages may differ.

The first component after the header in a DiME item contains a Base64 encoded JSON string containing claims. Envelopes are an exception to this, where the use of claims is optional.

There are several standardized claims in DiME, all with a specific purpose. Most claims may be used for all types of DiME items, however, there are few exceptions to this.

Even if the data format allows for the use of proprietary or application-specific claims, there is yet no standardized naming convention. At the time being non-standard claims are not officially supported, although this may change over time.

Each standardized claim uses a three-letter abbreviation, referred to as the claim key. The claim key is used in the JSON string as the field name when adding claims. The following table outlines all standard claims, their usage, and any exceptions:

<table><thead><tr><th>Claim</th><th width="80">Key</th><th width="329">Description</th><th>Applies to</th></tr></thead><tbody><tr><td><a href="#ambit">Ambit</a></td><td>amb</td><td>Describes the region, location or boundaries where the item is intended or valid</td><td>All</td></tr><tr><td><a href="#audience-id">Audience ID</a></td><td>aud</td><td>The identifier of the indented receiver, or audience, of the item</td><td>All</td></tr><tr><td><a href="#capability">Capability</a></td><td>cap</td><td>Describes the capabilities, or usages/constrains, of an item</td><td>Identity, Identity Issuing Request, Key</td></tr><tr><td><a href="#common-name">Common Name</a></td><td>cmn</td><td>A common name, or alias, for the item, may be used to simplify manual identification of items</td><td>All</td></tr><tr><td><a href="#context">Context</a></td><td>ctx</td><td>The context for in which the item is to be used or valid</td><td>All</td></tr><tr><td><a href="#expires-at">Expires at</a></td><td>exp</td><td>The date and time when the item should be considered invalid and should no longer be used</td><td>All</td></tr><tr><td><a href="#issued-at">Issued at</a></td><td>iat</td><td>The date and time when the item should be considered valid and only used after (until expires at, if specified)</td><td>All</td></tr><tr><td><a href="#issuer-id">Issuer ID</a></td><td>iss</td><td>The identifier of the issuer of the item</td><td>All</td></tr><tr><td>Issuer URL</td><td>isu</td><td>A URL or other form of resource locator where the issuer identity or public key may be fetched</td><td>All</td></tr><tr><td><a href="#key-id">Key ID</a></td><td>kid</td><td>The identifier of a key that is related to the item</td><td>All</td></tr><tr><td><a href="#item-links">Item links</a></td><td>lnk</td><td>Item links to other items that has been securely linked to the item</td><td>All</td></tr><tr><td><a href="#mime-type">MIME type</a></td><td>mim</td><td>The MIME type of any payload that is attached to the item</td><td>Data, Message</td></tr><tr><td><a href="#methods">Methods</a></td><td>mtd</td><td>Intended for use with external systems and data formats. Will be specified further in the future</td><td>All</td></tr><tr><td><a href="#public-key">Public key</a></td><td>pub</td><td>A public key in raw format</td><td>Identity, Identity Issuing Request, Key, Message</td></tr><tr><td><a href="#principle-information">Principle information</a></td><td>pri</td><td>A key-value object with further information related to the principle related to the item</td><td>Identity, Identity Issuing Request</td></tr><tr><td><a href="#secret-key">Secret key</a></td><td>key</td><td>A secret key in raw format, may be a private key or a shared key</td><td>Key</td></tr><tr><td><a href="#subject-id">Subject ID</a></td><td>sub</td><td>The identifier of the subject related to the item</td><td>All</td></tr><tr><td><a href="#system-name">System name</a></td><td>sys</td><td>The name of the system where the item originated from or belongs to</td><td>All</td></tr><tr><td><a href="#unique-id">Unique ID</a></td><td>uid</td><td>A unique identifier for the item</td><td>All</td></tr></tbody></table>

### Ambit

<table><thead><tr><th width="142">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>amb</td><td>String array (UTF8)</td></tr></tbody></table>

The ambit of an item describes the reach or within what region it may be used. A valid item may be refused if it is being used outside its ambit. The defined ambit and its enforcement is system-specific.

```json
"amb": [ 
    "global", 
    "administration" 
]
```

If ambit is omitted, then it is assumed that the item has no restrictions on where it may be used inside the deployed infrastructure.

### Audience ID

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>aud</td><td>String (UUIDv4)</td></tr></tbody></table>

The audience ID claim specifies the identifier of the receiver, the intended audience, of the a DiME item.



```json
"aud": "34e7081b-8871-467a-a963-7f0eedb42c80"
```

If an item has no direct intended receiver (audience), then this claim may be omitted.

### Capability

<table><thead><tr><th width="142">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>cap</td><td>String array (UTF8)</td></tr></tbody></table>

Capabilities describe the allowed usage of an identity or key. For more information about possible values refer to either [Identity](items/identity) or [Key](items/key).

### &#x20;Common Name

<table><thead><tr><th width="422.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>cmn</td><td>String (UTF8)</td></tr></tbody></table>

May be used to simplify manual identification of items where Common Name refers to a particular entity name or alias.&#x20;

```json
"cmn": "Data Integrity Message Envelope"
```

The maximum length of a common name is 84 characters.

### Context

<table><thead><tr><th width="422.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>ctx</td><td>String (UTF8)</td></tr></tbody></table>

This claim is used to provide additional information about the context of the DiME item. This could be used to indicate intention of a message as “request” or “response”, or the use of a particular key.

```json
"ctx": "keep-alive"
```

The maximum length of a context is 84 characters.

### Expires at

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>exp</td><td>String (<a href="https://www.rfc-editor.org/rfc/rfc3339">RFC 3339</a>)</td></tr></tbody></table>

This claim specifies the date when an item expires. The format of the date follows the standard RFC 3339 and UTC must always be used. RFC 3339 is used for its ease of parsing and also since it is human-readable. Items with an expiration date in the past must be discarded, the same applies if the expiration date is before the issued date.

```json
"exp": "2025-11-18T18:06:02.974395Z"
```

### Issued at

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>iat</td><td>String (<a href="https://www.rfc-editor.org/rfc/rfc3339">RFC 3339</a>)</td></tr></tbody></table>

The issued at claim specifies the date when an item was created or issued. The format of the date follows the standard RFC 3339 and UTC must always be used. RFC 3339 is used for its ease of parsing and also since it is human-readable. Items that do include this claim that specifies a date in the future should be discarded, the same applies if the expires at date ("exp") is before the issued date.

### Issuer ID

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>iss</td><td>String (UUIDv4)</td></tr></tbody></table>

This is the unique subject ID of the entity that created or issued an item.&#x20;

```json
"iss": "647589bf-7f7e-4d4c-8174-e3eb366d5a91"
```

### Issuer URL

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>isu</td><td>String (UTF8)</td></tr></tbody></table>

A URL, or part of, that may be used to locate and fetch the issuer identity if needed.

```json
"isu": "https://dime.example.com?id=647589bf-7f7e-4d4c-8174-e3eb366d5a91"
"isu": "?q=647589bf-7f7e-4d4c-8174-e3eb366d5a91"
```

The maximum length of Issuer URL (isu) is 512 characters, although it is recommended to keep this short and use it to build a full URL using other known components.

### Key ID

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>kid</td><td>String (UUIDv4)</td></tr></tbody></table>

The Key ID refers to a unique identifier of a DiME key item. This claim may be used to indicate which key is needed to verify the signature of the item, or which key is needed to decrypt any attached payload.

```json
"kid": "0cef1d8f-54be-4ce0-a669-cd2897ac64e0"
```

Key ID is equal to the value of the unique ID (‘uid’) of a key item.

### Item links

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>lnk</td><td>String (UTF8)</td></tr></tbody></table>

This claim is used to store links to other DiME items in an item. For detailed information refer to [Item links](cryptography/item-links).

{% code overflow="wrap" %}
```json
"lnk": "KEY.c0eb7bed-591e-4021-970d-e881147fa48d.7df0f3f6122413e83beb5347408d909151d5f956fe973a08357ceaf1c0b83b19"
```
{% endcode %}

### Methods

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>mtd</td><td>String array (UTF8)</td></tr></tbody></table>

This claim will be further specificed in the future. The intention for it is to hold information on how to convert, or adapt a DiME item for the use in external systems using other types of data formats.

An example of this are emerging decentalized solutions for distributing and using public-key pairs.

```json
"mtd":
[
    "furture-specification:and:use"
]
```

### MIME type

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>mim</td><td>String (UTF8)</td></tr></tbody></table>

DiME items that carry arbitrary payloads may use this claim to specify the MIME type of the payload data. This must use the standard format of MIME ([Multipurpose Internet Mail Extensions](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)) types.

```json
"mim": "text/plain"
```

The MIME type claim is used by [Data](items/data) and [Message](items/message).

### Public key

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>pub</td><td>String (UTF8)</td></tr></tbody></table>

This claim holds a public key, which can be used to verify signatures or complete Diffie-Hellman key agreement for shared keys. For that actual format refer to [Key encoding](encoding/key-encoding).

```json
"pub": "STN.Lo8cQbUU9wiDY1rgDbxYDAzsm8gis7RrDFsnH3BcvbY8wpBNC"
```

The Public key claim is used by [Identity](items/identity), [Identity Issuing Request](items/identity-issuing-request), [Key](items/key) and [Message](items/message).

### Principle information

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>pri</td><td>JSON object</td></tr></tbody></table>

A simple JSON object with information associated with the subject or holder of an identity. This may be the name of the entity name and organization. Not standard fields have been specified for the DiME data format and this claim is considered to be applicaiton-specific. This may be changed in the future.

The below example should be see as an example of usage as field names and structure is up to the application.&#x20;

```json
  "pri": {
    "entity": "Example subject",
    "location": "Planet Earth",
    "organization": "DiME",
    "domain": [ "dimeformat.io" ],
    "contact": [ "info@dimeformat.io" ]
  }
```

The Principle information claim is used by [Identity](items/identity) and [Identity Issuing Request](items/identity-issuing-request).

### Secret key

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>key</td><td>String (UTF8)</td></tr></tbody></table>

The raw data of the secret key, asymmetric or symmetric. For encoding information refer to [Key encoding](encoding/key-encoding).

```json
"key": "STN.aBjkzKX2B5ZwG1nrbmNFmugZp6o3i6Fk8oVmjtfopvgTPJcPcEMottZji2ejUmMWgEDukLDyFBchTw5KBoKjFF55wCTWk"
```

This claim is used by [Key](items/key).

### Subject ID

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>sub</td><td>String (UUIDv4)</td></tr></tbody></table>

This is a unique identifier for the entity (subject) that owns, or is associated with, the DiME item. Unlike [Unique ID](#unique-id), this may be reused over time for the same subject or entity. For example, if an entity requests a re-issue of an Identity item, then the Subject ID may remain the same, whereas the Unique ID would change.

```json
"sub": "a6902184-2ba0-4ba0-ab91-ca77da7d05d3"
```

### System name

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>sys</td><td>String (UTF8)</td></tr></tbody></table>

The system claim specifies the network, application scope or system where a DiME item is deployed. It may be used to specify sub-sections within a larger infrastructure.

The usage is application-specific. However, when issuing Identity items from a Identity item the system name will carry over, unless anything else is specified.

```json
"sys": "dimeformat.io"
"sys": "beaa26e7-34b2-4fa2-bdf6-17fec0840a01"
"sys": "NETWORK_DOMAIN:SUBNETWORK_DOMAIN"
```

### Unique ID

<table><thead><tr><th width="158.2173913043478">Claim key</th><th width="260">Format</th></tr></thead><tbody><tr><td>uid</td><td>String (UUIDv4)</td></tr></tbody></table>

This is unique identifier for a DiME item. It must not be reused, not even for items of other DiME item type. A new unique id must be generated at creation, this is also required when reissuing Identity items.

```json
"uid": "c48e4b68-91ac-4c93-ba96-1c35c50761d4"
```

## JSON

DiME holds item claims in a simple JSON structure, as demonstrated previous. To enable simple cross-platform use DiME also uses JSON canonicalization to ensure a consistent order of the claims inside the JSON structure. The JSON Canonicalization Scheme (JCS) is described in [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785).

#### JSON schema

Coming soon...





