Reference: PR

The PR has since diverged from the contents of this document. This document needs an update after the PR is merged.

This page documents the details of generic JSON message protocol. This protocol defines a format for sending arbitrary JSON payloads using DIDComm with message type `https://didcomm.org/json/1.0/message.` with following fields.

content~attach of type embedded JSON attachment is actually a machine readable message transported in this DIDComm message.
data-type field indicating types of data present in content~attach attachment. Unlike conventional message type based handlers, an agent can choose to register a handler for each data-type for handling corresponding content~attach attachment.
Optional ~thread field for providing the context
Optional ~timing field for to communicate about timing of messages

The major rationale behind this protocol is to introduce custom data-type and handlers without needing to standardize them through the RFC process. These custom data-type and handlers facilitates indirection (relaying, blinding etc).

Example Scenario:

Carl is requesting some data from Maria. When Maria receives a request from Carl she will look for requested data in her external application.

High level flow will look something like this

Introducing indirection using Generic JSON message (DIDComm Tunnel) using API binding

Pre-Steps:

Connection is already established between agent Carl and agent Maria.
Agent Maria listening to event for message type `https://didcomm.org/json/1.0/message.` and data type `foo`.
Post event handler logic → extract attachment from event and call external application to get response. Notify agent to trigger outbound DIDComm message to Carl after getting response.
Agent Carl listening to event for message type `https://didcomm.org/json/1.0/message.` and data type `foo-response`
Post event handler logic → extract attachment from event and send response to requestor using extracted attachment.

Introducing indirection using Generic JSON message (DIDComm Tunnel) using REST binding

Pre-Steps:

Connection is already established between agent Carl and agent Maria.
Agent Maria registered handler for message type `https://didcomm.org/json/1.0/message.` and data type `foo`.
Handler logic → extract attachment from handler event and call external application to get response. Notify agent to trigger outbound DIDComm message to Carl after getting response.
Agent Carl registered handler for message type `https://didcomm.org/json/1.0/message.` and data type `foo-response`
Handler logic → extract attachment from handler event and use extracted attachment to send HTTP response to requestor and close the connection.

High Level Design

Here are the key components needed for implementing generic JSON message / DIDComm tunnel.

Introducing generic message service for new message type

This service will handle inbound messages of type `https://didcomm.org/json/1.0/message.` Incoming messages will contain content~attach, data-type, ~thread and ~timing fields.
Event handlers for specific data-type should be able to get registered with this service. Duplicate event handlers for same data-type can be registered.
It will be service implementation's responsibility to find data-type from incoming messages and calling registered handlers by passing content of messages like attachment, timing and thread info.
Service should use generic message only to find respective handlers, it shouldn't manipulate/persist any of the message contents.
Service should also implement send message feature which can be a new message or reply to existing message (updated ~thread, ~timing decorators in outbound message)
Service should also provide way to unregister already registered handlers.

Event Handlers based on 'message-type/data-type'

Event handler should be able to specify data type it is interested in, under given message type `https://didcomm.org/json/1.0/message.` and it should be notified only when generic message arrives for the specified data-type.
It will be event handler's responsibility to validate attachment for given data-type.
It is event handler's responsibility to decide next course of action for message received (if required, then by notifying service to execute an action. For example: sending outbound message to another agent).

Client API

This API will be used by go binding and REST binding implementations.

Add client API similar to any other client for existing protocols which will provide APIs for operations like
- register handlers
- send generic message to another agent (new and reply)

Go/SDK binding

Should be able to send messages, reply to messages and register data type based handlers through client API.
Note: For HTTP DIDComm tunnel, it is up to client's implementation logic. (may be by using HTTP proxies to send messages through aries client API.)

REST binding (HTTP DIDComm Tunnel)

Introduce a new REST endpoint which can be used to send/reply generic JSON message using client API.

Question: Should be a public endpoint unlike other controller API endpoints ?

Reply message with context

All generic DIDComm message are simplex. But when communication between two agents involves exchange of multiple messages, to provide context we should have to make use ~thread and ~timing decorators.

Design: TBD

Browser not supported