Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection

[Markus Armbruster]

Michael Roth <address@hidden> writes:

> Quoting Markus Armbruster (2015-09-03 12:01:20)
>> Michael Roth <address@hidden> writes:
>> 
>> > Quoting Eric Blake (2015-09-03 09:31:01)
>> >> On 09/03/2015 03:26 AM, Markus Armbruster wrote:
>> >> >>
>> >> >> I think we need to be careful that these descriptions are not
>> >> >> interpreted by clients as an alternative to the more-specific
>> >> >> constraints in the QAPI schema though. 'query-schema' seems
>> >> >> a bit misleading in that regard, it appears to be more like
>> >> >> 'query-schema-encoding' in function. But not sure it's worth
>> >> >> renaming or anything so long as the documentation is clear.
>> >> > 
>> >> > You have a point: "schema" can mean two related, yet different things.
>> >> > There's the QAPI schema, and there's the QMP (the wire protocol) schema.
>> >> > QMP introspection is about the latter, not the former.
>> >> > 
>> >> > If we want to avoid the ambiguity, we could call the command
>> >> > query-qmp-schema or something.
>> >> > 
>> >> > Renaming query-schema now might confuse people coming from my KVM Forum
>> >> > talk slightly, but if we can agree on a better name, let's do it.
>> >> 
>> >> I'm okay if you want to use 'query-qmp-schema'; it's a bit longer, but
>> >> more precise, and doesn't cause too much grief to change the name at
>> >> this point in the game.
>> >
>> > I'm also okay with this. It avoids confusion down that road if we
>> > ever introduced, say, a query-ber-schema or something.
>> >
>> > I have some minor reservations: I think query-qmp-schema-mapping or
>> > query-qmp-schema-encoding, i.e. "give me information on how the
>> > [QAPI] schema maps to the QMP wire protocol", is more correct.
>> > query-qmp-schema reads like "give me the complete schema for the
>> > QMP wire protocol", which makes it more tempting to treat the
>> > result as a complete schema, rather than a component of what's
>> > defined by the QAPI schema.
>> 
>> Well, it *is* the schema for the QMP wire protocol.  Which happens to be
>> mechanically derived from the QAPI schema.
>
> True, but the separation from QMP wire schema and QAPI interface schema
> wouldn't be clear to most users. It would be fairly tempting/reasonable
> for the author of a QMP client to assume the "QMP schema" was the
> definitive source for how a client should interact with QEMU without
> realizing or finding the need to reference the QAPI schema for more
> specific constraints (like integer ranges).

The constraints not expressed in the QMP schema generally aren't
expressed in the QAPI schema either, only its comments.

Nevertheless, I quite agree our documentation should refer readers to
the QAPI schema, because it's the source code, and as such it's written
for humans.  The value of query-qmp-schema is just for machines.

> I'm somewhat harping on this because that's exactly the misconception
> I had when I first looked at this series, which is why the loss of
> information like integer ranges didn't seem acceptable to me initially.
>
> But I don't really have a problem with query-qmp-schema, the naming
> comments are more a suggestion of the sort of confusion we should
> try to clear up in the accompanying documentation.
>
>> 
>> > But in all likelihood trying to cram all that information into the
>> > command name would probably just be confusing to most, so a simpler
>> > name with clear documentation seems reasonable.
>> 
>> I think query-qmp-schema hits the sweet spot between "ambiguous because
>> it's too short" and "too long because we tried to make it unambiguous".
>> I'll adopt it in v5.
>> 
>> Regarding clear documentation: we don't have to get it perfect in the
>> initial commit, but I'm of course happy to address review of RFC PATCH
>> v4 in v5.
>> 
>
> Thanks, sounds reasonable to me.

Okay, we got a plan.  Thanks!