Creating or transforming a JSON message by using a JSON schema

You can use the Graphical Data Mapping editor to create or transform a JSON message with a data model defined from a JSON schema or a Swagger document.

Before you begin

Ensure that you have a JSON schema or Swagger document to provide the model for your data. If you do not have a JSON schema model, you can model and transform your data using the Add User Defined function, as described in the following topics:

About this task

When you create a message map for a Mapping node, you can choose to have the input and output message body data defined through a JSON type in a supported JSON schema.

When you select this option, the map is created with the input and output data fully defined by the JSON schema data definitions in the referenced JSON schema file. When you create a message map to transform JSON data in this way, the map must be located in the same shared library or REST API as the JSON schema file.

When working with a JSON model, you can use a JSON schema or Swagger document in either JSON or YAML format. You can also use the JSON elements and types to perform mapping casts; for more information, see Casting elements in a message map.

Procedure

Use a message map to transform data to or from a JSON data model in a JSON schema, by following these steps:

  1. Ensure that your JSON schema model is available for use by the message map:
    1. Put your JSON schema file (with a .json, .yaml, or .yml extension) in one of the following 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.

      Ensure that the schema model file conforms to the JSON Schema draft 4 specifications and meets the requirements specified in JSON schema requirements for message maps.

    2. Ensure that the container selected to create the new message map is the one that contains the JSON schema or Swagger documents that need to be referenced. Also ensure that the model definitions meet the requirements specified in JSON schema requirements for message maps.
  2. Create a new message map by starting the New Message Map wizard, either from the context menu or by double-clicking a Mapping node. If you are creating a message map for a REST API operation request or response mapping, ensure that you start the New Message Map wizard by double-clicking the Mapping node in the operation subflow. For more information, see Implementing a REST API operation by using a message map.
    1. On the first panel of the wizard, select a map that is called from a Mapping node; submaps are not supported with models from JSON schema.
    2. Ensure that the container selected for the new message map is the same shared library or REST API project that contains your JSON schema file.
    3. Click Next to move to the Select inputs and outputs panel. Expand the JSON Types folder under the shared library or REST API project folder, to view and select the required type. You can also enter part of the Type name in the filter boxes, to limit the search.
      • JSON array types are prefixed with JSONArray_.
      • The root level type from a JSON schema file is the basename of the containing file, suffixed with _JsonType.
      • The type names are unique in a JSON schema file. If two JSON schema files provide a type with the same name, you must select the required type by using the filename to distinguish them.
      • If your JSON data is not located in the message body (for example, if you have a REST request node that is configured to place its response in the environment), you can add a mapping cast to specify Environment.Variables.any when the map is created and opened in the editor.
    4. If you have selected a JSON type that is not in the same Toolkit container as the one in which the map will be created, an error is displayed and you cannot continue until all the map and JSON schema files are located in a single shared library or REST API container.
      When performing a mapping cast, the elements and types from JSON schema and Swagger documents located in the same container as the map will be included in the list of available options.
    5. Click Finish, and the map is opened in the Graphical Data Mapping editor.
  3. Complete the required transformation logic in the message map, by using any of the available transform types. For more information, see Transform types in the Graphical Data Mapping editor and Editing message maps.
    In addition to transforming the message data, you can interact with resources as described in the following topics:

What to do next

Deploy the solution with the message map, and exercise it to verify that the output message is as required. For more information, see Troubleshooting a message map.