Skip to content

Aries RFC 0020: Message Types

Summary

Define structure of message type strings used in agent to agent communication, describe their resolution to documentation URIs, and offer guidelines for protocol specifications.

Motivation

A clear convention to follow for agent developers is necessary for interoperability and continued progress as a community.

Tutorial

A "Message Type" is a required attribute of all communications sent between parties. The message type instructs the receiving agent how to interpret the content and what content to expect as part of a given message.

Types are specified within a message using the @type attribute:

{
    "@type": "<message type string>",
    // other attributes
}

Message types are URIs that may resolve to developer documentation for the message type, as described in Protocol URIs. We recommend that message type URIs be HTTP URLs.

Aries Core Message Namespace

https://didcomm.org/ is used to namespace protocols defined by the community as "core protocols" or protocols that agents should minimally support.

The didcomm.org DNS entry is currently controlled by the Decentralized Identity Foundation (DIF) based on their role in standardizing the DIDComm Messaging specification.

Protocols

Protocols provide a logical grouping for message types. These protocols, along with each type belonging to that protocol, are to be defined in future RFCs or through means appropriate to subprojects.

Protocol Versioning

Version numbering should essentially follow Semantic Versioning 2.0.0, excluding patch version number. To summarize, a change in the major protocol version number indicates a breaking change while the minor protocol version number indicates non-breaking additions.

Message Type Design Guidelines

These guidelines are guidelines on purpose. There will be situations where a good design will have to choose between conflicting points, or ignore all of them. The goal should always be clear and good design.

Respect Reserved Attribute Names

Reserved attributes are prefixed with an @ sign, such as @type. Don't use this prefix for an attribute, even if use of that specific attribute is undefined.

Avoid ambiguous attribute names

Data, id, and package, are often terrible names. Adjust the name to enhance meaning. For example, use message_id instead of id.

Avoid names with special characters

Technically, attribute names can be any valid json key (except prefixed with @, as mentioned above). Practically, you should avoid using special characters, including those that need to be escaped. Underscores and dashes [_,-] are totally acceptable, but you should avoid quotation marks, punctuation, and other symbols.

Use attributes consistently within a protocol

Be consistent with attribute names between the different types within a protocol. Only use the same attribute name for the same data. If the attribute values are similar, but not exactly the same, adjust the name to indicate the difference.

Nest Attributes only when useful

Attributes do not need to be nested under a top level attribute, but can be to organize related attributes. Nesting all message attributes under one top level attribute is usually not a good idea.

Design Examples

Example 1

{
    "@type": "did:example:00000;spec/pizzaplace/1.0/pizzaorder",
    "content": {
        "id": 15,
        "name": "combo",
        "prepaid?": true,
        "ingredients": ["pepperoni", "bell peppers", "anchovies"]
    }
}

Suggestions: Ambiguous names, unnecessary nesting, symbols in names.

Example 1 Fixed

{
    "@type": "did:example:00000;spec/pizzaplace/1.0/pizzaorder",
    "table_id": 15,
    "pizza_name": "combo",
    "prepaid": true,
    "ingredients": ["pepperoni", "bell peppers", "anchovies"]
}

Reference

Implementations

The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.

Name / Link Implementation Notes
Indy Cloud Agent - Python Reference agent implementation contributed by Sovrin Foundation and Community
Aries Framework - .NET .NET framework for building agents of all types
Streetcred.id Commercial mobile and web app built using Aries Framework - .NET
Aries Cloud Agent - Python Contributed by the government of British Columbia.
Aries Static Agent - Python Useful for cron jobs and other simple, automated use cases.
Aries Framework - Go For building agents, hubs and other DIDComm ../../features in GoLang.
Connect.Me Free mobile app from Evernym. Installed via app store on iOS and Android.
Verity Commercially licensed enterprise agent, SaaS or on-prem.