SimpleIO data types reference

  • Each element in a SimpleIO (SIO) definition has a specific data type
  • All data types can be imported from the zato.server.service package, e.g.:
from zato.server.service import AsIs, List
  • Unless it is overridden, the data type of an SIO element implictly defaults to Text
  • Various convenience prefixes and suffixes can be used by idiomatic declarations - read the full documentation here

SIO data types available

The table below contains all the SIO data types available along with a brief description for each. The following sections document each in detail.

Data type Notes
AsIs A passthrough element which ensures that the service receives data exactly as it was sent, without any conversions by Zato. It is useful in case where the automatic data type conversion is not required, e.g. by default an element named is_active would be converted to a boolean value but AsIs(‘is_active’) will indicate that no conversion should be attempted.
Bool Converts input data to a Python bool instance.
CSV Expects for input data to be a comma-separated list and converts it to a Python list.
Date Converts input data to a datetime.date instance.
DateTime Converts input data to a datetime.datetime instance.
Decimal Converts input data to a decimal.Decimal instance.
Dict Converts input data to a Python dict object.
DictList Converts input data to a Python list of dict objects.
Float Converts input data to a Python float object.
Int Converts input data to a Python int object.
List Converts input data to a Python list instance.
Text Converts input data to a Python string (Unicode) object.
UUID Converts input data to a Python uuid.UUID4 object.

AsIs

Can be used with: JSON, XML/SOAP, CSV and POST

Elements of type AsIs are used to indicate that Zato should not convert input data in any way, e.g., to override default conversions through suffixes and prefixes.

For instance, in the definition below, values of user_id would be by default converted to integers by Zato because the element ends in _id which triggers automatic conversion per the the default configuration ..

class SimpleIO:
    input = 'user_id'

.. however, if user IDs are non-numeric then this would result in a conversion error whereas with AsIs, no conversion will be carried out:

class SimpleIO:
    input = AsIs('user_id')

Bool

Can be used with: JSON, XML/SOAP, CSV and POST

Converts input data to Python bool instances - True, False - based on following values, respectively:

  • ‘true’, ‘yes’, ‘on’, ‘y’, ‘t’, ‘1’
  • ‘false’, ‘no’, ‘off’, ‘n’, ‘f’, ‘0’

CSV

Can be used with: JSON, XML/SOAP and POST

Converts input comma-separated data to a list of string elements. For instance ..

class SimpleIO:
    input = CSV('my_data')

.. if ‘my_data’ is given the value of ‘myuser,my_display_name,1997,off’ then the service will received a list of the following strings on input in self.request.input.my_data: [‘myuser’, ‘my_display_name’, ‘1997’, ‘off’].

Date

Can be used with: JSON, XML/SOAP, CSV and POST

Converts an input string to a Python’s built-in datetime.date instance. Input must have an unambiguous format, such as YYYY-MM-DD, otherwise conversion may have an undefined result, e.g. if input is 12/12/12 it is not clear which of the elements is year, month or day.

DateTime

Can be used with: JSON, XML/SOAP, CSV and POST

Like Date but converts to datetime.datetime objects.

Decimal

Can be used with: JSON, XML/SOAP, CSV and POST

Converts an input string to a Python’s built-in decimal.Decimal instance.

Dict

Can be used with: JSON

Converts an input JSON dict to a Python dict, optionally validating the existence or lack of keys and sub-keys. Can embed other SIO elements including other Dict ones.

If no keys are listed in the element’s declaration, any and all JSON keys will be accepted.

For instance:

class SimpleIO:
    input = Dict('user_data')

The above will convert user_data to a Python dict in self.request.input.user_data regardless of its form in JSON as long it is a dict (hashmap).

If keys are provided explicitly, only what is provided in the declaration will exist in the service’s input, e.g.

class SimpleIO:
    input = Dict('user_data', 'username', 'display_name')

The above created a definition in which an input ‘user_data’ dictionary must exist and it must contain two keys: ‘username’ and ‘display_name’. Any other input keys from user_data will be ignored.

Dict keys may point to other SimpleIO definitions:

class SimpleIO:
    input = Dict('user_data', 'username', 'display_name', Dict('address', 'street', 'region'))

That definition has an embedded Dict object which expects a JSON sub-dict under key ‘address’ with keys ‘street’ and ‘region’, such as below:

{
  "user_data": {
    "username": "my_name",
    "display_name": "My Display Name",
    "address": {
      "street": "My Street",
      "region": "My Region"
    }
  }
}

DictList

Can be used with: JSON

Works exactly like Dict but expects a JSON list od dictionaries (hashmaps) on input. Otherwise, everything that applies to Dict applies to DictList as well.

Float

Can be used with: JSON, XML/SOAP, CSV and POST

Converts input data to Python float instances.

Int

Can be used with: JSON, XML/SOAP, CSV and POST

Converts input data to Python int instances.

List

Can be used with: JSON

Converts input data to Python list instances. Does not check the contents of the input list - if this is required, use Dict elements.

Text

Can be used with: JSON, XML/SOAP, CSV and POST

UUID

Can be used with: JSON, XML/SOAP, CSV and POST

Converts input data to Python’s built-in uuid.UUID4 instances.

SIO data types and data formats

The following table contains information which SIO data types are available for which data format. With JSON, it is possible to use all of the SIO data types whereas other data formats cannot make use of container-like data types.

A runtime exception will be raised if a service has an SIO definition over a channel whose data format that is incompatible, e.g. if a CSV document is sent to a service whose SIO definition contains a DictList element, this will result in an exception.

Data type JSON XML/SOAP CSV POST
AsIs Yes Yes Yes Yes
Bool Yes Yes Yes Yes
CSV Yes Yes Yes
Date Yes Yes Yes Yes
DateTime Yes Yes Yes Yes
Decimal Yes Yes Yes Yes
Dict Yes
DictList Yes
Float Yes Yes Yes Yes
Int Yes Yes Yes Yes
List Yes
Text Yes Yes Yes Yes
UUID Yes Yes Yes Yes

Convenience prefixes and suffixes

To make one’s source code use less imports and declarations use fewer explicit SIO data types, it is possible to apply convenience prefixes and suffixes.

For instance, both of the definitions below are equivalent, yet the first one is more convenient to read:

class SimpleIO:
    input = 'user_id', 'is_active', 'has_account'
class SimpleIO:
    input = Int('user_id'), Bool('is_active'), Bool('has_account')