How to represent XML elements with attributes

[micovery]

Suppose I have the following XML:

<location>
  <coordinate format="lat-lon">a-b</coordinate>
</location>

I this the correct way to represent this using Swagger Schema objects?

---
  type: "object"
  xml: 
    name: "location"
  properties: 
    coordinate: 
      type: "string"
      properties: 
        format: 
          type: "string"
          xml: 
            attribute: true

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.

[webron]

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.

[ePaul]

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.

[micovery]

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 (http://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 xml field that Swagger came up with).

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.

[eminence]

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!

[ralfhandl]

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"

[AlskiOnTheWeb]

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!

[ralfhandl]

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.
Another obvious name would be text() - also no risk of clashing with an XML attribute name in someone's API out there.

[AlskiOnTheWeb]

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....

[ralfhandl]

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?

[dskow]

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 http://wiki.open311.org/JSON_and_XML_Conversion/

[MikeRalphson]

As we have the attribute property on the xml object already, perhaps it makes sense to add a text property (also of type boolean) to indicate that the property represents the xml text node, where at most only one property of an object SHOULD be marked text: true?

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>

[ronniedepriest]

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 (http://www.sklar.com/badgerfish/) convention for converting to json objects, per @micovery comment above.

[andygaga2018]

Hi
With MikeRalphson and ronniedepriest‘s comments, I just got something like this:
I could not remove the value tag, is there any good ideas?
<typeName href="example.com"> <value>SampleTypeName</value> </typeName>

[MikeRalphson]

@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.

[DinoChiesa]

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:

components:
  schemas:
    Person:
      type: object
      xml:
        namespace: http://example.com/schema/sample
      properties:
        id:
          type: integer
          format: int32
          xml:
            attribute: true
        name:
          type: string
          xml:
            namespace: http://example.com/schema/sample
      required:
        - name
        - id

allows this XML

<Person xmlns="http://example.com/schema/sample" id="0">
	<name>string</name>
</Person>