Conversion Between Swagger and XML in
TIBCO Business Studio

When you create a service using a Swagger file,
TIBCO Business Studio 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 by creating your XML schema using the Schema Editor in
TIBCO Business Studio. 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. If the Swagger file originated in
TIBCO Business Studio, then it can be modified in
TIBCO Business Studio.

Note:TIBCO Business Studio 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-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 handles Swagger to XML conversion of arrays differently than it handles single elements. This sections explains how
TIBCO Business Studio 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:

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

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 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. Do not use the "array" suffix in an XSD element name.

Swagger array representation in
TIBCO Business Studio

When
TIBCO Business Studio 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-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-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.

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 example above appear as follows in the
Schemas folder of
TIBCO Business Studio:

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

The above example appears as follows in the
Schemas folder in
Project Explorer:

Forms

TIBCO Business Studio 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:

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: