Commit 1829851c authored by Paolo Bonzini's avatar Paolo Bonzini Committed by Luiz Capitulino
Browse files

qmp: document strict parsing

parent 6d36d7dc
Loading
Loading
Loading
Loading
+17 −3
Original line number Diff line number Diff line
@@ -209,13 +209,27 @@ incompatible way are disabled by default and will be advertised by the
capabilities array (section '2.2 Server Greeting'). Thus, Clients can check
that array and enable the capabilities they support.

Additionally, Clients must not assume any particular:

- Size of json-objects or length of json-arrays
The QMP Server performs a type check on the arguments to a command.  It
generates an error if a value does not have the expected type for its
key, or if it does not understand a key that the Client included.  The
strictness of the Server catches wrong assumptions of Clients about
the Server's schema.  Clients can assume that, when such validation
errors occur, they will be reported before the command generated any
side effect.

However, Clients must not assume any particular:

- Length of json-arrays
- Size of json-objects; in particular, future versions of QEMU may add
  new keys and Clients should be able to ignore them.
- Order of json-object members or json-array elements
- Amount of errors generated by a command, that is, new errors can be added
  to any existing command in newer versions of the Server

Of course, the Server does guarantee to send valid JSON.  But apart from
this, a Client should be "conservative in what they send, and liberal in
what they accept".

6. Downstream extension of QMP
------------------------------