Add support for for xml schema as a model definition

[jahlborn]

I'm looking for a way to provide metadata for a REST webservice, and swagger is currently my leading choice. The biggest missing feature (for me) is the ability to use xml schema to describe a model. i understand this is potentially a large feature. even if it may not be added anytime soon, it would be great if there was at least a rough "proposal" for a good way that the current spec could be modified to support xml schema.

[jahlborn]

Based on some feedback from the forum here ( https://groups.google.com/forum/#!topic/swagger-swaggersocket/hofujwEY6TY ), I will try to flush this out a little more.

Basically, swagger currently supports a limited sub-set of JSON Schema for describing models. The documentation alludes to the idea that you can use this to describe XML content as well as JSON content, but this only works in the simplest situation. The most obvious missing features would be the ability to describe XML attributes and XML namespaces. XML Schema, however, has the ability to describe most any reasonable XML structure (as well as plenty of unreasonable ones) and has extensive tooling support in a wide variety of languages, frameworks, and runtimes at this point in time. While swagger seems to have some good marketplace traction already, adding this support would allow swagger to branch out into a much wider variety of APIs, especially many existing APIs which already make extensive use of XML.

While even just the ability to embed XML Schema would be nice, similar to issue #58 , it would be even better to be able to reference external schema documents (both JSON and XML Schema).

So, ultimately, if all my dreams came true, i would see this issue resulting in:

• The ability to define a Model using either JSON Schema or XML Schema (inline)
• The ability to define a Model using a url which refers to an external JSON Schema or XML Schema document

[webron]

In Swagger 2.0, we've added support to finely define the translation to XMLs - https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#xmlObject.

[nize]

I am not sure I understand the spec, but to me it seems as you still can't reference XML Schema elements or types from your swagger spec. This would be a handy feature since you may have XML Schemas which you would like to reuse when you specify your API using swagger.

[webron]

That is correct. You cannot use XML schema to declare your models.

[ulaBLUE]

Hi Ron,
I'm new to Swagger and would like to know if this still the case with new versions ? i.e can we use XML schema to define models ? Thanks.

[ePaul]

@ulaBLUE OpenAPI.next (what will become OpenAPI 3.0) is likely not to support other ways of defining schemas than the built-in schema language.

#764 proposed to allow schemas of different types, but this was withdrawn due to this being impossible to implement.

[rhyde]

This is very unfortunate that there appears to be no interest in being compatible with existing standards.

[darrelmiller]

@rhyde It is unfortunate that you have got that impression. Fortunately it is an inaccurate impression. We care very deeply about being compatible with existing standards. We also care about ensuring that tooling that implements the OpenAPI spec provides a consistent experience for users. Supporting schemas other than JSON Schema is something that many of us in the OpenAPI community want to be able to do. However, we need to do it in a way that meets all of our other goals and objectives. We were not able to do that in the V3 timeline. We definitely will be re-addressing this issue as we move forward and we look forward to your input and feedback on this important feature.

[sendtonirav]

Is there a tool that lets you automatically and reliably convert the XML schema (XSD) to the swagger supported JSON schema? Atleast that way I am managing one schema and then just auto converting it to the supported format?

[MikeRalphson]

From this stackoverflow answer there are a few options mentioned.

A tool I wrote called jgeXml has a module for converting XSD to JSON schema (and particularly OpenAPI-flavour JSON schema). It isn't an exact 1:1 conversion, though it has been used to convert a complex 1,700+ line XML schema to build valid OpenAPI 2.0 schema objects, Feedback is welcome.

[benp444]

OK, so given that there is no support for XML in Swagger, what is the commonly accepted work around where:

a) your data models are defined outside of the Swagger files and
b) you data models are defined in XSD.

My clumsy efforts have led me to the following Swagger file where I am using description to indicate to developers what they must expect in terms of payload definitions:

 post:
      summary: Creates a new student
      parameters:
        - name: StudentPerson
          in: body
          description: 'http://myOrg.com/schema/student/StudentPerson.xsd'
          schema:
            type: string

There must be some commonly accepted practice for using Swagger whilst at the same time stating "the payload should be based on this XML schema"

Can anyone provide some insight?

[ioggstream]

Work-in-progress here #1736

[slogic]

ok, that thread is closed until oas 3.1.0 is ready. i see it is published 2 years ago. where is continuation of this thread?