Add some simple docs for the LHS json path substitution.

So that there is some warning about quoting issues.

docs/source/format.rst

@@ -274,7 +274,8 @@ All of these variables may be used in all of the following fields:
 * ``data``
 * ``request_headers``
 * ``response_strings``
-* ``response_json_paths`` (on the value side of the key value pair)
+* ``response_json_paths`` (in both the key and value, see
+  :ref:`json path substitution <json-subs>` for more info)
 * ``response_headers`` (on the value side of the key value pair)
 * ``response_forbidden_headers``
 * ``count`` and ``delay`` fields of ``poll``

docs/source/jsonpath.rst

@@ -67,5 +67,30 @@ not just your API interactions.
 There are more JSONPath examples in :doc:`example` and in the
 `jsonpath_rw`_ and `jsonpath_rw_ext`_ documentation.
 
+.. _json-subs:
+
+Substitution
+------------
+
+:ref:`Substitutions <state-substitution>` can be made in both the
+left (query) and right (expected) hand sides of the json path
+expression. When subtitutions are used in the query, care must be
+taken to ensure proper quoting of the resulting value. For example
+if there is a uuid (with hyphens) at ``$RESPONSE['$.id']`` then this
+expression may fail::
+
+    $.nested.structure.$RESPONSE['$.id'].name: foobar
+
+as it will evaluate to something like::
+
+   $.nested.structure.ADC8AAFC-D564-40D1-9724-7680D3C010C2.name: foobar
+
+which may be treated as an arithemtic expression by the json path
+parser. The test author should write::
+
+    $.nested.structure["$RESPONSE['$.id']"].name: foobar
+
+to quote the result of the substitution.
+
 .. _jsonpath_rw: http://jsonpath-rw.readthedocs.io/en/latest/
 .. _jsonpath_rw_ext: https://python-jsonpath-rw-ext.readthedocs.io/en/latest/