Merge branch 'issues/88/variables_in_number_fields' into merge/pr98_p…

…r100

Domain Connect Spec Draft.adoc

@@ -65,6 +65,8 @@ DNS Providers and Service Providers to simplify this interaction across the inte
 [glossary]
 [toc=exclude]
 :sectnums!:
+[toc=exclude]
+:sectnums!:
 === Terminology
 
 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document are to be interpreted as described in BCP 14 <<RFC2119>> <<RFC8174>> when, and only when, they appear in all capitals, as shown here.
@@ -1514,7 +1516,7 @@ A template is defined as a standard JSON data structure containing the following
 |String
 |serviceId
 |(REQUIRED) The name or identifier of the template.
-This is used in URLs to identify the template. It is also used in the scope parameter for OAuth. It must not contain space characters, and must be URL friendly.
+This is used in URLs to identify the template. It is also used in the scope parameter for OAuth. It MUST NOT contain space characters, and must be URL friendly.
 
 |*Service Name*
 |String
@@ -1535,12 +1537,12 @@ If present this represents a version of the template and should be increased wit
 |*Description*
 |Text
 |description
-|(OPTIONAL) A textual description of what this template attempts to do. This is meant to assist developers and must not be displayed to the user.
+|(OPTIONAL) A textual description of what this template attempts to do. This is meant to assist developers and MUST NOT be displayed to the user.
 
 |*Variable Description*
 |Text
 |variableDescription
-|(OPTIONAL) A textual description of what the variables are. This is meant to assist developers and must not be displayed to the user.
+|(OPTIONAL) A textual description of what the variables are. This is meant to assist developers and MUST NOT be displayed to the user.
 
 |*Synchronous Block*
 |Boolean
@@ -1659,6 +1661,8 @@ Each record will contain the following elements.
 |enum
 |type
 |(REQUIRED) Describes the type of record in DNS, or the operation impacting DNS. +
+|type
+|(REQUIRED) Describes the type of record in DNS, or the operation impacting DNS. +
 
 Valid values include: A, AAAA, CNAME, MX, TXT, SRV, or SPFM. +
 The DNS provider MUST support the core set of records A, AAAA, CNAME, MX, TXT, SRV. +
@@ -1733,10 +1737,15 @@ The pointsTo location for A, AAAA, CNAME, NS and MX records. +
 A value of empty or @ indicates the host and domain name being applied or [host.]example.com +
 
 |*TTL*
-|Int
+|Int or string representation of Int
 |ttl
 |The time-to-live for the record in DNS. Valid
-for A, AAAA, CNAME, NS, TXT, MX, and SRV records. This must not contain variables.
+for A, AAAA, CNAME, NS, TXT, MX, and SRV records.
+In order to avoid operational unpredactibility of the template and the challenges outlined below this SHOULD NOT contain variables unless absolutely necessary. If it does, the variable MUST be included as string in the template definition to build a valid JSON and the variable MUST be the only value content. Prefixes, suffixes or multiple variables MUST NOT be used.
+
+This value, no matter if variable or constant, is understood as "best effort" by DNS provider and MAY be limited or adjusted by local policy at runtime or during template onboarding, like applying a certain minimum or maximum value of TTL or an enumeration of TTL values supported by the DNS provider. The DNS provider SHOULD NOT reject template application because of invalid value, rather pick the nearest supported value or a default, in order to avoid necessity of per provider adjustment to the application flow.
+
+Support of variables in this field is OPTIONAL for DNS Provider.
 
 |*Data*
 |String
@@ -1763,22 +1772,31 @@ None, All, or Prefix. The default value is None. <<record-types-conflicts, See b
 |String
 |txtConflictMatchingPrefix
 |The prefix to detect conflicts when txtConflict-MatchingMode is "Prefix". This
-must not contain variables. <<record-types-conflicts, See below>>.
+MUST NOT contain variables. <<record-types-conflicts, See below>>.
 
 |*Priority*
-|Int
+|Int or string representation of Int
 |priority
-|The priority for an MX or SRV record. This must not contain variables.
+|The priority for an MX or SRV record.
+This MAY contain variable but if it does the variable MUST be included as string in the template definition to build a valid JSON and the variable MUST be the only content of the value field. Prefixes, suffixes or multiple variables MUST NOT be used.
+
+Support of variables in this field is OPTIONAL for DNS Provider.
 
 |*Weight*
-|Int
+|Int or string representation of Int
 |weight
-|The weight for the SRV record. This must not contain variables.
+|The weight for the SRV record.
+This MAY contain variable but if it does the variable MUST be included as string in the template definition to build a valid JSON and the variable MUST be the only content of the value field. Prefixes, suffixes or multiple variables MUST NOT be used.
+
+Support of variables in this field is OPTIONAL for DNS Provider.
 
 |*Port*
-|Int
+|Int or string representation of Int
 |port
-|The port for the SRV record. This must not contain variables.
+|The port for the SRV record.
+This MAY contain variable but if it does the variable MUST be included as string in the template definition to build a valid JSON and the variable MUST be the only content of the value field. Prefixes, suffixes or multiple variables MUST NOT be used.
+
+Support of variables in this field is OPTIONAL for DNS Provider.
 
 |*Protocol*
 |String
@@ -1901,7 +1919,7 @@ template such a DNS Provider should remove the previously applied template on th
 This may not be desireable for all templates, as a limited set of templates are designed to
 be applied multiple times. To faciliate this the template can have the flag <<template-definition, multiInstance>>
 set. This tells the DNS Provider that the template is expected to be written multiple times
-and that a re-apply must not remove previous instances.
+and that a re-apply MUST NOT remove previous instances.
 
 This setting only impacts DNS Providers that maintain applied template state. DNS Providers
 that do not maintain applied template state must rely on the normal conflict
@@ -2171,7 +2189,7 @@ When a template is added or removed with an _SPFM_ record in the template, some
 
 DNS Provider SHOULD also allow the end user to modify the SPF record after merging.
 
-Due to merging step in between, the resulting SPF TXT records are considered non-essential (see: <<non-essential-record>>). That means the user may decide to override the final calculated value or remove the whole SPF record. This action must not lead to removal of any related templates in conflict detection and template integrity routines if implemented by the DNS provider.
+Due to merging step in between, the resulting SPF TXT records are considered non-essential (see: <<non-essential-record>>). That means the user may decide to override the final calculated value or remove the whole SPF record. This action MUST NOT lead to removal of any related templates in conflict detection and template integrity routines if implemented by the DNS provider.
 
 If the existing TXT record makes the merging operation not possible, the DNS provider must handle this situation the same way as a conflict and either let the end-user resolve it in the UX (both in Synchronous and Asynchronous flow) or return the conflict as an error in the Asynchronous flow unless the _force=true_ parameter is used, effectively removing the existing record.
 

exampleprovider.exampleservice.json

@@ -6,7 +6,7 @@
     "version": 1,
     "logoUrl": "https://example.com/logo.svg",
     "description": "Example description explaining overall purpose of the record updates",
-    "variableDescription": "%a%: domain apex IP; %sub%: sub record destination; %cnamehost%: host pointing to sub destination; %txt%: domain apex text; %mx%: domain apex mail destination; %target%: domain apex service record target",
+    "variableDescription": "%a%: domain apex IP; %sub%: sub record destination; %cnamehost%: host pointing to sub destination; %txt%: domain apex text; %mx%: domain apex mail destination; %target%: domain apex service record target; %ttlvar%: variable TTL for SRV record; %srvport%: variable port for SRV record; %srvproto%: variable ptotocol of SRV record; %srvservice%: variable service of SRV record",
     "syncPubKeyDomain": "syncPubKeyDomain",
     "syncRedirectDomain": "syncRedirectDomain",
     "warnPhishing": true,
@@ -65,7 +65,7 @@
             "host": "@",
             "pointsTo": "192.0.2.2",
             "ttl": 3600,
-            "priority": 10
+            "priority": "%mxprio%"
         },
         {
             "type": "SRV",
@@ -83,6 +83,17 @@
             "host": "@",
             "data": "0 issuewild \"ca2.example.\"",
             "ttl": 1800
+        },
+        {
+            "type": "SRV",
+            "name": "@",
+            "ttl": "%ttlvar%",
+            "priority": "0",
+            "weight": "20",
+            "port": "%srvport%",
+            "protocol": "%srvproto%",
+            "service": "_%srvservice%",
+            "target": "srv.example.com"
         }
     ]
 }

template.schema

@@ -1,5 +1,5 @@
 {
-   "$schema":"http://json-schema.org/draft-06/schema#",
+   "$schema": "http://json-schema.org/draft-07/schema#",
    "$ref":"#/definitions/DomainConnectTemplate",
    "definitions":{
       "DomainConnectTemplate":{
@@ -192,7 +192,7 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   }
                },
                "required":[
@@ -223,7 +223,7 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   }
                },
                "required":[
@@ -254,7 +254,7 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   }
                },
                "required":[
@@ -285,7 +285,7 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   }
                },
                "required":[
@@ -313,7 +313,7 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   },
                   "data":{
                      "type":"string"
@@ -359,7 +359,7 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   },
                   "data":{
                      "type":"string"
@@ -393,10 +393,10 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   },
                   "priority":{
-                     "type":"integer"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   }
                },
                "required":[
@@ -455,10 +455,10 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   },
                   "priority":{
-                     "type":"integer"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   },
                   "protocol":{
                      "type":"string"
@@ -467,10 +467,10 @@
                      "type":"string"
                   },
                   "weight":{
-                     "type":"integer"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   },
                   "port":{
-                     "type":"integer"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   }
                },
                "required":[
@@ -555,7 +555,7 @@
                      "type":"string"
                   },
                   "ttl":{
-                     "$ref":"#/definitions/TTL"
+                     "$ref":"#/definitions/Number_or_NumberInString_or_Variable"
                   }
                },
                "required":[
@@ -567,17 +567,21 @@
             }
          ]
       },
-      "TTL":{
-         "anyOf":[
+      "Number_or_NumberInString_or_Variable":{
+         "oneOf":[
             {
                "type":"integer"
             },
             {
                "type":"string",
-               "format":"integer"
+               "pattern":"\\d"
+            },
+            {
+               "type":"string",
+               "pattern":"%[^%]+%"
             }
          ],
-         "title":"TTL"
+         "title":"Number or Number as String or Variable as String"
       }
    }
 }