Clarify scoping (fixes issue #5)

iay · Nov 27, 2013 · 54a654f · 54a654f
1 parent a6b2b12
commit 54a654f
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -1,17 +1,22 @@
-# Metadata Query Protocol Specification
+# Metadata Query Protocol Specifications
 
-This is the working area for the draft Metadata Query Protocol specification.
-The main directory contains the editor's working copy of the draft in its XML
+This is the working area for the draft Metadata Query Protocol specifications.
+The main directory contains the editor's working copy of the drafts in their XML
 and plain text forms.
 
-The document's current status in the IETF process can be viewed at
+The specification is broken into two parts, one for the base protocol and one
+for a SAML-specific profile.
+
+The protocol document's current status in the IETF process can be viewed at
 [its tracker page](https://datatracker.ietf.org/doc/draft-young-md-query/).
 The editor's working copy may be fresher, but less stable, than the most
 recent formally submitted Internet Draft.
 
 Prior versions submitted as Internet Drafts are also archived in the `history`
 directory here for quick comparison between versions.
 
+The SAML profile document has not yet been submitted as an Internet Draft.
+
 ## Terminology
 
 Please don't use the term "MDX" to refer to this specification or the protocol specified by it.  "MDX" as an acronym for MetaData eXchange refers to a more general concept of which the Metadata Query Protocol is just one component.
@@ -25,33 +30,42 @@ join the mailing list.  You can do this by means of
 [this webform](http://lists.iay.org.uk/listinfo.cgi/mdx-iay.org.uk)
 and then sending emails to [mdx@lists.iay.org.uk](mailto:mdx@lists.iay.org.uk).
 
-If you'd like to contribute specific text to the document, you can submit a 
+If you'd like to contribute specific text to the document, you can submit a
 ticket to the project's [issue tracker](https://github.com/iay/md-query/issues).
 GitHub pull requests are fine as well but are probably a bit of overkill here.
 
 Please don't use the GitHub issue tracking system for substantive discussion;
-that should always be done on the mailing list.  The issue tracker is used only to organize the outstanding substantive issues and to process minor editorial changes.
+that should always be done on the mailing list.  The issue tracker is used
+only to organize the outstanding substantive issues and to process minor
+editorial changes.
 
 ## Background
 
 This protocol work started out within the [Shibboleth](http://shibboleth.net)
-project.  The current Shibboleth products consume large SAML metadata 
-files that provide all the information necessary to communicate with peers.  
+project.  The current Shibboleth products consume large SAML metadata
+files that provide all the information necessary to communicate with peers.
 So, in some respects, SAML metadata files are like big `/etc/hosts` files.
 
 This model has some obvious scalability problems as the number of peers
 increases.  It also increases brittleness in the system because any erroneous
 metadata is visible to every consumer.
 The obvious solution then was to move to a more DNS-like model and
-this protocol is meant to be akin to the DNS query protocol.  So, some scoping
+this protocol is meant to be akin to the DNS query protocol, returning the
+information returned by a simple identifier lookup.  So, some scoping
 requirements are:
 
-* very simple protocol - we don't want 100 different options that end up behaving in strange ways when used together
-* metadata format agnostic - we started with SAML metadata but it shouldn't be the only format we support
-* good net citizen - we need to work well with proxies, caching infrastructure, etc.
+* simple protocol &mdash; we don't want numerous options which end up behaving in strange ways when used together
+* simple semantics &mdash; we don't need a sophisticated query language for the intended use cases
+* metadata format agnostic &mdash; we started with SAML metadata but it shouldn't be the only format we support
+* good net citizen &mdash; we need to work well with proxies, caching infrastructure, etc.
 
 ## Building the Documents
 
-The canonical source of the document is the `.xml` source file.  The repository always includes that form plus `.txt` versions.  Submission to the IETF datatracker requires the `.txt` version but I always supply the `.xml` as well.
+The canonical source of the document is the `.xml` source file.  The
+repository always includes that form plus `.txt` versions rendered from the
+XML.  Submission to the IETF datatracker requires the `.txt` version but I
+always supply the `.xml` as well.
 
-I'm using the included `Makefile` to build the HTML and text forms of the document.  This requires a locally installed copy of the `xml2rfc` tool.  An [online version](http://xml.resource.org) of `xml2rfc` is also available.
+I'm using the included `Makefile` to build the HTML and text forms of the
+document.  This requires a locally installed copy of the `xml2rfc` tool.  An
+[online version](http://xml.resource.org) of `xml2rfc` is also available.
diff --git a/draft-young-md-query.xml b/draft-young-md-query.xml
@@ -22,13 +22,18 @@
         <keyword>web service</keyword>
 
         <abstract>
-            <t>This document defines a simple protocol for retrieving metadata about entities.  The goal of the protocol is to profile various aspects of HTTP to allow requesters to rely on certain, rigorously defined, behaviour.</t>
+            <t>
+                This document defines a simple protocol for retrieving metadata about named entities, or named
+                collections of entities.
+                The goal of the protocol is to profile various aspects of HTTP to allow requesters to rely on
+                certain, rigorously defined, behaviour.
+            </t>
         </abstract>
     </front>
 
     <middle>
         <section title="Introduction">
-            <t>Many clients of web-based services are capable of consuming descriptive metadata about a service in order to customize or information the client's connection parameters.  While the form of the metadata (e.g., JSON, XML) and content varies between services this document attempts to specifies a set of semantics for <xref target="RFC2616">HTTP</xref> that allow clients to rely on certain behavior.  The defined behavior is meant to make it easy for clients to perform queries, to be efficient for both requesters and responders, and to allow the responder to scale in various ways.</t>
+            <t>Many clients of web-based services are capable of consuming descriptive metadata about a service in order to customize or information the client's connection parameters.  While the form of the metadata (e.g., JSON, XML) and content varies between services this document specifies a set of semantics for <xref target="RFC2616">HTTP</xref> that allow clients to rely on certain behavior.  The defined behavior is meant to make it easy for clients to perform queries, to be efficient for both requesters and responders, and to allow the responder to scale in various ways.</t>
 
             <section title="Notation and Conventions">
                 <t>
@@ -46,7 +51,7 @@
                     <list>
                         <t>entity - A single logical construct for which metadata may be asserted. Generally this is a network accessible service.</t>
                         <t>metadata - A machine readable description of certain entity characteristics. Generally metadata provides information such as end point references, service contact information, etc.</t>
-                    </list>                    
+                    </list>
                 </t>
             </section>
         </section>
@@ -91,7 +96,7 @@
                     </list>
                 </t>
                 <t>
-                    A metadata request to the same URL, after an initial request, MUST include the following header per section 13.3.4 of <xref target="RFC2616">RFC 2616</xref>: 
+                    A metadata request to the same URL, after an initial request, MUST include the following header per section 13.3.4 of <xref target="RFC2616">RFC 2616</xref>:
                     <list>
                         <t>If-None-Match</t>
                     </list>
@@ -107,7 +112,7 @@
                     </list>
                 </t>
                 <t>
-                    All metadata retrieval responses SHOULD include the following headers: 
+                    All metadata retrieval responses SHOULD include the following headers:
                     <list>
                         <t>Cache-Control</t>
                         <t>Content-Length</t>
@@ -117,7 +122,7 @@
             </section>
             <section title="Status Codes">
                 <t>
-                    This protocol uses the following HTTP status codes: 
+                    This protocol uses the following HTTP status codes:
                     <list>
                         <t>200 - standard response code when returning requested metadata</t>
                         <t>304 - response code indicating requested metadata has not been updated since the last request</t>
@@ -286,7 +291,7 @@ Content-Length: 1234
 
         <section title="Security Considerations" anchor="sec_cons">
             <section title="Integrity">
-                <t>As metadata often contains information necessary for the secure operation of interacting services it is RECOMMENDED that some form of content integrity checking be performed. This may include the use of SSL/TLS at the transport layer, digital signatures present within the metadata document, or any other such mechanism.</t>                
+                <t>As metadata often contains information necessary for the secure operation of interacting services it is RECOMMENDED that some form of content integrity checking be performed. This may include the use of SSL/TLS at the transport layer, digital signatures present within the metadata document, or any other such mechanism.</t>
             </section>
             <section title="Confidentiality">
                 <t>In many cases service metadata is public information and therefore confidentiality is not required.  In the cases where such functionality is required, it is RECOMMENDED that both the requester and responder support SSL/TLS.  Other mechanisms, such as XML encryption, MAY also be supported.</t>