[Qemu-devel] [PATCH 5/5] qapi: Fix QMP spec references to JSON

[Eric Blake <eblake@redhat.com>]

I had assumed that 'id' of a command/return transaction could only
be an integer, and therefore that 'json-value' meant integer, so
I invented the term 'json-entity' to express a choice between
json-object, json-string, and json-array.  But in reality, the JSON
RFC defines json-value as the combination of all other types, and
the QMP parser currently accepts any JSON value that does not
include a literal JSON null.  So, clean up the docs to be consistent
with the RFC.  And while at it, use the newer version of the RFC.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/qmp/qmp-spec.txt | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/qmp/qmp-spec.txt b/docs/qmp/qmp-spec.txt
index 1fb642b..f7d8c30 100644
--- a/docs/qmp/qmp-spec.txt
+++ b/docs/qmp/qmp-spec.txt
@@ -28,10 +28,10 @@ following format:

     json-DATA-STRUCTURE-NAME

-Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by
-the JSON standard:
+Where DATA-STRUCTURE-NAME is any valid JSON data structure except the
+'null' literal, as defined by the JSON standard:

-http://www.ietf.org/rfc/rfc4627.txt
+http://www.ietf.org/rfc/rfc7159.txt

 For convenience, json-object members mentioned in this document will
 be in a certain order. However, in real protocol usage they can be in
@@ -92,7 +92,9 @@ The format for command execution is:
   execution of the command, it is optional when no arguments are required
 - The "id" member is a transaction identification associated with the
   command execution, it is optional and will be part of the response if
-  provided
+  provided. The "id" member can be any json-value that does not use a
+  json-null; however, most clients use a json-number incremented for
+  each successive command

 2.4 Commands Responses
 ----------------------
@@ -105,13 +107,13 @@ of a command execution: success or error.

 The format of a success response is:

-{ "return": json-entity, "id": json-value }
+{ "return": json-value, "id": json-value }

  Where,

 - The "return" member contains the data returned by the command, which
   is defined on a per-command basis (usually a json-object or
-  json-array of json-objects, but sometimes a json-value, json-string,
+  json-array of json-objects, but sometimes a json-number, json-string,
   or json-array of json-strings); it is an empty json-object if the
   command does not return data
 - The "id" member contains the transaction identification associated
-- 
2.1.0