xml property and root schemas

This is a question about the specification, and the intent of the following description in the Schema Object, relating to the xml property:

This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property.

This has the effect of banning the construct

components:
  schemas:
    mySchema:
      type: object
      properties:
        a:
          type: string
      xml:
        name: xmlSchema

As a point-of-reference only, both swagger-ui and swagger-editor appear to honour this (useful) construct.

Is it possible to align the specification with real-world use for this case, and possibly move the restriction on xml properties on root schemas to those sub-properties (such as attribute and wrapped) where it seems to make sense?

[handrews]

@MikeRalphson JSON Schema 2019-09 has definitions for “schema document”, “schema resource”, “root schema”, “schema object”, and “subschema”. It shouldn’t be too hard to adapt that for the OAS situation of schema objects embedded in a non-schema document.

[hrennau]

It is helpful to be aware of the analogies between JSON Schema and XSD. What seems to be called here a “root schema” (if I understand the comments correctly) is named schemas, that is, the schemas contained by /components/schemas (V3) or /definitions (V2). They are equivalent to a named type definition in XSD. Such a type definition is used by element declarations or attribute declarations. The name of the item (corresponding to a JSON property name) is NEVER assigned by the type definition, always by the element/attribute declaration. These declarations are equivalent to the fields in a properties object. Like the name, also cardinality constraints can only be placed in those declarations, never in the types. Cardinality constraints are roughly equivalent to “required”, @fmvilas - hence we only have to look at XSD and understand the equivalences in order to have a clear idea what belongs where. (Not that we could not do it differently, but we should think very carefully before doing it, and be aware of the deliberate deviation.)

And because of this analogy, it makes sense to me to keep the xml keyword out of “root schemas” = named schemas (alias type definitions): property naming is not the business of the type used to constrain the property value. Arguments in favor of allowing xml there in the interest of code generation should be reviewed crititically - they would have to be very convincing.

There is a real issue with translation into XML, which is the necessity to insert an XML root node, for which there is no correspondence in JSON. Currently, OAS foresees no possibility to control the invented name, leaving the integration developer in the lurch.