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.

You have the option to create a REST service or reference using a Swagger file or you can create them from scratch in the TIBCO Business Studio for BusinessWorks by creating your XML schema using the Schema Editor in TIBCO Business Studio for BusinessWorks. When you create a REST service or reference from a Swagger file, a corresponding XSD file is automatically generated in the Schemas folder of your project. When you create a REST service or reference from scratch using their respective wizard, then a corresponding Swagger file gets generated in the Service Descriptors folder of your project.
Note: A Swagger file is a contract that must be followed. Only the originator of the Swagger file can modify it in TIBCO Business Studio for BusinessWorks. If the Swagger file originated in TIBCO Business Studio for BusinessWorks, then it can be modified in TIBCO Business Studio for BusinessWorks.
Note: TIBCO Business Studio for BusinessWorks maintains a link between the Swagger file and its generated .xsd file. Multiple XSD files may be linked to one Swagger file. Do not edit a TIBCO Business Studio for BusinessWorks-generated .xsd file because its contents will be replaced the next time the file is generated.

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

The following table shows the conversion of elements of basic types between XML and Swagger in TIBCO Business Studio for BusinessWorks:
XSD type Corresponding type in Swagger
long integer
short, int, integer integer
double number
float number
string string
base64Binary string
decimal number
boolean boolean
byte string
date string
dateTime string
binary string

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.

Since the object has multiple attributes, it is a complex type element in XSD. The minOccurs="0" indicates that specifying a value for the attribute is optional.
Note: If $ref and type: object are present in the Swagger file, type: object is ignored, and only $ref is considered.
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.

Note: The word "Array" is a key word in TIBCO Business Studio for BusinessWorks. Do not use the "array" suffix in an XSD element name.

Swagger array representation in TIBCO Business Studio for BusinessWorks

When TIBCO Business Studio for BusinessWorks encounters an array in the Swagger file, while generating a schema for it, it models the array by generating two separate but related elements in the .xsd file for each array:
  • 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.
Note: Do not edit a TIBCO Business Studio for BusinessWorks-generated .xsd file because its contents will be replaced the next time the file is generated.
The example below shows the definition of an array called Products in Swagger and its corresponding XSD.
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. .

An operation in a REST API has one of the following encoding:
  • 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:
    • name - used to store the name of the file
    • content - used to store the actual data within the file

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: