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 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.

> 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.