You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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:
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.
This discussion was converted from issue #123 on May 24, 2024 20:22.
Heading
Bold
Italic
Quote
Code
Link
Numbered list
Unordered list
Task list
Attach files
Mention
Reference
Menu
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
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:
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:
The disadvantages of this approach would be:
What do you think?
Beta Was this translation helpful? Give feedback.
All reactions