Internet Engineering Task Force (IETF) C. Smith Internet-Draft Fastmail Intended status: Standards Track August 15, 2025 Expires: February 16, 2026 The JSON Chat Application Protocol (JCHAT) draft-jchat-00 Abstract This document specifies a protocol for real-time chat messaging built on top of the JSON Meta Application Protocol (JMAP) [RFC8620]. JCHAT provides a standardized way to exchange chat messages, manage conversations, handle user presence, and synchronize chat state across multiple devices efficiently. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on February 16, 2026. Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 2. JCHAT Capability . . . . . . . . . . . . . . . . . . . . . . 4 3. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Conversation . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Message . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.3. Participant . . . . . . . . . . . . . . . . . . . . . . . 10 3.4. Presence . . . . . . . . . . . . . . . . . . . . . . . . 11 4. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1. Conversation Methods . . . . . . . . . . . . . . . . . . . 12 4.1.1. Conversation/get . . . . . . . . . . . . . . . . . . . 12 4.1.2. Conversation/set . . . . . . . . . . . . . . . . . . . 13 4.1.3. Conversation/changes . . . . . . . . . . . . . . . . . 15 4.1.4. Conversation/query . . . . . . . . . . . . . . . . . . 15 4.2. Message Methods . . . . . . . . . . . . . . . . . . . . . 17 4.2.1. Message/get . . . . . . . . . . . . . . . . . . . . . 17 4.2.2. Message/set . . . . . . . . . . . . . . . . . . . . . 18 4.2.3. Message/changes . . . . . . . . . . . . . . . . . . . 20 4.2.4. Message/query . . . . . . . . . . . . . . . . . . . . 20 4.3. Participant Methods . . . . . . . . . . . . . . . . . . . 22 4.3.1. Participant/get . . . . . . . . . . . . . . . . . . . 22 4.3.2. Participant/set . . . . . . . . . . . . . . . . . . . 23 4.3.3. Participant/changes . . . . . . . . . . . . . . . . . 24 4.4. Presence Methods . . . . . . . . . . . . . . . . . . . . . 25 4.4.1. Presence/get . . . . . . . . . . . . . . . . . . . . . 25 4.4.2. Presence/set . . . . . . . . . . . . . . . . . . . . . 26 5. Push Notifications . . . . . . . . . . . . . . . . . . . . . 27 6. Security Considerations . . . . . . . . . . . . . . . . . . . 28 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 8.1. Normative References . . . . . . . . . . . . . . . . . . . 29 8.2. Informative References . . . . . . . . . . . . . . . . . . 30 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 1. Introduction Modern chat applications require real-time message delivery, efficient synchronization across multiple devices, and robust handling of conversations with multiple participants. The JSON Meta Application Protocol (JMAP) [RFC8620] provides an excellent foundation for building such applications with its efficient delta synchronization, push notifications, and batched operations. JCHAT builds upon JMAP to provide: o Structured conversation management with metadata o Real-time message delivery and synchronization o Participant management and permissions o User presence information o Message threading and replies o Rich message content including attachments o Message delivery receipts and read status This specification defines the data model and methods for a chat system that can scale from simple one-on-one messaging to large group conversations while maintaining the efficiency benefits of JMAP. 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. The underlying format used for this specification is JSON. Consequently, the terms "object" and "array" as well as the four primitive types (strings, numbers, booleans, and null) are to be interpreted as described in Section 1 of [RFC8259]. Type signatures follow the conventions established in [RFC8620]. 1.2. Terminology Conversation: A container for messages between one or more participants. Conversations have metadata such as a title, creation time, and participant list. Message: A single communication within a conversation, containing text content, metadata, and optionally attachments or replies to other messages. Participant: A user who is a member of a conversation and can send and receive messages within that conversation. Presence: Information about a user's current availability status and activity. 2. JCHAT Capability The JCHAT capability is identified by the URI: "urn:ietf:params:jmap:chat" This capability is advertised in the "capabilities" object of the JMAP Session response. The value of this capability in the capabilities object MUST be an object with the following properties: o maxConversationsPerAccount: "UnsignedInt|null" The maximum number of conversations allowed per account. If null, there is no limit. o maxParticipantsPerConversation: "UnsignedInt|null" The maximum number of participants allowed in a single conversation. If null, there is no limit. o maxMessageLength: "UnsignedInt|null" The maximum length in UTF-8 octets of a message body. If null, there is no limit. o supportedMessageTypes: "String[]" A list of message content types supported by the server. MUST include "text/plain". MAY include "text/html", "text/markdown", and others. o maxAttachmentSize: "UnsignedInt|null" The maximum size in octets of a single attachment. If null, attachments are not supported. 3. Data Types 3.1. Conversation A *Conversation* object represents a chat conversation between one or more participants. It has the following properties: o id: "Id" (immutable; server-set) The id of the conversation. o title: "String|null" A user-defined title for the conversation. If null, clients SHOULD generate a title from participant names. o description: "String|null" An optional description of the conversation purpose. o createdAt: "UTCDate" (immutable; server-set) The date and time the conversation was created. o updatedAt: "UTCDate" (server-set) The date and time the conversation was last modified. o isArchived: "Boolean" (default: false) Whether this conversation has been archived by the user. o isMuted: "Boolean" (default: false) Whether notifications for this conversation are muted. o participantIds: "Id[]" The list of participant IDs who are members of this conversation. The order MAY be significant for display purposes. o lastMessageId: "Id|null" (server-set) The ID of the most recent message in this conversation. null if the conversation has no messages. o lastMessageAt: "UTCDate|null" (server-set) The timestamp of the most recent message in this conversation. null if the conversation has no messages. o unreadCount: "UnsignedInt" (server-set) The number of unread messages in this conversation for this user. o messageCount: "UnsignedInt" (server-set) The total number of messages in this conversation. o metadata: "String[String]|null" Application-specific metadata as key-value pairs. 3.2. Message A *Message* object represents a single message within a conversation. It has the following properties: o id: "Id" (immutable; server-set) The id of the message. o conversationId: "Id" (immutable) The id of the conversation this message belongs to. o senderId: "Id" (immutable) The id of the participant who sent this message. o sentAt: "UTCDate" (immutable; server-set) The date and time the message was sent. o receivedAt: "UTCDate" (immutable; server-set) The date and time the message was received by the server. o editedAt: "UTCDate|null" (server-set) The date and time the message was last edited. null if never edited. o body: "String" The main content of the message. o bodyType: "String" (default: "text/plain") The MIME type of the message body. Servers MUST support "text/plain". MAY support "text/html", "text/markdown". o attachments: "Attachment[]|null" A list of file attachments associated with this message. null if no attachments. o replyToMessageId: "Id|null" The id of the message this message is replying to. null if not a reply. o isSystemMessage: "Boolean" (immutable; default: false) Whether this is a system-generated message (e.g., user joined/left conversation). o isDeleted: "Boolean" (default: false) Whether this message has been marked as deleted. o reactions: "Reaction[]|null" (server-set) A list of emoji reactions to this message. null if no reactions. o deliveryStatus: "DeliveryStatus" (server-set) The delivery status of this message. o readBy: "MessageRead[]" (server-set) A list of participants who have read this message. o metadata: "String[String]|null" Application-specific metadata as key-value pairs. An *Attachment* object has the following properties: o blobId: "Id" The blob id of the attachment data. o name: "String" The filename of the attachment. o type: "String" The MIME type of the attachment. o size: "UnsignedInt" The size of the attachment in octets. A *Reaction* object has the following properties: o emoji: "String" The Unicode emoji character(s) for the reaction. o participantIds: "Id[]" The list of participant IDs who added this reaction. A *DeliveryStatus* is a string with one of the following values: o "sending": The message is being sent to the server. o "sent": The message has been accepted by the server. o "delivered": The message has been delivered to all online participants. o "failed": The message failed to send. A *MessageRead* object has the following properties: o participantId: "Id" The id of the participant who read the message. o readAt: "UTCDate" When the participant read the message. 3.3. Participant A *Participant* object represents a user's membership in a conversation. It has the following properties: o id: "Id" (immutable; server-set) The id of the participant record. o conversationId: "Id" (immutable) The id of the conversation. o userId: "Id" (immutable) The id of the user account. o displayName: "String" The display name for this participant in this conversation. o avatarBlobId: "Id|null" The blob id of the participant's avatar image. null if no custom avatar. o role: "String" (default: "member") The participant's role in the conversation. Possible values: "owner", "admin", "member", "observer". o joinedAt: "UTCDate" (immutable; server-set) When the participant joined the conversation. o lastActiveAt: "UTCDate|null" (server-set) When the participant was last active in this conversation. null if never active. o isActive: "Boolean" (server-set) Whether the participant is currently an active member of the conversation. o permissions: "String[]" The list of permissions this participant has in the conversation. Possible values: "send", "edit", "delete", "invite", "remove", "manage". o metadata: "String[String]|null" Application-specific metadata as key-value pairs. 3.4. Presence A *Presence* object represents a user's current availability status. It has the following properties: o userId: "Id" (immutable) The id of the user account. o status: "String" The user's current status. Possible values: "online", "away", "busy", "offline". o statusMessage: "String|null" An optional custom status message. o lastSeenAt: "UTCDate|null" (server-set) When the user was last seen online. null if currently online or privacy settings prevent sharing. o updatedAt: "UTCDate" (server-set) When the presence information was last updated. 4. Methods 4.1. Conversation Methods 4.1.1. Conversation/get Standard "/get" method as described in [RFC8620], Section 5.1. The following additional properties are supported in the response: Additional errors: None specific to this method. 4.1.2. Conversation/set Standard "/set" method as described in [RFC8620], Section 5.3. When creating a new conversation, the following properties are required in the create object: o participantIds: Must include at least the creating user. The following properties MUST NOT be included when creating a conversation: o id, createdAt, updatedAt, lastMessageId, lastMessageAt, unreadCount, messageCount When updating a conversation, the following properties are immutable and MUST NOT be changed: o id, createdAt Additional SetErrors: o "invalidParticipants": The participantIds list is invalid (empty, contains non-existent users, etc.). o "maxParticipantsExceeded": The conversation would exceed the maximum number of participants allowed. o "insufficientPermissions": The user does not have permission to perform the requested action on this conversation. 4.1.3. Conversation/changes Standard "/changes" method as described in [RFC8620], Section 5.2. 4.1.4. Conversation/query Standard "/query" method as described in [RFC8620], Section 5.5. Supported filter conditions: o hasParticipant: "Id" Matches conversations where the specified user is a participant. o isArchived: "Boolean" Matches conversations with the specified archived status. o after: "UTCDate" Matches conversations with lastMessageAt after this date. o before: "UTCDate" Matches conversations with lastMessageAt before this date. o hasUnread: "Boolean" If true, matches conversations with unreadCount > 0. If false, matches conversations with unreadCount = 0. Supported sort options: o "lastMessageAt": Sort by the timestamp of the last message. o "createdAt": Sort by conversation creation time. o "title": Sort by conversation title (case-insensitive). o "unreadCount": Sort by number of unread messages. Default sort is "lastMessageAt desc". 4.2. Message Methods 4.2.1. Message/get Standard "/get" method as described in [RFC8620], Section 5.1. Additional errors: None specific to this method. 4.2.2. Message/set Standard "/set" method as described in [RFC8620], Section 5.3. When creating a new message, the following properties are required in the create object: o conversationId: Must reference an existing conversation. o body: The message content. The following properties MUST NOT be included when creating a message: o id, sentAt, receivedAt, editedAt, reactions, deliveryStatus, readBy The following properties are set by the server when creating: o senderId: Set to the authenticated user's participant ID in the specified conversation. When updating a message, the following properties are immutable and MUST NOT be changed: o id, conversationId, senderId, sentAt, receivedAt, isSystemMessage Only the message sender can edit these properties: o body, bodyType, attachments The server MUST set editedAt when any editable property is modified. Message deletion is handled by setting isDeleted to true. Servers MAY permanently delete message content after a retention period. Additional SetErrors: o "conversationNotFound": The specified conversationId does not exist. o "notParticipant": The user is not a participant in the specified conversation. o "messageNotFound": The message to update does not exist. o "cannotEditMessage": The user does not have permission to edit this message (not the sender, message too old, etc.). o "invalidReplyTo": The replyToMessageId references a non-existent message or a message in a different conversation. o "messageTooLarge": The message body exceeds maxMessageLength. 4.2.3. Message/changes Standard "/changes" method as described in [RFC8620], Section 5.2. 4.2.4. Message/query Standard "/query" method as described in [RFC8620], Section 5.5. Supported filter conditions: o inConversation: "Id" Matches messages in the specified conversation. o from: "Id" Matches messages sent by the specified participant. o after: "UTCDate" Matches messages sent after this date. o before: "UTCDate" Matches messages sent before this date. o hasAttachment: "Boolean" If true, matches messages with attachments. o text: "String" Matches messages containing this text in the body (case-insensitive substring search). o isUnread: "Boolean" If true, matches unread messages for this user. o replyTo: "Id" Matches messages that are replies to the specified message. Supported sort options: o "sentAt": Sort by message timestamp. o "receivedAt": Sort by server receive timestamp. Default sort is "sentAt asc". 4.3. Participant Methods 4.3.1. Participant/get Standard "/get" method as described in [RFC8620], Section 5.1. 4.3.2. Participant/set Standard "/set" method as described in [RFC8620], Section 5.3. When creating a new participant, the following properties are required in the create object: o conversationId: Must reference an existing conversation. o userId: Must reference an existing user account. The following properties MUST NOT be included when creating a participant: o id, joinedAt, lastActiveAt, isActive When updating a participant, the following properties are immutable and MUST NOT be changed: o id, conversationId, userId, joinedAt Only conversation owners/admins can modify: o role, permissions Additional SetErrors: o "conversationNotFound": The specified conversationId does not exist. o "userNotFound": The specified userId does not exist. o "alreadyParticipant": The user is already a participant in this conversation. o "cannotModifyParticipant": The user does not have permission to modify participants in this conversation. o "cannotRemoveSelf": The user cannot remove themselves from the conversation (use conversation archiving instead). 4.3.3. Participant/changes Standard "/changes" method as described in [RFC8620], Section 5.2. 4.4. Presence Methods 4.4.1. Presence/get Standard "/get" method as described in [RFC8620], Section 5.1. Users can only retrieve presence information for users they share conversations with, unless broader permissions are granted. Additional errors: o "cannotAccessPresence": The user does not have permission to view presence information for the requested users. 4.4.2. Presence/set Standard "/set" method as described in [RFC8620], Section 5.3. Users can only update their own presence information. The following properties are immutable and MUST NOT be changed: o userId, lastSeenAt, updatedAt Additional SetErrors: o "cannotSetOthersPresence": Attempted to set presence for a user other than the authenticated user. 5. Push Notifications JCHAT extends JMAP push notifications to provide real-time updates for chat events. The following state changes trigger push notifications: o New messages in conversations the user participates in o Changes to conversation metadata o Participant additions/removals o Presence updates for users the client is interested in Push subscription setup follows the standard JMAP push model described in [RFC8620], Section 7. The push notification payload includes the standard JMAP StateChange object with the following chat-specific type changes: o "Conversation": Conversation state changes o "Message": Message state changes o "Participant": Participant state changes o "Presence": Presence state changes Clients SHOULD subscribe to push notifications for responsive chat experience and battery efficiency on mobile devices. 6. Security Considerations JCHAT inherits the security model of JMAP [RFC8620] and adds the following chat-specific considerations: o Message Privacy: Messages are only accessible to conversation participants. Servers MUST enforce participant membership when processing requests. o Participant Management: Only users with appropriate permissions can add/remove participants or modify conversation settings. o Presence Privacy: Presence information should only be shared with users who share conversations or have explicit permission. o Message Retention: Servers SHOULD provide configurable message retention policies and honor deletion requests. o Content Filtering: Servers MAY implement content filtering for spam, abuse, or regulatory compliance. o Rate Limiting: Servers SHOULD implement rate limiting for message sending to prevent abuse. 7. IANA Considerations This document registers the JMAP Capability for chat as follows: Capability Name: urn:ietf:params:jmap:chat Specification document: This document Intended use: COMMON Change controller: IETF Security and privacy considerations: See Section 6 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July 2019, . 8.2. Informative References [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, . Author's Address Calvin Smith Fastmail Email: calvin@fastmail.com