1 % JSON Domain Format as Implemented by Pdns-Pipe-Nmc
5 `DomObj` is a JSON object, specifically a `Map` (not an `Array`), or a
6 `String` containing a dotted quad (see Note below).
10 `DomObj` is a JSON `Map`, with the following attributes, all optional:
12 | Key | Type | Comment |
13 |-------------|---------------------------------------|---------------------------------|
14 | service | Array(SrvObj) | Located two levels above pos. |
15 | ip | Array(String) | Dotted quad "1.2.3.4" |
16 | ip6 | Array(String) | Semicolon format "DEAD::BEEF" |
17 | tor | String | Onion name |
19 | freenet | String | |
20 | alias | String | Nullifies other attributes |
21 | translate | String | Nullifies other attributes |
22 | email | String | Used in `SOA` |
23 | loc | String | Format suitable for `LOC` |
24 | info | JsonObj | Currently unspecified |
25 | ns | Array(String) | Domain names as in `NS` |
26 | delegate | String | Replaces current object |
27 | import | String | "Deep" merges into current obj. |
28 | map | Map(String:DomObj) | Tree of subdomain objects |
29 | fingerprint | Array(String) | |
30 | tls | Map(String:Map(String:Array(TlsObj))) | |
31 | ds | Array(DsObj) | |
35 * Any attribute specified as `Array(String)` may be present in the
36 JSON document as `String`, which is interpreted the same way as
37 an `Array` containing a single `String` element.
38 * In any place where `DomObj` is expected there may be a `String`, which
39 is interpreted as an IPv4 address. In other words, a string `"1.2.3.4"`
40 is interpreted the same way as the object `"{\"ip\":\"1.2.3.4\"}"`
41 Such "shorthand" DomObj can be present at the top level or as a value
42 in the `"map"` attribute.
46 `SrvObj` is a heterogenous Array of fixed size containing 6 elements:
48 | N | Type | Meaning |
49 |---|--------|----------|
50 | 0 | String | Service |
51 | 1 | String | Protocol |
52 | 2 | Int | Priority |
55 | 5 | String | Hostname |
59 * `Service` and `Protocol` are two elements of the domain name, without
61 * `SrvObj` with Service `"smtp"`, Protocol `"tcp"` and Port `25` is also
62 interpteted as an `MX` DNS respource.
63 * When lookup is performed for `SRV` records at fqdn
64 `"_serv._proto.sub.dom.bit"`, domain object for `"sub.dom.bit"` must be
65 fetched, and in this object, `SrvObj`s for the Service `"serv"` and
66 Protocol `"proto"` selected from it.
70 `TlsObj` is a heterogenous Array of fixed size containing 3 elements:
72 | N | Type | Meaning |
73 |---|--------|-------------------------------------------------------|
74 | 0 | Int | Match type - 0:Exact, 1:SHA-256, 2:SHA-512 |
75 | 1 | String | Match value - certificate or hash of it as hex string |
76 | 2 | Int | Include subdomains - 0:No, 1:Yes |
80 `DsObj` is a heterogenous Array of fixed size containing 4 elements:
82 | N | Type | Meaning |
83 |---|--------|--------------------------|
85 | 1 | Int | Key Algorithm |
86 | 2 | Int | Hash Type |
87 | 3 | String | Hash Value as hex string |
89 ## Data Interpretation
91 Assuming a query for a subdomain of a basedomain in the `.bit` TLD
92 (subdomain possibly being empty), lookup starts by fetching the
93 "base" object for basedomain. The domain object is then transformed
94 by the following sequece applied recursively:
96 1. Value of the element of the `"map"` attribute with the key `""`
97 (empty string) is recursively merged into the base domain. The
98 `""` element of the `"map"` is removed from the result.
99 2. If attribute `"import"` does not exist in the resulting object,
100 recursion stops, and step 3 is performed on the result
101 If attribute `"import"` exists in the resulting object, lookup is
102 is performed for the value of this attribute, and fetched object
103 is recursively merged into the base domain. The `"import"` attribute
104 is removed from the result. Then the result is passed as base
106 3. If subdomain chain is empty, recursion stops, and step 4 is
107 performed on the result. If subdomain chain is not empty, next
108 element is taken out of the chain, and the `"map"` is looked
109 up for the element with the name matching the subdomain element.
110 The value of this element of the `"map"` is passed as base domain
111 to step 1. If matching element does not exist, lookup is considered
113 4. Domain object with all `""` map elements and all `"import"` data
114 merged is "normalized" by removal of attributes that are nullified
115 by the presence of other attributes.
117 Note that the process involves recursion nested to three levels.
121 When a domain object `sub` needs merging into a domain object `base`,
122 the following rules are applied:
124 * Of `String` and other "scalar" attributes, one is chosen, the value
125 from the `base` taking precedence.
126 * On `Array` attribtes, `union` operation is performed. (Of equal
127 elements, only one copy is left.)
128 * On `Map` attributes, recursive merge is performed. On the top level,
129 elemens with keys that are only present in either `base` or `sub`
130 object are all put into result. The values of the elements that are
131 present in both `base` and `sub` are merged according to the rules
132 applicable to their type.