Ability to import datatype declarations from XSD files

[RCBiczok]

Dear OAS community,

foremost - thank you so much for this lovely invention that is Open API - I think every company I worked with not only embraced this, but also made significant improvements on their system landscape.

Now I reach out to you from a distant land that is called "Banking sector", where XML is still the hot shit. For instance, we are implementing new APIs that span between different national banks. We do the design part by sending XML Schema files around containing the desired message structure. It's also not an arbitrary approach, as the so-called ISO 20022 standard is the most widely exacted one and relies on XSD / XML messages.

Which brings me to my request: I would love to see a more extended roadmap to support XML and XML Schema in OpenAPI. Now I'm well aware that OpenAPI already has a concept called XML Object. However, in its current state, it does not support the most common use-cases. One issue that still persists is the inability to represent an XML element with textual content and attributes assigned to it (see OAI/OpenAPI-Specification#630). On top of that, current (national) banks would need to migrate away from using XML Schema Definitions to a JSON-based format to describe the data structures. This would make transitioning from XML world to JSON world more abrupt.

SUGGESTIONS: 1) Fix OAI/OpenAPI-Specification#630 2) Add the ability to reference data definitions from XSD files directly. We could use the $ref semantics for that:

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
               "$ref": "pet.ontology.xsd#//xs:complexType[@name='Pet']"
            }
          }
        }
      },
    }
  },
}

Everything before the '#' represents the target file to source from. This is just the same logic for JSON Schema declarations in JSON or YAML format. The part after the '#' is a XPath expression pointing to the type declaration to reference. The advantages of this approach would be:

• Reusability of existing XSD files - no rewrite needed.
• We don't have to write dedicated generators to support XML Object constructs - instead generators could just fallback to existing code generating tools (i.e. JAXB in the Java World)

The disadvantages of this approach would be:

• More complex handling with the $ref construct: It could be complicated to allow XSD references everywhere where $ref itself is allowed. This example, for instance, would be problematic:

  paths:
  /users:
    $ref: '../resources/users.xsd#//xs:complexType[@name='UserOperation']'

  However, we could avoid this by simply restricting the use of XSD references in $ref only to places where we want to declare content types.

• Internal conversion from XSD to JSON/YAML-Compatible intermediate might be necessary, depending on how the swagger-ui, generators actually resolve these $ref references.

What do you think?