-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
How to represent XML elements with attributes #630
Comments
When it comes to pure json schema, that's actually not illegal, but the properties, when it comes to json, would be effectively ignored. As for the answer to your actual question - there's pretty much no way to represent that currently with 2.0. The attributes can pretty much be applied only to objects. |
Nice idea. I guess Swagger/OpenAPI can not describe many types of XML, just those that have an obvious 1:1 mapping to JSON which can be described by OpenAPI itself. As there is no JSON equivalent to your XML fragment, it can't be described with Swagger either. |
Thanks @webron and @ePaul for the clarifications. That's correct, my sample XML has no way of being represented as JSON ... unless you adopt some convention like BadgerFish (https://www.sklar.com/badgerfish/) where it would be represented like this: {
"location": {
"coordinate": {
"@format": "lat-lon",
"$": "a-b",
}
}
} (which itself could be described purely by JSON Schema without resorting to using the But, putting that aside ... since it's not illegal (as @webron pointed out) in JSON-Schema-Draft-V4 for a string to have properties ... OpenAPI could accept it as a valid schema to describe XML ... just a matter of convention. |
This is primarily a problem when you are trying to use swagger to document an already existing API (that is, an API that you can't change). Which is a pretty big bummer! |
This could be solved by adding the convention to OpenAPI 3.0 that the text node of an XML element is represented as a property whose name is the empty string: type: "object"
xml:
name: "location"
properties:
coordinate:
type: "object"
properties:
format:
type: "string"
xml:
attribute: true
"":
type: "string" |
Oh man! If that's the type of hacking we can expect in this spec for 3.0, then I'd consider it a failure. A property whose name is an empty string? Really? That's intentional / by design? I can hear the death knell for Swagger now! |
Any reserved property name that cannot be mistaken for an XML attribute name would do the trick, the empty name is just the shortest possible choice. |
Ugh. The hacking shows the lack for forethought that went into this stuff. If Swagger / OpenAPI were designed from the get go to be suitably generic, these hacks wouldn't be needed. It's like the nasty "discriminator" hack to make things look hierarchical through some messed up definition. It's no wonder adoption for existing APIs is so low for this stuff.... |
I assume Swagger / OpenAPI was primarily invented for describing APIs that use the JSON format, and I think it does a great job in that area. Unfortunately its JSON-Schema-based payload description syntax only supports a subset of XML, and the most prominent gap is XML elements with text content. @AlskiOnTheWeb how would you address this gap? |
I have seen many javascript webpages use _ prefix in json to denote an attribute and __ prefix to denote inner text. Also I found this on the web https://wiki.open311.org/JSON_and_XML_Conversion/ |
As we have the Thus location:
type: "object"
properties:
coordinate:
type: "object"
properties:
format:
type: "string"
xml:
attribute: true
value:
type: "string"
xml:
text: true would represent the xml <location>
<coordinate format="lat-lon">a-b</coordinate>
</location> |
I inadvertantly added another bug here: #2624 I would also like to suggest a similar solution as @MikeRalphson, with 1 possible tweek: TypeName:
type: "object"
properties:
href:
type: "string"
example: "example.com"
xml:
attribute: true
value:
type: "string"
example: "SampleTypeName"
xml:
wrapped: "false"
xml:
name: "typeName" Which would produce: <typeName href="example.com">SampleTypeName</typeName> Like wise, we're also using the (https://www.sklar.com/badgerfish/) convention for converting to json objects, per @micovery comment above. |
Hi |
@andygaga2018 to make things clear, both of the examples above are proposals for future versions of the OpenAPI Specification. They won't work today in any existing tools. |
Not sure if that made things completely clear. Let me add: the xml/attribute flag is available in OpenAPI Spec 3.0.0. This schema:
allows this XML
|
I stumbled upon this issue today. I guess the problem is not with the attributes - they work fine, the problem is with objects that have both attributes and a value. Maybe the title of the issue could be rephrased to indicate that? Solution wise.. I'm +1 on How should we move this forward? |
Describing non-object elements with attributes such as |
How to represent below xml in swagger 2.0? |
has this issue been resolved ?? I don't see any mention of it in 3.0.2 release notes |
The issue is still open / unresolved. As per our development guide, it isn't the kind of thing which can be changed in a patch release. |
This worked for me: "geolocation": { And this is the contents of the referenced file: { |
Is this going to be addressed in future OpenAPI specifications? eg 3.1 or 4.0? |
With 3.1 being almost ready, it's unlikely to make it in. Based on work that has been done the last couple of years, I suspect it's more likely we'll see support for other schemas (such as XSD) rather than trying to resolve this issue, but time will tell. |
It's sad to see how an issue has been neglected for 4 years and counting. :( |
4 years and counting for sure...and it won't end either since the spec itself is fundamentally flawed. The hens have come to roost for this problem, what went around came around. Poor design / poor result. Garbage in / Garbage out. |
That helps in the sense that we have well documented XSDs already. In JSON Schema I'm missing mixed node support, enum content description support, support for <xs:attributeGroup ref="..."/>, support for $ref + a tweak, like deprecating the calling property or supplying a new default (cannot use anything next to $ref according to the validators), and then some like comment(). The downside is having to maintain 2 schemas. The notion of one schema to rule them all was fun while it lasted I guess. |
Just a note that JSON Schema draft 2020-12 (which will be referenced by OAS 3.1) does support some of these constructs, such as Depending on the appetite for alternative-schema support, there could be room for |
I found this thread while trying to figure out how to add an XML attribute to what would be an array in the JSON definition. e.g. something like the
It does not look like that is currently possible, so i wanted to make sure this use-case is also on your radar. |
Stuck with this issue too! |
Is there any workaround to do it in dot net core ISchemaFilter. Inner text example value not showing in swager openAPI schema.
if (property.Key == "totalQuantity")
} |
this work around does not work - it generates |
Try this:
in pom.xml add import:
And create this file in namespase com.example.iso20022.http.v1.schema.AmountMoreZero:
|
The proposed solution below looks good.
|
+1 |
2 similar comments
+1 |
+1 |
Temporary hack/workaround for small use cases with Gradle and Java Spring: Consider this definition:
and desired
Put to gradle build file:
|
Possible workaround by adding |
+1 |
re: this statement in the proposed solution.
Just pointing out, it is legal and valid in XML to have multiple text children of an element. This is valid: <location>
<coordinate format='a'> sometext <value>V</value> other-text </coordinate>
</location> If the proposal is implemented, then it will work for the simple case with 1 text node, but won't allow specifying an interface that allows multiple text nodes. That's ok with me; I don't see a reason to use that kind of structure in an API interface. But it should be noted. |
On the question around supporting XML elements with multiple text nodes, As a note, we're approaching the badgerfish convention. I sort of developed an extended version of it, maybe it could help the conversation https://jam01.github.io/xtrasonnet/dataformats/xml/#extended |
Suppose I have the following XML:
I this the correct way to represent this using Swagger Schema objects?
It seems weird for the "coordinate" property ... which itself is of type "string" to contain a "properties" field. Coming from JSON-Schema-Draft-V4 background, you would not expect a "string" field to have properties, because there is no such thing in JSON.
But then again, this is a "Swagger Schema Object" ... not a JSON-Schema-Draft-V4. I just want confirmation whether or not this is the correct way to do it.
The text was updated successfully, but these errors were encountered: