path: root/draft-jchat-00.txt

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,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174,
              DOI 10.17487/RFC8174, May 2017,
              <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON)
              Data Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

   [RFC8620]  Jenkins, N. and C. Newman, "The JSON Meta Application
              Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620,
              July 2019, <https://www.rfc-editor.org/info/rfc8620>.

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,
              <https://www.rfc-editor.org/info/rfc6901>.

Author's Address

   Calvin Smith
   Fastmail
   
   Email: calvin@fastmail.com