1 % JSON Domain Format as Implemented by Pdns-Pipe-Nmc
7 `DomObj` either a `String` containing a dotted quad (see Note below),
8 or a JSON `Map`, with the following attributes, all optional:
10 | Key | Type | Comment |
11 |-------------|---------------------------------------|--------------------------------------------|
12 | service | Array(SrvObj) | Located two levels above position |
13 | ip | Array(String) | Dotted quad format "1.2.3.4" |
14 | ip6 | Array(String) | Semicolon format "DEAD::BEEF" |
15 | tor | String | Onion name |
17 | freenet | String | |
18 | alias | String | Nullifies other attributes |
19 | translate | String | Nullifies other attributes |
20 | email | String | Used in `SOA` |
21 | loc | String | Format suitable for `LOC` |
22 | info | JsonObj | Currently unspecified |
23 | ns | Array(String) | Domain names as in `NS` |
24 | delegate | String | Replaces current object |
25 | import | Array(String) | "Deep" merges into current object |
26 | map | Map(String:DomObj) | Tree of subdomain objects |
27 | fingerprint | Array(String) | |
28 | tls | Map(String:Map(String:Array(TlsObj))) | Outer `Map` by `Protocol`, inner by `Port` |
29 | ds | Array(DsObj) | |
33 * Any attribute specified as `Array(String)` may be present in the
34 JSON document as a plain `String`, which is interpreted the same way
35 as an `Array` containing a single `String` element.
36 * If `DomObj` is a `String`, it is interpreted as an IPv4 address.
37 In other words, string `"1.2.3.4"` is the same as the Map
38 `"{\"ip\":\"1.2.3.4\"}"`. Such "shorthand" DomObj can be present at
39 the top level or as a value in the `"map"` attribute.
43 `SrvObj` is a heterogenous Array of fixed size containing 6 elements:
45 | N | Type | Meaning |
46 |---|--------|----------|
47 | 0 | String | Service |
48 | 1 | String | Protocol |
49 | 2 | Int | Priority |
52 | 5 | String | Hostname |
56 * `Service` and `Protocol` are two elements of the domain name, without
58 * `SrvObj` with Service `"smtp"`, Protocol `"tcp"` and Port `25` is also
59 interpteted as an `MX` DNS resource.
60 * When lookup is performed for `SRV` records at fqdn
61 `"_serv._proto.sub.dom.bit"`, domain object for `"sub.dom.bit"` must be
62 fetched, and in this object, `SrvObj`s for the Service `"serv"` and
63 Protocol `"proto"` selected from its `"service"` attribute.
67 `TlsObj` is a heterogenous Array of fixed size containing 3 elements:
69 | N | Type | Meaning |
70 |---|--------|-------------------------------------------------------|
71 | 0 | Int | Match type - 0:Exact, 1:SHA-256, 2:SHA-512 |
72 | 1 | String | Match value - certificate or hash of it as hex string |
73 | 2 | Int | Include subdomains - 0:No, 1:Yes |
77 `DsObj` is a heterogenous Array of fixed size containing 4 elements:
79 | N | Type | Meaning |
80 |---|--------|--------------------------|
82 | 1 | Int | Key Algorithm |
83 | 2 | Int | Hash Type |
84 | 3 | String | Hash Value as hex string |
86 ## Data Interpretation
88 ### Semantics of the Attributes
90 #### service attribute
92 Translates to DNS `SRV` RR, only it is located in the subdomain tree
93 two levels higher than the `SRV` record would. For example, a
94 `"service"` attribute in the `"map"` hieararchy at the point
95 corresponding to the FQDN "sub.dom.bit" with the value
98 "service": [ ["imap", "tcp", 0, 0, 143, "mail.host.com." ],
99 ["smtp", "tcp", 0, 0, 25, "relay.host.com."] ]
102 corresponds to two `SRV` RRs at two different points in the
106 _imap._tcp.sub.dom.bit. IN SRV 0 0 143 mail.host.com.
107 _smtp._tcp.sub.dom.bit. IN SRV 0 0 25 relay.host.com.
110 In addition to these, an `MX` RR is syntesized at the "sub.dom.bit"
114 sub.dom.bit. IN MX 0 relay.host.com.
119 Contains a list of strings representing IPv4 addresses in dotted
120 quad notation. For example,
123 "ip": ["1.2.3.4", "5.6.7.8"]
126 translates into a series of `A` RRs:
142 #### freenet attribute
148 #### translate attribute
163 #### delegate attribute
166 #### import attribute
172 #### fingerprint attribute
183 Assuming a query is performed for
184 `sdN`++"."++{...}++"."++`sd2`++"."++`sd1`++"."++`dom`++".bit"
185 (`sdX` list possibly being empty), the lookup process starts by
186 querying the database for the object corresponding to `dom`.
187 Technically, it is easiest to populate a "seed" DomObj with a
188 single attribute `"import"` the value of which corresponds to the
189 `dom` name in the Namecoin namespace, which is `"d/" ++ dom`.
190 This domain object is then transformed by the following
193 1. Value of the element of the `"map"` attribute with the key `""`
194 (empty string) is recursively merged into the base domain. The
195 `""` element of the `"map"` is removed from the result.
196 2. If attribute `"import"` does not exist in the resulting object,
197 recursion stops, and step 3 is performed on the result
198 If attribute `"import"` exists in the resulting object, lookup is
199 is performed for the values of this attribute, and fetched objects
200 are recursively merged into the base domain. The `"import"` attribute
201 is removed from the result. Then the result is passed as base
203 3. If subdomain chain is empty, recursion stops, and step 4 is
204 performed on the result. If subdomain chain is not empty, next
205 element is taken out of the chain, and the `"map"` is looked
206 up for the element with the name matching the subdomain element.
207 The value of this element of the `"map"` is passed as base domain
208 to step 1. If matching element does not exist, lookup is considered
210 4. Domain object with all `""` map elements and all `"import"` data
211 merged is "normalized" by removal of attributes that are nullified
212 by the presence of other attributes.
214 Note that the process involves recursion nested to three levels.
216 ### Merging Procedure
218 When a domain object `sub` needs merging into a domain object `base`,
219 the following rules are applied:
221 * Of `String` and other "scalar" attributes, one is chosen, the value
222 from the `base` taking precedence.
223 * On `Array` attribtes, `union` operation is performed. (Of equal
224 elements, only one copy is left.)
225 * On `Map` attributes, recursive merge is performed. On the top level,
226 elemens with keys that are only present in either `base` or `sub`
227 object are all put into result. The values of the elements that are
228 present in both `base` and `sub` are merged according to the rules
229 applicable to their type.