VCON for MIMI Messages

Syntax A MIMI conversation (or portion thereof) is represented in VCON with a mandatory list of parties and dialogs, a new top-level room object, and optionally attachment objects.

Room information This document adds a mandatory, top-level room object. It contains metadata known about the room at the start of the VCON period.

id is the MIMI room ID URL. It is mandatory.
name is the textual name of the room. It is optional.
avatar is a URL referencing the room image. It is optional.
subject is the room subject. It is optional.
mood is the room mood. It is optional
description is an array of room_description objects. It is optional. Each object can contain:
- a type- a media type or an empty string. It is optional. It's default value is text/plain;charset=UTF-8.
- a lang - a Language-tag as defined by . It is optional.
- a content - if the type begins with "text" or is empty, the content the is UTF-8 text description of the room. Otherwise it is the base64url encoding of whatever type is described. The content field is mandatory in a room_description object.

Parties The parties array MUST contain all the participants who were in the conversation at any point in time during the period represented by the VCON. The first party in the array is the MIMI room URI. This document adds a new party_object_type: im_uri. It is mandatory. The name field is optional. The role indicates the MIMI role and is optional. The document also adds a thumbprint party_object_type, which is the JWK thumbprint of the public key of the party. If there are multiple parties (clients) with the same im_uri then the thumbprint is required, otherwise it is optional.

The dialog object (text type) The following section refers to changes and additions to the dialog object when the type field is "text".

Semantics of the existing fields for text The dialog object consists of an array of instant messages of type "text". The start time is set to the hub received timestamp when available. The duration is zero. The originator is set to the parties index of the sender of the message. The first MIMI message represented in a MIMI VCON should contain the complete list of parties who were participants in the room at that time. For subsequent messages, a parties array consisting of index zero, indicates the recipients of the message are the active participants of the room. Changes to the roster can be tracked if party_history is present for those changes (see ).

Extensions to the dialog object for text The parties array consist of the party indexes of those who were active participants when the message was sent.

message_id is the base64url encoding of the MIMI content message ID. It is mandatory.
salt is the base64url encoding of the MIMI content salt. It is mandatory.
replaces is the base64url encoding of the MIMI content message_id of the message this message replaces. It is optional if empty.
topic_id is the base64url encoding of the MIMI topic_id. It is optional if empty.
expires is optional if empty in MIMI. It contains null or a map with the following items:
- relative is a boolean that is true if the time is expressed relative to the recipient read time, and false if it is expressed as an absolute date/time. It is mandatory when expires is present.
- relative_time is an integer number of seconds. If relative is true, once the message has been read, the client is expected to delete the message after relative_time seconds. It is mandatory if relative is true.
- absolute_time is the expiration date/time of the message expressed as a VCON (text) date_type. It is mandatory if relative is false and optional otherwise.
in_reply_to is the base64url encoding of the MIMI content message_id of the message to which this message is replying (or reacting). It is optional if empty.
mimi_extensions is a base64 encoding of the CBOR MIMI content extensions map or null. It is optional if not present in the MIMI content.
franking_tag is a base64url encoding of the MIMI franking_tag, or null. It is optional if not present.
frank is a base64url encoding of the MIMI protocol Frank TLS struct, or null. It is optional if not present.

VCON typically expresses message content using the body, encoding, and mediatype fields. In order to preserve this convention we use these fields directly for a MIMI SinglePart structure, but use new MultiPart and ExternalPart objects for those corresponding MIMI structures. For a SinglePart these two fields with the same semantics as their MIMI content counterparts could be present.

disposition - optional if set to the default value ("render")
language - optional if absent

If there is only a single part its part_index is 0, and in this case it is optional.

MultiPart objects A MultiPart object is designed to carry multiple items, as with the MultiPart structure in MIMI content or the top level multipart media types. It contains the following fields.

part_semantics is one of "chooseOne", "singleUnit", or "processAll". It is mandatory.
parts is an array of Parts. It is mandatory in a MultiPart object.

Part objects The following fields can be in a Part object. They have the same meaning as their MIMI content counterparts.

disposition optional if set to the default value ("render")
language - optional if absent
part_index is an unsigned integer. It is mandatory in a Part object.
cardinality is one of "nullpart", "single", "external", or "multi". mandatory.

If cardinality is "single" or "external", then body, encoding, and mediatype fields are included directly in the Part object.

ExternalPart objects The ExternalPart object can contain the following fields with similar meanings to those in MIMI content, with exceptions noted below.

mediatype is the value of the contentType in MIMI. It is mandatory if present in the MIMI message and recommended otherwise.
url is the URL of the content as a text string. It is mandatory
expires is a date_type (text) date. It is optional if not present.
size is an integer number of octets. It is optional if not present.
description is a text string. It is optional if not present.
filename is a text string. It is optional if not present.
content_hash is the base64url encoded string of the MIMI contentHash of the ExternalPart, prefixed with the name of the hash algorithm corresponding to hashAlg and a colon (for example "sha256:"). content_hash is mandatory if it was included in the MIMI content ExternalPart, and omitted otherwise.

In addition, the following fields are unique to MIMI VCON.

cached is a boolean. It is mandatory if it is true, which means that a copy of the external content is available in a vcon attachment object (see ). If cache is true and no content_hash is present, a new content hash is calculated for the attachment and placed the cache_ref field (which can only be present in this case).

ExternalPart has several fields for the decryption of the referenced content. If it is not necessary to reconstruct the original MIMI content (for example to allow later verification of the message ID), these fields can be omitted once the content has been downloaded, decrypted, verified, and included in the VCON attachments array. Otherwise they are mandatory if present in the MIMI content. All of these fields are base64url encoded strings.

encAlg
key
nonce
aad

Changes to the parties The party_history object can be interleaved with text objects in the dialog objects array. It indicates when changes have been made to the participants represented by party index zero, as well as properties of individual parties (such as their role or name). The party_history object contains the following fields.

party is the party index of the modified party. It is mandatory.
originator is the party that originated the change. It is optional.
time is the time that the change was effected
event is the type of change. It is mandatory and for MIMI VCONs can be one of the following new event types:
- add: user added by someone else
- self_add: user added herself directly
- leave: user leaves of their own accord
- remove: user is removed by another user
- ban: user is banned from the group
- update:
name is the new name of the user. It is only permitted for an update event.
role is the new role assigned to the user. It is only permitted for an update event.

Changes to the room Changes to the room metadata should be accompanied by a new room dialog type. The room dialog type can contain anything in the top-level room object except for the id (which cannot change). It must contain a time field to convey the time of the change, and may contain an originator field to convey who made that change.

Attachments An attachment consists of the following fields:

start: is the time when the attachment was downloaded. It is mandatory.
party: is the party that downloaded the attachment. It is mandatory.
content_hash: is the base64url encoded hash using the hash name prefixed with a colon before the hash (ex: "sha256:"). It is mandatory.
dialog_object_ref is a string consisting of: "mid:" (representing the message ID URI), the message_id of the message in the dialog object, a colon, the part_index of the Part (or "0" if the ExternalPart is at the top level), and the string "@anon.invalid"

The mediatype, filename, encoding, and body fields are as they are defined in VCON and are all mandatory.

Message tombstones When a message has been deleted/retracted, or it expires, it can be valuable to present a record that such a message was previously present, by generating a dialog object with the following fields (which are all mandatory):

type is "tombstone"
start is the time the tombstone was generated
message_id is the message ID of the message.
status is the status of the former message, either "retracted" or "expired".