JSON schema requirements for message maps

You can use the Graphical Data Mapping editor to create and transform JSON messages with the data model defined from a JSON schema or REST API swagger document, which can be in JSON or YAML format.

The following requirements apply to both JSON schema and to the model definitions from a Swagger document; for more information, see Swagger.

• JSON schema must be well formed, valid, and must conform to the JSON Schema draft 4 specifications.

  You can use an external tool to validate the JSON schema file before importing it and using it for message maps. For example, see http://jsonlint.com.

• JSON schema must be in either JSON format with a .json file extension, or YAML format with a .yaml or .yml file extension.
• JSON schema must be located in one of the following project containers:
  • Application
  • REST API project
  • Integration Service project
  • Shared library
  • Static library
  Note: Your message map and JSON schema file must be stored in the same project.
• When you are using a JSON schema for a Mapping Cast, such as mapping the output of a REST request node that has been configured to place its output in environment tree, bear in mind that cast types and elements are provided for only the following types:
  • Root-level JSON type, with the same name as the schema file
  • Top-level JSON types
  • JSON types defined in the definitions section
  The elements for a JSON array are suffixed with JSONArray, and the complex types for a JSON array are prefixed with JSONArray.
• Heterogeneous JSON arrays, in which the type of each entry can vary, appear in the message map with the Item field that represents an array entry defined as an any type. You can cast this any type to the heterogeneous JSON array types only if the JSON schema defines them through JSON references.
• The JSON schema "$ref" keyword is supported only for internal file references, which have the form "$ref" : "#/definitions/Pet".
• To enable message mapping, all JSON data types that are to be mapped from or to must be explicitly modelled. You cannot map from or to JSON data if it is present only because the JSON schema keyword additionalProperties is set to true. To be able to graphically map to or from data, it must be explicitly present in the model so that it appears as a named input or output in the map. Therefore, it is beneficial to use JSON schema models that set: "additionalProperties": false.
• The message map and Mapping node do not implement JSON schema validation. While JSON schema properties will be transposed into the model used for mapping, there is no validation that these are met by the transformation you provide. For example:
  • A JSON schema data member with type "string" and property "maxLength": 10

    This type could have an transform applied in the map that will set the length in excess of 10 characters. This would not cause a map design validation or runtime error.

  • A JSON enum could be set incorrectly to a value not matching one of the enumerations.
• JSON schema data defined as type "number" will be processed in the Mapping node using a Message Assembly tree type of "double". This might lead to the output JSON text providing the data in a scientific (exponential) notation. To avoid this, use the JSON schema type "integer".
• In the message map, optional/required/number of occurrences is modelled as "minOccurs" and "maxOccurs". The JSON schema keyword "required" sets "minOccurs=1", otherwise it is set as "minOccurs=0"
• A JSON schema "enum" with mixed type entries appears as a "string" type in the message map.
• The JSON schema "oneOf" and "anyOf" keywords, which are used for structuring and combining more complex JSON schema, are supported as follows:
  • Specifying a JSON type or null:
    • To define a type as either a primitive or null. For example:

      "NullableNums": {	
      	      "oneOf": [
      	        {
      	          "type": "integer",
      	        },
      	        {
      	          "type": "null"
      	        }
      	      ]
      }

    • To define a type as either an object or null, where the object can be defined inline or through $ref. For example:

      "Address" : {
      	"oneOf": [
      		{"type": "null"},
       		{"$ref":"#/definitions/Address"}
              	]
      }

    In these cases, the map presents the JSON type in the map ready for wiring transforms. The properties show that the type is defined as nillable.

  • To define a JSON schema top level type as an object or array of a $ref type. For example:

      "oneOf": [
        {
          "$ref": "#/definitions/Account"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Account"
          }
        }
      ]

    In this case the New Message Map wizard, or the Map Editor Add Input or Output dialog provides two entries for the JSON type, one as an Object and the other as an Array (in the example, these are Account and JSONArray_Account).

  • Support for the "oneOf" and "anyOf" keywords has been enhanced to handle a list with multiple types. For example:

    "Contact" : {
    "properties": {
    "conType": {
    "type": "string"
    }
    },
    "oneOf": [
                {"type": "null"},
                {"$ref":"#/definitions/Address"},
                {"$ref":"#/definitions/TelContacts"}
            ]
            }

    In this case the map initially displays the JSON object "Contact" with only the "conType" child, or with no content when the JSON object has no properties. You can right-click "Contact" and apply a mapping cast to one or more of the types from the list provided in the JSON schema; in this example, the types are "Contact_Address" and "Contact_TelContacts". For more information, see Casting with JSON schema types.

• The JSON data element names must also be a valid XML name.
  Note:
  Naming issues might not be detected in the Integration Toolkit, but they might lead to the deployment of the message map failing with a Map script generation error with a cause of invalid grammar.