git.notmuchmail.org Git - notmuch/blob - devel/schemata

   1 This file describes the schemata used for notmuch's structured output
   2 format (currently JSON and S-Expressions).
   3
   4 []'s indicate lists.  List items can be marked with a '?', meaning
   5 they are optional; or a '*', meaning there can be zero or more of that
   6 item.  {}'s indicate an object that maps from field identifiers to
   7 values.  An object field marked '?' is optional; one marked with '*'
   8 can repeat (with a different name). |'s indicate alternates (e.g.,
   9 int|string means something can be an int or a string).
  10
  11 For S-Expression output, lists are printed delimited by () instead of
  12 []. Objects are printed as p-lists, i.e. lists where the keys and values
  13 are interleaved. Keys are printed as keywords (symbols preceded by a
  14 colon), e.g. (:id "123" :time 54321 :from "foobar"). Null is printed as
  15 nil, true as t and false as nil.
  16
  17 This is version 5 of the structured output format.
  18
  19 Version history
  20 ---------------
  21
  22 v1
  23 - First versioned schema release.
  24 - Added part.content-length and part.content-transfer-encoding fields.
  25
  26 v2
  27 - Added the thread_summary.query field.
  28
  29 v3
  30 - Replaced message.filename string with a list of filenames.
  31 - Added part.content-disposition field.
  32
  33 v4
  34 - replace signature error integer bitmask with a set of flags for
  35   individual errors.
  36 - (notmuch 0.29) added message.crypto to identify overall message
  37   cryptographic state
  38
  39 v5
  40 - sorting support for notmuch show (no change to actual schema,
  41   just new command line argument)
  42
  43 Common non-terminals
  44 --------------------
  45
  46 # Number of seconds since the Epoch
  47 unix_time = int
  48
  49 # Thread ID, sans "thread:"
  50 threadid = string
  51
  52 # Message ID, sans "id:"
  53 messageid = string
  54
  55 # E-mail header name, sans trailing colon, like "Subject" or "In-Reply-To"
  56 header_name = string
  57
  58 notmuch show schema
  59 -------------------
  60
  61 # A top-level set of threads (do_show)
  62 # Returned by notmuch show without a --part argument
  63 thread_set = [thread*]
  64
  65 # Top-level messages in a thread (show_messages)
  66 thread = [thread_node*]
  67
  68 # A message and its replies (show_messages)
  69 thread_node = [
  70     message|null,             # null if not matched and not --entire-thread
  71     [thread_node*]            # children of message
  72 ]
  73
  74 # A message (format_part_sprinter)
  75 message = {
  76     # (format_message_sprinter)
  77     id:             messageid,
  78     match:          bool,
  79     filename:       [string*],
  80     timestamp:      unix_time, # date header as unix time
  81     date_relative:  string,   # user-friendly timestamp
  82     tags:           [string*],
  83
  84     headers:        headers,
  85     crypto:         crypto,
  86     body?:          [part]    # omitted if --body=false
  87 }
  88
  89 # when showing the message, was any or all of it decrypted?
  90 msgdecstatus: "full"|"partial"
  91
  92 # The overall cryptographic state of the message as a whole:
  93 crypto = {
  94     signed?:    {
  95                   status:      sigstatus,
  96                   # was the set of signatures described under encrypted cover?
  97                   encrypted:   bool,
  98                   # which of the headers is covered by sigstatus?
  99                   headers:     [header_name*]
 100                 },
 101     decrypted?: {
 102                   status: msgdecstatus,
 103                   # map encrypted headers that differed from the outside headers.
 104                   # the value of each item in the map is what that field showed externally
 105                   # (maybe null if it was not present in the external headers).
 106                   header-mask:  { header_name*: string|null }
 107                 }
 108 }
 109
 110 # A MIME part (format_part_sprinter)
 111 part = {
 112     id:             int|string, # part id (currently DFS part number)
 113
 114     encstatus?:     encstatus,
 115     sigstatus?:     sigstatus,
 116
 117     content-type:   string,
 118     content-disposition?:       string,
 119     content-id?:    string,
 120     # if content-type starts with "multipart/":
 121     content:        [part*],
 122     # if content-type is "message/rfc822":
 123     content:        [{headers: headers, body: [part]}],
 124     # otherwise (leaf parts):
 125     filename?:      string,
 126     content-charset?: string,
 127     # A leaf part's body content is optional, but may be included if
 128     # it can be correctly encoded as a string.  Consumers should use
 129     # this in preference to fetching the part content separately.
 130     content?:       string,
 131     # If a leaf part's body content is not included, the length of
 132     # the encoded content (in bytes) may be given instead.
 133     content-length?: int,
 134     # If a leaf part's body content is not included, its transfer encoding
 135     # may be given.  Using this and the encoded content length, it is
 136     # possible for the consumer to estimate the decoded content length.
 137     content-transfer-encoding?: string
 138 }
 139
 140 # The headers of a message or part (format_headers_sprinter with reply = FALSE)
 141 headers = {
 142     Subject:        string,
 143     From:           string,
 144     To?:            string,
 145     Cc?:            string,
 146     Bcc?:           string,
 147     Reply-To?:      string,
 148     Date:           string,
 149     extra_header_pair*
 150 }
 151
 152 extra_header_pair=  (header_name: string)
 153 # Encryption status (format_part_sprinter)
 154 encstatus = [{status: "good"|"bad"}]
 155
 156 # Signature status (format_part_sigstatus_sprinter)
 157 sigstatus = [signature*]
 158
 159 signature = {
 160     # (signature_status_to_string)
 161     status:         "good"|"bad"|"error"|"unknown",
 162     # if status is "good":
 163     fingerprint?:   string,
 164     created?:       unix_time,
 165     expires?:       unix_time,
 166     userid?:        string
 167     email?:         string
 168     # if status is not "good":
 169     keyid?:         string
 170     errors?:        sig_errors
 171 }
 172
 173 sig_errors = {
 174     key-revoked?: bool,
 175     key-expired?: bool,
 176     sig-expired?: bool,
 177     key-missing?: bool,
 178     alg-unsupported?: bool,
 179     crl-missing?: bool,
 180     crl-too-old?: bool,
 181     bad-policy?: bool,
 182     sys-error?: bool,
 183     tofu-conflict?: bool
 184 }
 185
 186 notmuch search schema
 187 ---------------------
 188
 189 # --output=summary
 190 search_summary = [thread_summary*]
 191
 192 # --output=threads
 193 search_threads = [threadid*]
 194
 195 # --output=messages
 196 search_messages = [messageid*]
 197
 198 # --output=files
 199 search_files = [string*]
 200
 201 # --output=tags
 202 search_tags = [string*]
 203
 204 thread_summary = {
 205     thread:         threadid,
 206     timestamp:      unix_time,
 207     date_relative:  string,   # user-friendly timestamp
 208     matched:        int,      # number of matched messages
 209     total:          int,      # total messages in thread
 210     authors:        string,   # comma-separated names with | between
 211                               # matched and unmatched
 212     subject:        string,
 213     tags:           [string*],
 214
 215     # Two stable query strings identifying exactly the matched and
 216     # unmatched messages currently in this thread.  The messages
 217     # matched by these queries will not change even if more messages
 218     # arrive in the thread.  If there are no matched or unmatched
 219     # messages, the corresponding query will be null (there is no
 220     # query that matches nothing).  (Added in schema version 2.)
 221     query:          [string|null, string|null],
 222 }
 223
 224 notmuch reply schema
 225 --------------------
 226
 227 reply = {
 228     # The headers of the constructed reply
 229     reply-headers: reply_headers,
 230
 231     # As in the show format (format_part_sprinter)
 232     original: message
 233 }
 234
 235 # Reply headers (format_headers_sprinter with reply = TRUE)
 236 reply_headers = {
 237     Subject:        string,
 238     From:           string,
 239     To?:            string,
 240     Cc?:            string,
 241     Bcc?:           string,
 242     In-reply-to:    string,
 243     References:     string
 244 }