CLEMA Protocol Specification

CLEMA — Common Language for Exchanging Messages and Attachments

Version: 2.0.0

CLEMA is a lightweight, extensible protocol for real-time messaging and file transfer. It is designed to be simple, secure, and easy to implement.

Key Features

Transport: WebSocket over TLS (WSS)
Format: JSON messages
Security: TLS encryption, authentication required
Files: durable S3-backed attachments and optional online-only direct relay
Conversations: direct chats, groups and broadcast channels with roles and invitations
Search: global conversation/message search and scoped in-chat search
Mobile: sign-in by phone, push notifications and background sync
Schema: every message type, what it carries and what it is answered with, as a JSON Schema (draft 2020-12) generated from the reference server's code: clema.schema.json, whose x-clema-messages maps each type to its data, its response and whether streams keep it; clients generate their types from it

URL: wss://<host>/ws
Port: 443 (standard HTTPS/WSS port)
Compression: the server accepts permessage-deflate (RFC 7692) from a client that offers it; one that does not is spoken to uncompressed
Keepalive: anything within 120 seconds — a WebSocket ping frame, connection.ping or a request (see Keepalive)

The protocol's JSON Schema, to generate a client's types from: clema.schema.json.