-document use of xquery for filtering for approximate queries, fixes #7142; other minor edits/clarifications

1 files changed, 23 insertions, 16 deletions

diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index db465f7..eb62dce 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -325,12 +325,15 @@ Connectivity | |Underlay|  |Underlay|
             Any combination of options as defined in <xref target="route_options"/>
             may be specified.
           </dd>
-          <dt>Extended-Query:</dt>
+          <dt>eXtended-Query:</dt>
           <dd>
-            is extended query medatadata which may be
+            is extended query (XQuery) medatadata which may be
             required depending on the respective <tt>Block-Type</tt>.
             A <tt>Block-Type</tt> must define if the <tt>XQuery</tt> can or must
             be used and what the specific format of its contents should be.
+            Extended queries are in general used to implement domain-specific filters.
+            These might be particularly useful in combination with approximate queries.
+            Regardless, the DHT does not define any particular semantics for an XQuery.
             See also <xref target="blockstorage"/>.
           </dd>
           <dt>Result-Filter:</dt>
@@ -1107,7 +1110,7 @@ Connectivity | |Underlay|  |Underlay|
             </dd>
             <dt>XQ_SIZE</dt>
             <dd>
-              is a 32-bit number indicating the length of the optional
+              is a 16-bit number indicating the length of the optional
               extended query XQUERY. In network byte order.
             </dd>
             <dt>PEER_BF</dt>
@@ -1150,9 +1153,10 @@ Connectivity | |Underlay|  |Underlay|
               against the
               requested <tt>BTYPE</tt> as defined by its respective
               <tt>ValidateBlockQuery</tt> procedure.
-              If the <tt>BTYPE</tt> is not supported, or if the block key
-              does not match or if the <tt>XQUERY</tt> is malformed,
-              the message <bcp14>MUST</bcp14> be discarded.
+              If the <tt>BTYPE</tt> is not supported, the message <bcp14>MUST</bcp14>
+              be forwarded without query validation.
+              However, If the <tt>BTYPE</tt> is supported and the <tt>XQUERY</tt>
+              is malformed, the message <bcp14>MUST</bcp14> be discarded.
             </li>
             <li>
               The peer address of the sender peer <tt>P</tt> <bcp14>SHOULD</bcp14> be in the
@@ -1330,24 +1334,27 @@ Connectivity | |Underlay|  |Underlay|
             </li>
             <li>
               If the <tt>QUERY_HASH</tt> of this <tt>ResultMessage</tt> is found in the
-              list of pending local queries, the <tt>QUERY_HASH</tt> and <tt>XQUERY</tt>
-              are validated against the requested BTYPE using the respective
+              list of pending local queries and the BTYPE is supported, then
+              the <tt>QUERY_HASH</tt> and <tt>XQUERY</tt>
+              <bcp14>MUST</bcp14> be validated against the requested BTYPE using the respective
               block type implementation of <tt>ValidateBlockReply</tt>.
-              If the approximate flag is set and the BTYPE allows the
-              implementation to compute the key from the block it must match
-              the QUERY_HASH. If the XQUERY is malformed, the message <bcp14>MUST</bcp14> be discarded.
-              <!-- FIXME: This should be reviewed.
-              <= approximate flag -->
+              If the approximate flag was not set in the query and the BTYPE allows the
+              implementation to compute the key from the block, the computed key <bcp14>MUST</bcp14> match
+              the QUERY_HASH. If there is a mismatch, the message <bcp14>MUST</bcp14> be discarded.
             </li>
             <li>
-              The implementation <bcp14>MAY</bcp14> cache RESULT messages.
+              The implementation <bcp14>SHOULD</bcp14> cache RESULT messages
+              if the DemultiplexEverywhere flag was set on the query.
             </li>
             <li>
               <t>
                 If requests by other peers for this QUERY_HASH or BTYPE are
                 known,
                 the result block is validated against each request using
-                the respective <tt>ValidateBlockReply</tt> function.
+                the respective <tt>ValidateBlockReply</tt> function.  If
+                the BTYPE is not supported, filtering by the result Bloom
+                filter <bcp14>MUST</bcp14> still be performed.
+                <!-- FIXME-CG: check that it can be! Check implementation! -->
               </t>
               <t>
                 If the request options include <tt>FindApproximate</tt> and the result
@@ -1416,7 +1423,7 @@ Connectivity | |Underlay|  |Underlay|
             <dt>RESULT_INVALID</dt>
             <dd>Invalid result. Block does not match query. Value = 4.</dd>
             <dt>RESULT_IRRELEVANT</dt>
-            <dd>Block does not match xquery. Valid result, but not relevant for the request.</dd>
+            <dd>Block does not match XQuery. Valid result, but not relevant for the request.</dd>
           </dl>
         </section>
         <section anchor="block_functions">