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