Conversion Between Swagger and XML in TIBCO Business Studio for BusinessWorks
When you create a service using a Swagger file, TIBCO Business Studio for BusinessWorks converts the Swagger definitions into XML schema elements. You use the schema elements to configure your REST operations.
Not all artifacts in JSON have a direct equivalent in XML. For example, TIBCO Business Studio for BusinessWorks handles Swagger to XML conversion of arrays differently than it handles single elements. This sections explains how TIBCO Business Studio for BusinessWorks models the conversion of elements from Swagger to XML and vice versa.
Basic type elements
Objects
The following table shows how an object in JSON is converted into an XML schema element in TIBCO Business Studio for BusinessWorks. In this example, Product is an object that has three attributes called 'product_id', 'description' and 'dispaly_name' all of which are of type string.
This object in JSON... | ...is converted to the following in XSD |
---|---|
"Product": { "type": "object", "properties": { "product_id": { "type": "string", }, "description": { "type": "string", }, "display_name": { "type": "string", } } } |
<xs:element name="Product" type="tns:Product"/> <xs:complexType name="Product"> <xs:sequence> <xs:element minOccurs="0" name="product_id" type="xs:string"/> <xs:element minOccurs="0" name="description" type="xs:string"/> <xs:element minOccurs="0" name="display_name" type="xs:string"/> </xs:sequence> </xs:complexType> |
Arrays
An array is a collection of identically typed elements. The type can be primitive or complex. For the most part, when TIBCO Business Studio for BusinessWorks converts from JSON to XSD, you can see a one-to-one correspondence for the objects in Swagger and elements in the corresponding XSD file. The only exception lies in the handling of arrays.
Swagger array representation in TIBCO Business Studio for BusinessWorks
- a wrapper element (with an "Array" suffix) that acts as a definition for a container that holds the array elements. In addition to other attributes, this wrapper element contains the type of the element that the array contains. The wrapper element is a TIBCO Business Studio for BusinessWorks-generated artifact solely to comply with the XML requirement of having a container for a collection. It does not exist in the .json file. The array element is created with a boundary of 0..* (0 indicates that it is optional and * indicates that the array is unbounded).
- a definition of the element itself.
Array in JSON... | represented in XSD |
---|---|
"Products": { "type": "array", "items": { "$ref": "Product" } } |
<xs:element name="Products" type="tns:Products"/> <xs:complexType name="Products"> <xs:sequence> <xs:element maxOccurs="unbounded" minOccurs="0" name="Products" type="tns:Product"/> </xs:sequence> </xs:complexType>
|
In the example above, Products is an array in JSON (denoted by "type": "array") that contains multiple Product objects (denoted by "items":{ "$ref": Product). The object, Product, itself is defined in another location in the Swagger file. (see the "Objects" section above for the definition of Product).
The following shows how the Products array defined above is used as a path parameter:
The following in JSON schema... | ...gets converted to the following in XSD |
---|---|
"schema": { "type": "array", "items": { "$ref": "Product" } } |
<xs:element name="ProductArray" type="tns:ProductArray"/> <xs:complexType name="ProductArray"> <xs:sequence> <xs:element maxOccurs="unbounded" minOccurs="0" name="Product" type="tns:Product"/> </xs:sequence> </xs:complexType> |
The example above appear as follows in the Schemas folder of TIBCO Business Studio for BusinessWorks:
Anonymous Arrays
Since XML is a strongly-typed language, all elements - arrays and single elements alike, are named and have a type in XML. In JSON however, arrays can either be structured or anonymous. A structured array is type-based where a type defines the basic construct and also its elements. An anonymous array is an unnamed construct containing a group of homogenous objects. Neither the construct nor the elements contained in it have a type. Anonymous arrays simply contain blocks of data that repeat. The concept of anonymous arrays is used extensively in JSON, but does not exist in XML. In JSON, a parameter may be of type string, but if you add "type" : "array" to the definition, it becomes a collection of strings.
The following is an example of a JSON payload and its equivalent in XSD in TIBCO Business Studio for BusinessWorks. The wizard prompts you to enter a file name when generating XSD from a JSON payload. The file name entered was "ClassicNovels" in this example.
Anonymous array in JSON... | ...gets converted to the following in XSD |
---|---|
[ { "id": 1, "name": "Great Expectations", "author": "Charles Dickens", "isbn": "13: 978-0141439563", "genre": "Classic" }, { "id": 2, "name": "Jane Austen", "author": "Emma", "isbn": "13: 978-1493663644", "genre": "Romance" }, { "id": 3, "name": "Jude the Obscure", "author": "Thomas Hardy", "isbn": "13: 978-0140435382", "genre": "Tragedy" } ] |
<complexType name="ClassicNovelsElementType"> <sequence> <element maxOccurs="1" minOccurs="0" name="id" type="integer"/> <element maxOccurs="1" minOccurs="0" name="name" type="string"/> <element maxOccurs="1" minOccurs="0" name="author" type="string"/> <element maxOccurs="1" minOccurs="0" name="isbn" type="string"/> <element maxOccurs="1" minOccurs="0" name="genre" type="string"/> </sequence> </complexType> <element name="ClassicNovelsElement" type="tns:ClassicNovelsElementType"/> <complexType name="ClassicNovelsElementArrayType"> <sequence> <element maxOccurs="unbounded" minOccurs="0" ref="tns:ClassicNovelsElement"/> </sequence> </complexType> <element name="ClassicNovelsElementArray" type="tns:ClassicNovelsElementArrayType"/> |
The above example appears as follows in the Schemas folder in Project Explorer:
Forms
TIBCO Business Studio for BusinessWorks supports the use of form parameters as the media type in REST requests for POST, PUT, and PATCH operations. This is the only media type that can be used to transmit binary data and files. Form parameters must be defined at the operation level only and cannot be defined at the binding level. .
- Tag/Value (application/x-www-form-urlencoded) - used when you use form data which is of a primitive data type. You cannot send or receive binary data or files using this encoding.
- Multipart (application/form-data) - is superset of urlencoded encoding. Besides primitive data types, multipart encoding also supports binary and file data types. When the data type of a form parameter is either binary or text, two elements get created in TIBCO Business Studio for BusinessWorks:
The following illustrates how form parameters are represented in JSON and XSD:
Data types | JSON | XSD |
---|---|---|
primitive data types |
{ "/person" : { "post" : { "description" : "", "operationId" : "post-person", "consumes" : [ "application/x-www-form-urlencoded" ], "produces" : [ "application/json" ], "parameters" : [ { "name" : "name", "in" : "formData", "description" : "", "type" : "string", "required" : true } ] |
<xs:element name="personPostForm"> <xs:complexType> <xs:sequence> <xs:element maxOccurs="1" minOccurs="1" name="name" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> |
binary or file type |
{ "/person" : { "post" : { "description" : "", "operationId" : "post-person", "consumes" : [ "multipart/form-data" ], "produces" : [ "application/json" ], "parameters" : [ { "name" : "photo", "in" : "formData", "description" : "", "type" : "file", "format" : "binary", "required" : false } ] |
<xs:element name="personPostForm"> <xs:complexType> <xs:sequence> <xs:element maxOccurs="1" minOccurs="0" name="photo"> <xs:complexType> <xs:sequence> <xs:element maxOccurs="1" minOccurs="0" name="filename" type="xs:string"/> <xs:element maxOccurs="1" minOccurs="0" name="content" type="xs:base64Binary"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> |
The above examples appear as follows in the TIBCO Business Studio for BusinessWorks:
Primitive type:
Binary or File type: