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

[Michael Roth]

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

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.