expand spec doc
[pdns-pipe-nmc.git] / SPEC.md
1 % JSON Domain Format as Implemented by Pdns-Pipe-Nmc
2
3 ## Data Format
4
5 ### `DomObj` Object
6
7 `DomObj` either a `String` containing a dotted quad (see Note below),
8 or a JSON `Map`, with the following attributes, all optional:
9
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                                 |
16 | i2p         | I2pObj                                |                                            |
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)                          |                                            |
30
31 #### Notes:
32
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.
40
41 ### `SrvObj` Object
42
43 `SrvObj` is a heterogenous Array of fixed size containing 6 elements:
44
45 | N | Type   | Meaning  |
46 |---|--------|----------|
47 | 0 | String | Service  |
48 | 1 | String | Protocol |
49 | 2 | Int    | Priority |
50 | 3 | Int    | Weight   |
51 | 4 | Int    | Port     |
52 | 5 | String | Hostname |
53
54 #### Notes
55
56 * `Service` and `Protocol` are two elements of the domain name, without
57   the undescore '_'.
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.
64
65 ### `TlsObj` Object
66
67 `TlsObj` is a heterogenous Array of fixed size containing 3 elements:
68
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                      |
74
75 ### `DsObj` Object
76
77 `DsObj` is a heterogenous Array of fixed size containing 4 elements:
78
79 | N | Type   | Meaning                  |
80 |---|--------|--------------------------|
81 | 0 | Int    | Key Tag                  |
82 | 1 | Int    | Key Algorithm            |
83 | 2 | Int    | Hash Type                |
84 | 3 | String | Hash Value as hex string |
85
86 ## Data Interpretation
87
88 ### Semantics of the Attributes
89
90 ...FIXME
91
92 ### Lookup Sequence
93
94 Assuming a query is performed for
95 `sdN`++"."++{...}++"."++`sd2`++"."++`sd1`++"."++`dom`++".bit"
96 (`sdX` list possibly being empty), the lookup process starts by
97 querying the database for the object corresponding to `dom`.
98 Technically, it is easiest to populate a "seed" DomObj with a
99 single attribute `"import"` the value of which corresponds to the
100 `dom` name in the Namecoin namespace, which is `"d/" ++ dom`.
101 This domain object is then transformed by the following
102 recursive sequece:
103
104 1. Value of the element of the `"map"` attribute with the key `""`
105    (empty string) is recursively merged into the base domain. The
106    `""` element of the `"map"` is removed from the result.
107 2. If attribute `"import"` does not exist in the resulting object,
108    recursion stops, and step 3 is performed on the result
109    If attribute `"import"` exists in the resulting object, lookup is
110    is performed for the values of this attribute, and fetched objects
111    are recursively merged into the base domain. The `"import"` attribute
112    is removed from the result. Then the result is passed as base
113    domain to step 1.
114 3. If subdomain chain is empty, recursion stops, and step 4 is
115    performed on the result. If subdomain chain is not empty, next
116    element is taken out of the chain, and the `"map"` is looked
117    up for the element with the name matching the subdomain element.
118    The value of this element of the `"map"` is passed as base domain
119    to step 1. If matching element does not exist, lookup is considered
120    failed.
121 4. Domain object with all `""` map elements and all `"import"` data
122    merged is "normalized" by removal of attributes that are nullified
123    by the presence of other attributes.
124
125 Note that the process involves recursion nested to three levels.
126
127 ### Merging Procedure
128
129 When a domain object `sub` needs merging into a domain object `base`,
130 the following rules are applied:
131
132 * Of `String` and other "scalar" attributes, one is chosen, the value
133   from the `base` taking precedence.
134 * On `Array` attribtes, `union` operation is performed. (Of equal
135   elements, only one copy is left.)
136 * On `Map` attributes, recursive merge is performed. On the top level,
137   elemens with keys that are only present in either `base` or `sub`
138   object are all put into result. The values of the elements that are
139   present in both `base` and `sub` are merged according to the rules
140   applicable to their type.
141