From 9cdf03ec80c88e51fbcf0625b4f642fb8c6c4e1a Mon Sep 17 00:00:00 2001
From: Eugene Crosser <crosser@average.org>
Date: Mon, 21 Apr 2014 14:32:58 +0400
Subject: [PATCH] update spec doc, notably FQDN requirement

---
 SPEC.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/SPEC.md b/SPEC.md
index 138a75c..f464e11 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -1,5 +1,18 @@
 % JSON Domain Format as Implemented by Pdns-Pipe-Nmc
 
+This document is based on
+[Namecoin Domain Name Specification](https://wiki.namecoin.info/index.php?title=Domain_Name_Specification).
+It tries to follow it closely, and clarify parts that are not
+specified, or specified ambiguously, in the original document.
+
+One notable deviation is the specification of `"delegate"` and `"import"`
+attributes: domain objects to which their value point are
+replacing/merging to the domain object in which they are defined.
+This seems to be in line with at least one existing "real world"
+implementation.
+
+This specification is implemented by the `pdns-pipe-nmc` program.
+
 ## Data Format
 
 ### `DomObj` Object
@@ -51,7 +64,7 @@ or a JSON `Map`, with the following attributes, all optional:
 | 2 | Int    | Priority |
 | 3 | Int    | Weight   |
 | 4 | Int    | Port     |
-| 5 | String | Hostname |
+| 5 | String | FQDN     |
 
 #### Notes
 
@@ -108,8 +121,8 @@ two levels higher than the `SRV` record would. For example, a
 corresponding to the FQDN "sub.dom.bit" with the value
 
 ```
-"service": [ ["imap", "tcp", 0, 0, 143, "mail.host.com." ],
-             ["smtp", "tcp", 0, 0,  25, "relay.host.com."] ]
+"service": [ ["imap", "tcp", 0, 0, 143, "mail.host.com" ],
+             ["smtp", "tcp", 0, 0,  25, "relay.host.com"] ]
 ```
 
 corresponds to two `SRV` RRs at two different points in the
@@ -127,6 +140,13 @@ level:
 sub.dom.bit. IN MX 0 relay.host.com.
 ```
 
+Note: Hostname element **must** be specified as fully qualified domain
+name of the host, and **must not** terminate with a dot. 
+This requirement seems to be in line with many existing definitions in
+the blockchain; however it deviates from the BIND zone file format, in
+which names that have not terminating dot are automatically expanded
+by attaching the current origin zone to the end of the name.
+
 #### ip attribute
 
 Contains a list of strings representing IPv4 addresses in dotted
@@ -177,6 +197,9 @@ Translates into `CNAME` RR. Invalidates all other attributes except
 the element of the `"map"` with empty key. Such element is analysed
 and its contents merged into the base domain before the check.
 
+Note: Hostname element **must** be specified as fully qualified domain
+name of the host, and **must not** terminate with a dot. 
+
 #### translate attribute
 
 Translates into `DNAME` RR. Invalidates the contents of the `"map"`
@@ -206,6 +229,10 @@ Translates into `NS` RR. Invalidates all other attributes, except
 the element of the `"map"` with empty key. Such element is analysed
 and its contents merged into the base domain before the check.
 
+Note: the value of the attribute  **must** be specified as fully
+qualified domain name of the host, and **must not** terminate
+with a dot.
+
 #### delegate attribute
 
 Does not translate into any DNS RR. Instead, the value is used as
-- 
2.39.2