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.  |'s indicate
   8 alternates (e.g., int|string means something can be an int or a
   9 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 Common non-terminals
  18 --------------------
  19
  20 # Number of seconds since the Epoch
  21 unix_time = int
  22
  23 # Thread ID, sans "thread:"
  24 threadid = string
  25
  26 # Message ID, sans "id:"
  27 messageid = string
  28
  29 notmuch show schema
  30 -------------------
  31
  32 # A top-level set of threads (do_show)
  33 # Returned by notmuch show without a --part argument
  34 thread_set = [thread*]
  35
  36 # Top-level messages in a thread (show_messages)
  37 thread = [thread_node*]
  38
  39 # A message and its replies (show_messages)
  40 thread_node = [
  41     message|null,             # null if not matched and not --entire-thread
  42     [thread_node*]            # children of message
  43 ]
  44
  45 # A message (format_part_sprinter)
  46 message = {
  47     # (format_message_sprinter)
  48     id:             messageid,
  49     match:          bool,
  50     filename:       string,
  51     timestamp:      unix_time, # date header as unix time
  52     date_relative:  string,   # user-friendly timestamp
  53     tags:           [string*],
  54
  55     headers:        headers,
  56     body?:          [part]    # omitted if --body=false
  57 }
  58
  59 # A MIME part (format_part_sprinter)
  60 part = {
  61     id:             int|string, # part id (currently DFS part number)
  62
  63     encstatus?:     encstatus,
  64     sigstatus?:     sigstatus,
  65
  66     content-type:   string,
  67     content-id?:    string,
  68     # if content-type starts with "multipart/":
  69     content:        [part*],
  70     # if content-type is "message/rfc822":
  71     content:        [{headers: headers, body: [part]}],
  72     # otherwise (leaf parts):
  73     filename?:      string,
  74     content-charset?: string,
  75     # A leaf part's body content is optional, but may be included if
  76     # it can be correctly encoded as a string.  Consumers should use
  77     # this in preference to fetching the part content separately.
  78     content?:       string
  79 }
  80
  81 # The headers of a message or part (format_headers_sprinter with reply = FALSE)
  82 headers = {
  83     Subject:        string,
  84     From:           string,
  85     To?:            string,
  86     Cc?:            string,
  87     Bcc?:           string,
  88     Reply-To?:      string,
  89     Date:           string
  90 }
  91
  92 # Encryption status (format_part_sprinter)
  93 encstatus = [{status: "good"|"bad"}]
  94
  95 # Signature status (format_part_sigstatus_sprinter)
  96 sigstatus = [signature*]
  97
  98 signature = {
  99     # (signature_status_to_string)
 100     status:         "none"|"good"|"bad"|"error"|"unknown",
 101     # if status is "good":
 102     fingerprint?:   string,
 103     created?:       unix_time,
 104     expires?:       unix_time,
 105     userid?:        string
 106     # if status is not "good":
 107     keyid?:         string
 108     # if the signature has errors:
 109     errors?:        int
 110 }
 111
 112 notmuch search schema
 113 ---------------------
 114
 115 # --output=summary
 116 summary = [thread*]
 117
 118 # --output=threads
 119 threads = [threadid*]
 120
 121 # --output=messages
 122 messages = [messageid*]
 123
 124 # --output=files
 125 files = [string*]
 126
 127 # --output=tags
 128 tags = [string*]
 129
 130 thread = {
 131     thread:         threadid,
 132     timestamp:      unix_time,
 133     date_relative:  string,   # user-friendly timestamp
 134     matched:        int,      # number of matched messages
 135     total:          int,      # total messages in thread
 136     authors:        string,   # comma-separated names with | between
 137                               # matched and unmatched
 138     subject:        string,
 139     tags:           [string*]
 140 }
 141
 142 notmuch reply schema
 143 --------------------
 144
 145 reply = {
 146     # The headers of the constructed reply
 147     reply-headers: reply_headers,
 148
 149     # As in the show format (format_part_sprinter)
 150     original: message
 151 }
 152
 153 # Reply headers (format_headers_sprinter with reply = TRUE)
 154 reply_headers = {
 155     Subject:        string,
 156     From:           string,
 157     To?:            string,
 158     Cc?:            string,
 159     Bcc?:           string,
 160     In-reply-to:    string,
 161     References:     string
 162 }