spec: Handler key tree examples.

Co-authored-by: pancho horrillo <pedrofelipe.horrillo@bbva.com>

spec/README.md

@@ -114,8 +114,8 @@ behavior.
     information is the client code.  The client can thus use this information to
     control the program flow.
   * The JSON-encoded message.  The target audience in this case is the human
-    operating the client. The human can use this information to make a decision
-    on how to proceed.
+    operating the client.  The human can use this information to make a
+    decision on how to proceed.
 
 Let's illustrate these ideas with an example: TODO
 
@@ -329,16 +329,16 @@ following keys:
 │
 ├─ request               All information related to the HTTP request.  Read-Only
 │  ├──── method          Used HTTP Method (GET, POST)
-│  ├──── path            Complete URL path.
-│  ├──── match           Previously matched URL path parts.
+│  ├──── path            Complete URL path (URL-unquoted)
+│  ├──── matches         Previously matched URL path parts
 │  │     └──── <key>
-│  ├──── param           URL parameters (post ? symbol)
+│  ├──── params          URL parameters (post ? symbol)
 │  │     └──── <key>
-│  ├──── header          HTTP request headers
+│  ├──── headers         HTTP request headers
 │  │     └──── <key>
-│  ├──── cookie          HTTP request cookie
+│  ├──── cookies         HTTP request cookie
 │  │     └──── <key>
-│  ├──── form            form-encoding body data
+│  ├──── form            form-urlencoded form fields
 │  │     └──── <key>
 │  └──── body            HTTP request body
 │  
@@ -346,10 +346,67 @@ following keys:
    ├──── status          HTTP status code
    ├──── body            Response body.  Mutually exclusive with response/stream
    ├──── stream          Chunk-encoded body.  Streamed response.  Mutually exclusive with response/body
-   └──── header          HTTP response headers
+   └──── headers         HTTP response headers
          └──── <key>
 ```
 
+#### Example Keys
+
+1.
+  Scenario: Request URL is `http://localhost:8080/example?q=foo&r=bar`
+  Key: `/request/path`
+  Access: Read-Only
+  Returned Value: `/example?q=foo&r=bar`
+  Comment: That would provide read-only access to the request URL path.
+
+2. 
+  Scenario: Request URL is `http://localhost:8080/example?q=foo&r=bar`
+  Key: `/request/params/q`
+  Access: Read-Only
+  Returned Value: `foo`
+  Comment: That would provide read-only access to the request URL parameter `q`.
+
+3.
+  Scenario: A POST request with a JSON body and the header `Content-Type` set to `application/json`.
+  Key: `/request/headers/Content-Type`
+  Access: Read-Only
+  Returned Value: `application/json`
+  Comment: That would provide read-only access to the value of the request header `Content-Type`.
+
+4.
+  Scenario: A request generated by submitting this form:
+    ```
+    <form method="post">
+      First name:<br>
+      <input type="text" name="firstname" value="Jane"><br>
+      Last name:<br>
+      <input type="text" name="lastname" value="Doe">
+      <input type="submit" value="Submit">
+    </form>
+    ```
+  Key: `/request/form/firstname`
+  Access: Read-Only
+  Returned Value: `Jane`
+  Comment: That would provide read-only access to the value of the field `firstname` of the form.
+
+5.
+  Scenario: A request is being attended.
+  Key: `/response/status`
+  Access: Write-Only
+  Acceptable Value: A 3-digit integer.  Must match `[0-9]{3}`.
+  Default Value: 200
+  Comment: It is customary to use the HTTP status code as defined at [https://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1.1](RFC2616).
+
+6.
+  Scenario: A request is being attended.
+  Key: `/response/body`
+  Access: Write-Only
+  Acceptable Value: Any string of bytes.
+  Default Value: N/A
+  Comment: For media types other than `application/octet-stream` you should
+  specify the appropiate `Content-Type` header.
+
+
 **Note**: Parameters under `request` are read-only and, conversely, parameters under
 `response` are write-only.