Add examples demonstrating cached objects and index property

[ghost]

This is what I wrote in an email to Ykaterina. She suggested I include it in the spec:

EXAMPLE 1: In this example, thisObject is an element of theRun.requests. We know what array index it’s at (0) so thisObject.index isn’t required: it MAY be present. But if it’s present, it had better equal that array index.

{                                 # A run object
  "requests": [
    {                             # A request object: thisObject.
      "index": 0,                 # Optional.
      "protocol": "HTTP",
      "version": "1.1",
      "method": "GET",
      "target": "/some/resource",
      "headers": {
        "Host": "www.example.com"
      },
      ...
    }
  ],
  ...
}

EXAMPLE 2: In this example, thisObject is not an element of theRun.Request. Rather, it’s the value of theResult.request. And in this example, there is no “cached” object. That is, there is no object in theRun.requests that provides additional information for thisObject. In fact, in this example, theRun.requests doesn’t exist at all. All the information is inline in theResult.request. Since there is no cached object for thisObject, thisObject.index SHALL NOT be present.

{                                 # A run object
  "results": [
    {                             # A result object.
      "ruleId": "WEB1001",
      "request": {                # A request object: thisObject. It has no index property. There is no cached object.
        "protocol": "HTTP",
        "version": "1.1",
        "method": "GET",
        "target": "/some/resource",
        "headers": {
          "Host": "www.example.com"
        },
        ...
      },
      ...
    }
  ]
}

EXAMPLE 3: Finally, in this example, thisObject is again the value of theResult.request, not an element of theRun.requests. But in this case, there is a cached object, an element of theRun.requests that provides additional information for thisObject. thisObject provides only the target property. Since we need to populate the remaining properties of thisObject from the cached object, thisObject.index SHALL be present.

{                                 # A run object
  "requests": [
    {                             # A request object: the cached object.
      "protocol": "HTTP",
      "version": "1.1",
      "method": "GET",
      "headers": {
        "Host": "www.example.com"
      },
      ...
    }
  ],

  "results": [
    {                             # A result object.
      "ruleId": "WEB1001",
      "request": {                # A request object: thisObject. It has an index property...
        "index": "0",             # ... so it can get the missing properties from the cached object.
        "target": "/some/resource"
      },
      ...
    }
  ]
}