wip move 'synthetic' parsing into NmcDom
[pdns-pipe-nmc.git] / SPEC.md
diff --git a/SPEC.md b/SPEC.md
index 5c659b75853cbed01c1c5f7611b8e1152c165383..4a0fb4ac7fdf82a890821236345580353d9b828e 100644 (file)
--- a/SPEC.md
+++ b/SPEC.md
@@ -17,8 +17,9 @@ This specification is implemented by the `pdns-pipe-nmc` program.
 
 ### `DomObj` Object
 
-`DomObj` either a `String` containing a dotted quad (see Note below),
-or a JSON `Map`, with the following attributes, all optional:
+`DomObj` is a data structure that is associated with an FQDN. It is
+either a `String` containing a dotted quad (see Note below), or a
+JSON `Map`, with the following attributes, all optional:
 
 | Key         | Type                                  | Comment                                    |
 |-------------|---------------------------------------|--------------------------------------------|
@@ -188,7 +189,7 @@ Does not translate into any DNS RR. Contains Tor hidden service address.
 
 #### i2p attribute
 
-Does not translate into any DNS RR. Contains an object with three
+Does not translate into any DNS RR. It is a JSON Map with three
 optional String attributes: `"destination"`, `"name"` and `"b32"`.
 
 ```
@@ -318,11 +319,32 @@ the empty element of the `"map"` has been recursively merged into
 the current object.
 
 ```
-"map": { "www": { "alias" : "www.example.com." }
+"map": { "www": { "alias" : "www.example.com" }
        , "www2": { "delegate": "d/example" }
        }
 ```
 
+Note: When a key contains dots ".", it is converted to a nested
+map.  If empty element appears as a result of split, such as when
+a dot is at the beginning or at the end of the key, or there are
+consequitive dots, such elemets are ignored. For example,
+
+```
+"map": { "www.uk": { "alias" : "www.example.co.uk" }
+       , "www..us": { "alias" : "www.example.com" }
+       , "smtp.us.": { "alias" : "smtp.example.com" }
+```
+
+is equivalent to
+
+```
+"map": { "uk": { "map": { "www": { "alias" : "www.example.co.uk" }}}
+       , "us": { "map": { "www": { "alias" : "www.example.com" }
+                        , "smtp": { "alias" : "smtp.example.com" }}
+               }
+       }
+```
+
 #### fingerprint attribute
 
 Does not translate into any DNS RR. Contains a list of TLS
@@ -343,6 +365,20 @@ Intended to carry attributes as per
        }
 ```
 
+translates into:
+
+```
+_443._tcp      TLSA  (3 0 1 660008F9...7621B787)
+_25._tcp       TLSA  (3 0 1 660008F9...7621B787)
+```
+
+The third element of the `TlsObj` heterogenous array is an extention
+to the DANE definition. Value `0` means that this rule is not enforced
+upon subdomains, value `1` means that it is enforced on subdomains.
+Rule defined inside a subdomain `DomObj` that specifies `0` on a rule
+existing in upper domain, that specifies `1` should be ignored. I.e.
+subdomain rule cannot revoke enforcement imposed by an upper domain rule.
+
 #### ds attribute
 
 Translates into `DS` RR. Carries attributes defined by