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

   1 This file describes the schemata used for notmuch's structured output
   2 format (currently JSON).
   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 Common non-terminals
  12 --------------------
  13
  14 # Number of seconds since the Epoch
  15 unix_time = int
  16
  17 # Thread ID, sans "thread:"
  18 threadid = string
  19
  20 # Message ID, sans "id:"
  21 messageid = string
  22
  23 notmuch show schema
  24 -------------------
  25
  26 # A top-level set of threads (do_show)
  27 # Returned by notmuch show without a --part argument
  28 thread_set = [thread*]
  29
  30 # Top-level messages in a thread (show_messages)
  31 thread = [thread_node*]
  32
  33 # A message and its replies (show_messages)
  34 thread_node = [
  35     message?,                 # present if --entire-thread or matched
  36     [thread_node*]            # children of message
  37 ]
  38
  39 # A message (show_message)
  40 message = {
  41     # (format_message_json)
  42     id:             messageid,
  43     match:          bool,
  44     filename:       string,
  45     timestamp:      unix_time, # date header as unix time
  46     date_relative:  string,   # user-friendly timestamp
  47     tags:           [string*],
  48
  49     headers:        headers,
  50     body:           [part]
  51 }
  52
  53 # A MIME part (show_message_body)
  54 part = {
  55     # format_part_start_json
  56     id:             int|string, # part id (currently DFS part number)
  57
  58     # format_part_encstatus_json
  59     encstatus?:     encstatus,
  60
  61     # format_part_sigstatus_json
  62     sigstatus?:     sigstatus,
  63
  64     # format_part_content_json
  65     content-type:   string,
  66     content-id?:    string,
  67     # if content-type starts with "multipart/":
  68     content:        [part*],
  69     # if content-type is "message/rfc822":
  70     content:        [{headers: headers, body: [part]}],
  71     # otherwise (leaf parts):
  72     filename?:      string,
  73     content-charset?: string,
  74     # A leaf part's body content is optional, but may be included if
  75     # it can be correctly encoded as a string.  Consumers should use
  76     # this in preference to fetching the part content separately.
  77     content?:       string
  78 }
  79
  80 # The headers of a message (format_headers_json with raw headers
  81 # and reply = FALSE) or a part (format_headers_message_part_json
  82 # with pretty-printed headers)
  83 headers = {
  84     Subject:        string,
  85     From:           string,
  86     To?:            string,
  87     Cc?:            string,
  88     Bcc?:           string,
  89     Date:           string
  90 }
  91
  92 # Encryption status (format_part_encstatus_json)
  93 encstatus = [{status: "good"|"bad"}]
  94
  95 # Signature status (format_part_sigstatus_json)
  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 }
 140
 141 notmuch reply schema
 142 --------------------
 143
 144 reply = {
 145     # The headers of the constructed reply (format_headers_json with
 146     # raw headers and reply = TRUE)
 147     reply-headers: reply_headers,
 148
 149     # As in the show format (format_part_json)
 150     original: message
 151 }
 152
 153 reply_headers = {
 154     Subject:        string,
 155     From:           string,
 156     To?:            string,
 157     Cc?:            string,
 158     Bcc?:           string,
 159     In-reply-to:    string,
 160     References:     string
 161 }