diff --git a/Domain Connect Spec Draft.adoc b/Domain Connect Spec Draft.adoc index 4137469..ea3c973 100644 --- a/Domain Connect Spec Draft.adoc +++ b/Domain Connect Spec Draft.adoc @@ -71,7 +71,7 @@ The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "* Service Providers:: refers to entities that provide products and services attached to domain names. Examples include web hosting providers (such as Wix or SquareSpace), email Service Providers (such as -Microsoft or Google) and potentially even hardware manufacturers with +Microsoft or Google), and potentially even hardware manufacturers with DNS-enabled devices like home routers or automation controls (such as Linksys, Nest, and Philips). @@ -89,7 +89,7 @@ Templates/Service Templates:: refers to a file that describes a set of changes to DNS and domain functionality to enable a specific service. Public Template Repository:: refers to a public repository of Templates -in a standarised format (read more: <>). +in a standardised format (read more: <>). Root Domain:: refers to a registered domain (e.g. example.com or example.co.uk), or to a delegated zone in DNS. @@ -111,7 +111,7 @@ DNS. Once the Service Provider discovered the DNS Provider, they typically gave the customer instructions for proper configuration of DNS. This -might include help text, screen shots, or even links to the appropriate +might include help text, screenshots, or even links to the appropriate tools. Discovery of the DNS Provider in this manner is unreliable, and @@ -204,7 +204,7 @@ first is a synchronous web flow, and the second is an asynchronous flow using oAuth and an API. It is noted that a DNS Provider may choose to only implement one -of the flows. As a matter of practice many Service Providers are based +of the flows. As a matter of practice, many Service Providers are based on the synchronous flow, with only a handful of them based on the asynchronous oAuth flow. So many DNS providers may opt to only implement the synchronous flow. @@ -271,7 +271,7 @@ After clicking the link, the user is directed to a browser window on the DNS Provider’s site. This may be done in another tab or in a new browser window, but may also be an in place navigation with a return url. This link passes the domain name being modified, the service -provider/template being enabled, and any additional parameters (variables) +provider/template to be enabled, and any additional parameters (variables) needed to apply the template and configure the service. Once at the DNS Provider site, the user is asked to authenticate @@ -501,7 +501,7 @@ Service Providers since DNS changes may be different for an apex zone vs. a sub-domain for an individual service. The Service Provider must handle the condition when a query for the -_domainconnect TXT record suceeds, but a call to query for the JSON fails. +_domainconnect TXT record succeeds, but a call to query for the JSON fails. This can happen if the zone is hosted with another DNS Provider, but contains an incorrect _domainconnect TXT record. @@ -655,7 +655,7 @@ It is unlikely that the DNS Provider would want to leak this information to the Service Provider, and as such the description may be vague. + There is one piece of information that may be interesting to communicate -to the Service Provider. This is when the end user decided to cancel the +to the Service Provider. This is when the end user decides to cancel the operation. If the DNS Provider wishes to communicate this to the Service Provider, when the error=access_denied the error_description may contain the prefix "user_cancel". Again, this is left to the discretion @@ -921,7 +921,7 @@ the DNS Provider is closed. When the redirect_uri is used and an error is not present in the URI, the Service Provider can not assume the changes were applied to DNS. While true in most circumstances, users can tamper with or alter the return -url in the browser. As such it is recommend that enablement of a service +url in the browser. As such it is recommended that enablement of a service be based on verification of changes to DNS. === Asynchronous Flow: OAuth @@ -973,7 +973,7 @@ This endpoint is similar to the synchronous flow described above. The DNS Provid must authenticate the user, verify the user has control of the DNS Zone for the domain, and ask the user for permission. Instead of permission to make a change to DNS, the permission is now to allow the Service Provider to -make the changes on their behalf. Similarly the +make the changes on their behalf. Similarly, the DNS Provider may warn the user that (the eventual) application of a template might change existing records and/or disrupt existing services attached to the domain. @@ -1468,9 +1468,9 @@ domain. |*InstanceId* |instanceId |(OPTIONAL) Only applicable to templates supporting multiple instances -(see <> template property). For DNS Provider -storing information about applied templates allows removal of single instance -of template. If missing all instances of template should be removed. +(see <> template property). For DNS Providers +storing information about applied templates, this allows removal of a single template instance +which was applied with provided InstanceId. If omitted all instances of template MUST be removed. |======================================================================= @@ -1566,7 +1566,7 @@ This flag has been deprecated. It used to indicate that the template allowed a d |Boolean |sharedProviderName |(OPTIONAL) -This flag indicates that the template allows the caller to pass in additional information for the providerName. This information should augment the display of the providerName from the template. The default for this is false. For backward compatability with DNS Providers not at V2.2 of the spec it is recommended that the shared flag also be set. +This flag indicates that the template allows the caller to pass in additional information for the providerName. This information should augment the display of the providerName from the template. The default for this is false. For backward compatibility with DNS Providers not at V2.2 of the spec it is recommended that the shared flag also be set. |*Shared Service Name* |Boolean @@ -1877,7 +1877,7 @@ records that would be deleted or overwritten. This could be progressively disclo Conflict detection done by the DNS provider prior to template application has to take into consideration specifics of each DNS record type. The rules outlined below ensure predictable conflict resolution between DNS providers. Each rule applies to -the records on the very same host, unless specifed otherwise. +the records on the very same host, unless specified otherwise. * CNAME record conflicts with TXT, MX, AAAA, A and existing CNAME records, and any other records of these types conflict with an existing CNAME record. Note: CNAME records cannot be at the root of the zone. @@ -1902,8 +1902,8 @@ template when re-applying a template. To avoid unnecessary conflict warnings to the user, under normal use when re-applying a template such a DNS Provider should remove the previously applied template on the same host. -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 <> +This may not be desirable for all templates, as a limited set of templates are designed to +be applied multiple times. To facilitate this the template can have the flag <> 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.