# RFC 0xxx: Linkable DIDComm Message Paths

## Summary

Describes how to hyperlink to specific elements of specific DIDComm messages.

## Motivation

It must be possible to refer to specific pieces of data in specific DIDComm messages. This allows a message later in a protocol to refer to data in a message that preceded it, which is useful for stitching together subprotocols, debugging, error handling, logging, and various other scenarios.

## Tutorial

There are numerous approaches to the general problem of referencing/querying a piece of data in a JSON document. We have chosen [JSPath](https://github.com/dfilatov/jspath#quick-example) as our solution to that part of the problem; see [Prior Art](#prior-art) for a summary of that option and a comparison to alternatives.

What we need, over and above JSPath, is a URI-oriented way to refer to an individual message, so the rest of the referencing mechanism has a JSON document to start from.

### DIDComm Message URIs

A __DIDComm message URI__ (__DMURI__) is a string that references a sent/received message, using [standard URI syntax as specified in RFC 3986](https://tools.ietf.org/html/rfc3986). It takes one of the following forms:

1. `didcomm://<thid>/<msgid>`
2. `didcomm://./<msgid>` or `didcomm://../<msgid>`
3. `didcomm:///<msgid>` (note 3 slashes)
4. `didcomm://<sender>@<thid>/<senderorder>`

Here, `<msgid>` is replaced with the value of the `@id` property of a plaintext DIDComm message; `<thid>` is replaced with the `~thread.thid` property, `<sender>` is replaced with a DID, and `<senderorder>` is replaced with a zero-based index (the Nth message emitted in the thread by that sender).

Form 1 is called __absolute form__, and is the prefered form of DMURI to use when talking about messages outside the context of an active thread (e.g., in log files)

Form 2 is called __relative form__, and is a convenient way for one message to refer to another within an ongoing interaction. It is relatively explicit and terse. It uses 1 or 2 dots to reference the current or parent thread, and then provides the message id with that thread as context. Referencing more distant parent threads is done by increasing the number of dots (3 dots, 4 dots, etc).
> [name=Sam Curren (TelegramSam)]
I'd leave off the 3+ dots in relative form. parent is easy enough because messages should reference it's parent thread. If you need to go higher than this, I think absolute form is the answer.

Form 3 is called __simple form__. It omits the thread id entirely. It is maximally short and usually clear enough. However, it is slightly less preferred than forms 1 and 2 because it is possible that some senders might not practice good message ID hygeine that guarantees global message ID uniqueness. When that happens, a message ID could get reused, making this form ambiguous. The most recent message that is known to match the message id must be assumed.

Form 4 is called __ordered form__. It is useful for referencing a message that was never received, making the message's internal `@id` property unavailable. It might be used to request a resend of a lost message that is uncovered by the gap detection mechanism in DIDComm's message threading.

Only parties who have sent or received messages can dereference DMURIs. However, the URIs should be transmittable through any number of third parties who do not understand them, without any loss of utility.

### Combining a DMURI with a JSPath

A JSPath is concatenated to a DMURI by using an intervening slash delimiter:

`didcomm:///e56085f9-4fe5-40a4-bf15-6438751b3ae8/.~timing.expires_time`

[If a JSPath uses characters from RFC 3986's __reserved characters__ list in a context where they have special meaning, they must be percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding).

## Prior Art

* [JSPath](https://github.com/dfilatov/jspath): the one we're using. Simple and relatively current, with clean syntax.
* [JSONPath](https://github.com/json-path/JsonPath): superseded by JSONQuery
* [JSONQuery](https://dojotoolkit.org/reference-guide/1.10/dojox/json/query.html): also looks a bit old
* [JSONSelect](https://github.com/lloyd/JSONSelect): old. More like CSS selectors
* [JSONiq](http://jsoniq.com/): powerful and current, but focuses more on querying; may be overkill for just referencing a subobject