# Message schemas

This directory holds JSON Schema files (draft 2020-12) for the messages that the
neoirc HTTP API carries. `message.json` describes the envelope every message
uses. `commands/` holds one file per IRC command and `numerics/` one file per
numeric reply. `README.md` at the repository root documents every command, reply
and field.

## The envelope

Every message is one JSON object with these fields:

- `command`: the IRC command name, such as `PRIVMSG`, or the name of a numeric
  reply, such as `RPL_WELCOME`. Always present.
- `code`: the number of a numeric reply, such as `1` for `RPL_WELCOME`. Absent
  on other messages.
- `id`: the message's UUID, assigned by the server.
- `from`: the sender's nick, or the server name on a server message.
- `to`: the target: a channel name starting with `#`, or a nick.
- `params`: further positional parameters, as an array of strings. `KICK` and
  many numeric replies use it.
- `body`: an array of strings, one per line of text. It is never a bare string.
- `ts`: when the server stored the message, in RFC 3339 form, in UTC.
- `meta`: an object of extra data, such as a hashcash stamp in `meta.hashcash`.
  The server stores and relays it as it is.

Two IRC lines and their JSON form:

```
IRC:  :alice PRIVMSG #general :hello world
JSON: {"command": "PRIVMSG", "from": "alice", "to": "#general", "body": ["hello world"]}

IRC:  :neoirc 353 alice = #general :@op1!op1@host1 alice!alice@host2
JSON: {"command": "RPL_NAMREPLY", "code": 353, "from": "neoirc", "to": "alice",
       "params": ["=", "#general"], "body": ["@op1!op1@host1 alice!alice@host2"]}
```

A `body` with two strings is a two-line message:

```
{"command": "PRIVMSG", "to": "#general", "body": ["line one", "line two"]}
```

## Files

Commands, in `commands/`:

- `PRIVMSG.json`: a message to a channel or a user.
- `NOTICE.json`: a notice. A client must not answer a notice automatically.
- `JOIN.json`: a user joined a channel.
- `PART.json`: a user left a channel.
- `QUIT.json`: a user left the server.
- `NICK.json`: a user changed nick.
- `TOPIC.json`: a channel topic was set.
- `MODE.json`: a channel mode was changed.
- `KICK.json`: a channel operator removed a user from a channel.
- `PING.json` and `PONG.json`: keepalive.
- `PUBKEY.json`: a public signing key announcement. The server does not have
  this command and answers it with `ERR_UNKNOWNCOMMAND` (421).

Numeric replies, in `numerics/`:

- `001.json` `RPL_WELCOME`, `002.json` `RPL_YOURHOST`, `003.json` `RPL_CREATED`
  and `004.json` `RPL_MYINFO`: the welcome replies.
- `322.json` `RPL_LIST` and `323.json` `RPL_LISTEND`: the channel list.
- `332.json` `RPL_TOPIC`: a channel's topic.
- `353.json` `RPL_NAMREPLY` and `366.json` `RPL_ENDOFNAMES`: a channel's member
  list.
- `372.json` `RPL_MOTD`, `375.json` `RPL_MOTDSTART` and `376.json`
  `RPL_ENDOFMOTD`: the message of the day.
- `401.json` `ERR_NOSUCHNICK`: no such nick.
- `403.json` `ERR_NOSUCHCHANNEL`: no such channel.
- `433.json` `ERR_NICKNAMEINUSE`: the nick is taken.
- `442.json` `ERR_NOTONCHANNEL`: the user is not on that channel.
- `482.json` `ERR_CHANOPRIVSNEEDED`: the user is not a channel operator.

## Where the files differ from the server

Where a schema file and the server disagree, the server is right:

- The numeric files put the three-digit code in `command` and have no `code`
  field. The server puts the reply's name in `command` and its number in `code`.
- `353.json` says `body` lists nicks. Over the HTTP API the server lists
  hostmasks, such as `@op1!op1@host1`.
- `MODE.json` puts the mode change in `params`. The server puts it in `body`:
  one string such as `"+o bob"`, or the change and its value as two strings,
  such as `"+k"` and `"secret"`.
- `JOIN.json` has no `body`. The server's `JOIN` event repeats the channel name
  in `body`.
- `PING.json` describes a token in `body`. The server ignores the body of a
  `PING` and answers the HTTP request itself with
  `{"command": "PONG", "from": "<server name>"}`.
- `TOPIC.json` says a `TOPIC` without a body queries the topic. Over the HTTP
  API a `TOPIC` without a body gets `ERR_NEEDMOREPARAMS` (461).
- `PUBKEY.json` describes a command the server does not have.