Hi On Thu, Oct 22, 2026 at 6:04 PM Markus Armbruster <[email protected]> wrote: > > Marc-André's series evolves ObjectPropertyInfo and ObjectPropertyValue: > it adds member @qapi-type and changes many values of member @type. > > I'd like to take a step back and discuss design. I trimmed Cc: > accordingly. > > > = The current interface > > qom-list returns information on an object's properties, one > ObjectPropertyInfo per property. > > qom-list-properties returns information on properties an instance of a > type is known to have[*], one ObjectPropertyInfo per property. > > qom-list-get returns information on the properties of several objects, > one ObjectPropertyValue per property. > > ObjectPropertyInfo and ObjectPropertyValue provide @name and @type. > > ObjectPropertyInfo additionally provides @description and > @default-value, both optional. > > ObjectPropertyValue additionally provides optional @value, absent when > the property cannot be read. > > If ObjectPropertyValue was an extension of ObjectPropertyInfo, then > qom-list-get would be a strictly more powerful version of qom-list. > It isn't. However, I think the information lost when moving from > qom-list to qom-list-get is not useful: > > * @description is rarely present (I see under 15% in a quick test). The > description text is commonly misleading for QMP. For instance, qdev > bool properties have description "on/off". The possible values are > actually JSON false and true. > > * @default-value can be useful with qom-list-properties, which operates > on types. I doubt it is with qom-list, which operates on objects. > > Let's pretend @description doesn't exist, and @default-value exists only > with qom-list-properties. > > This makes qom-list-get strictly more powerful than qom-list, so let's > further pretend qom-list doesn't exist. > > > = Simplified interface for the sake of discussion > > qom-list-properties returns information on properties an instance of a > type is known to have[*]: @name, @type, and maybe @default-value. > > qom-list-get returns information on the properties of several objects: > @name, @type, and maybe @value. > > > = The meaning of @type > > Three cases: > > 1. For a child property (created with object_property_add_child() etc.), > @type is "child<T>", where T is the child's QOM type. > > 2. For a link property (created with object_class_property_add_link() > etc.), @type is "link<T>", where T is the target's QOM type. > > 3. For other properties, @type can be anything. We commonly use QAPI > type names (occasionally misspelled), and also "well-known" (but > undocumented) non-QAPI names for primitive types. Every now and > then, developers get lazy and use values like "list", or creative and > use values like "guest statistics". Nobody has gotten sufficiently > masochistic to use values starting with "child<" or "link<" so far, > although nothing would stop that. > > Cases 1 and 2 go against the QAPI/QMP design maxim "don't encode stuff > in strings". > > Case 3 is is hard to use for anything. You're forced into stupid and > brittle hardcoding. > > Marc-André's work adds a new optional member @qapi_type that refers to a > QAPI type in the output of query-qmp-schema. It's present for a large > subset of case 3. When it's present, @type should not be used. > > It also cleans up many crap cases of 3, but without making it robust. I > understand this isn't something the series tries to do, it's just > something that's easier to do than not to do. If it creates > compatibility problems, we have to not do it. I hope it doesn't. > > > = Can we do better? > > What information are we trying to convey? Four cases: > > 1. Child property: the child's QOM type > > 2. Link property: the target's QOM type > > 3. QAPI-backed property: the property's QAPI type > > 4. Other property: we have nothing useful to offer > > Case 4 should go away eventually. > > How would we encode this in QAPI on a green field? With a union, of > course: > > { 'enum': 'ObjectPropertyKind', > 'data': [ 'child', 'link', 'qapi', 'other'] } > > { 'struct': 'ObjectPropertyInfoLink', > 'data': { 'qom-type': 'str' } } > > { 'struct': 'ObjectPropertyInfoQAPI', > 'data': { 'qapi-type': 'str' } } > > { 'union': 'ObjectProperty...', > 'base': { 'kind': 'ObjectPropertyKind', > ... more ... }, > 'discriminator': 'kind', > 'data': { > 'child': 'ObjectPropertyInfoLink', > 'link': 'ObjectPropertyInfoLink', > 'qapi': 'ObjectPropertyInfoQAPI' } } > > To make this a compatible evolution of ObjectPropertyInfo, we need > ... more ... to be > > 'type': 'str', > '*description': 'str' > '*default-value': 'any', > > Sadly, we need to duplicate the union for ObjectPropertyValue. There, > ... more ... needs to be > > 'type': 'str', > '*value': 'any' > > We should deprecate @type. I'd also deprecate @description.
It's optional, I don't think that hurts. > Thoughts? I like it overall. But this goes beyond the intended scope of the series. Blending/merging QOM type & QAPI type would warrant more design research. So covering child<> & link<> are out of scope of the current qom-qapi series. I think the addition of qapi-type shouldn't be incompatible with a future proposal, after all all properties should have some 'wire' type (link/child are paths). But we can drop it for now or just rename it x-qapi-type until we agree on the new introspection. my2c
