IBM Integration Bus, Version 10.0.0.3 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS


Modeling a JSON message for use in a message map by using a schema model

In the Graphical Data Mapping editor, you can use the Cast function to create a JSON message that contains JSON objects, JSON arrays, or both. You must provide your own schema message model.

About this task

If you don't want to provide a reusable model of your JSON data in a schema message model, you can define the JSON data in-line in the map by using the Add User-Defined function. For more information, see Graphically modeling a JSON message in a message map.

Procedure

Complete the following steps to create a JSON message based on a schema model:

  1. Create a message map. Select one of the following JSON supplied models as the output of the map:
    • JSON (JSON object message model supplied by IBM) to create a JSON object message
    • JSON (JSON array message model supplied by IBM) to create a JSON array message

    For more information, see Creating a message map.

  2. Delete the predefined Data object. Choose one of the following options:
    • If you select JSON (JSON object message model supplied by IBM) in the previous step, delete the Data element of type JSONObject.

      Figure that shows context menu to delete the extra Data element in a JSON message.

    • If you select JSON (JSON array message model supplied by IBM) in the previous step, delete the Data element of type JSONArray_1.

      Figure that shows context menu to delete the extra Data element in a JSON message.

    Note: In the Graphical Data Mapping editor, you can only have one Data element in a JSON message if you use a schema model to define the JSON message.
  3. Qualify the Data element of type anyType by using the Cast function.

    For more information, see Casting elements in a message map.

    When you cast the JSON.Data.any on the input side of the map to define the JSON message, you can only use schema models that are defined in the default namespace.

    For example, if you build a JSON input with a cast to an element in a none empty namespace, the Mapping node runs without throwing an error. However, you might not get the expected output. You can use a user trace to see that the presence of the namespace can be deduced as the cause of the map failure:
    1. First, you see that the map successfully locates JSON.Data.
    2. Next, you see BIP message BIP3959I: The Mapping node is traversing the input tree by using the nodetest ''element(Data)'' and the relationship ''child''. The number of matching elements is ''1''.
    3. Finally, you see that the map fails to locate anything for the subsequent JSON objects. You see BIP message BIP3959I: The Mapping node is traversing the input tree by using the nodetest ''element({http://schema014_T}:testMsgNsImpIn)'' and the relationship ''child''. The number of matching elements is ''0''.

    When you cast the JSON.Data.any on the output side of the map to define the JSON message, you can use a schema element in a none default namespace. It is recommended that you use the default namespace.

    The Mapping node creates the elements with namespaces and the JSON serializer ignores them.

    Note: When you define a JSON message by using the Cast function, you must comply with the following rules:
    • You must define the schema definition for the type of a JSON object in the default namespace.
    • You must define the schema definition for a JSON array in the target namespace http://www.ibm.com/iib/msl/json.
    • The name of the type must comply with the following naming convention: JSONArray_<unique name>. JSONArray_ is mandatory. You can define any name for <unique name>. For example, you can name a type as JSONArray_ofBooleans if the type is an array of Boolean elements. You can name a type JSONArray_ofMyAddrObjects if the type is a complex type.

    For more information, see Modeling a JSON object and a JSON array for use in a message map by using a schema model.

  4. Define transforms between the input elements and the output elements.
    • Use the Assign transform to set a fixed value without the use of input data.
    • Use the Create transform to create an empty element, or a nil element without the use of input data.
    • Use the Move transform to copy an input element value to the output element.
    • Use the If transform, a custom transform, or the XPath transform to define the condition that determines the value of an output element.
    • Use the Append transform, the Group transform, the For Each transform, the Join transform, a custom transform, or the XPath transform to set the value of a JSON array.
    • Use the Select transform or the Database Routine transform to set the value with data available in a database system.
    • Use the xs:type transform to cast the value of a simple input element to a specific data type.
    • Use the fn:type transform to set the value by using XPATH 2.0 functions.
    • Use the Custom Java transform to enter your own Java™ code.
    • Use the Custom ESQL transform to call your own ESQL code.

    For more information, see Specifying a transform (mapping operation).

Example

Example for a JSON object message

This example shows how to define a schema model for a JSON object message in the default namespace:
{ "Nam" : "A Name", "Num" : 1 }
The message tree for the JSON message is described in the following trace:
(0x01000000:Object):JSON       = ( ['json' : 0x2f030fa0]
    (0x01000000:Object):Data = (
          (0x03000000:NameValue):Nam = 'A Name' (CHARACTER)
          (0x03000000:NameValue):Num = 1 (INTEGER)
    )
  )
The following code shows the schema file that defines the JSON object message:
<?xml version="1.0" encoding="UTF-8"?>
   <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:complexType name="MyJsonObjType1">
    	<xsd:sequence>
    		<xsd:element name="Nam" type="xsd:string" nillable="true"></xsd:element>
    		<xsd:element name="Num" type="xsd:int" nillable="true"></xsd:element>
    	</xsd:sequence>
    </xsd:complexType>
</xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model MyJsonObjType1:

Figure that shows the JSON message that is defined in a map by using the cast function.

Example for a JSON array message

This example shows how to model a JSON message that is an array of Boolean elements. You define a schema model for the following JSON array message in the default namespace:
[ true,false ]
The message tree for the JSON array message is described in the following trace:
  
(0x01000000:Object):JSON       = ( ['json' : 0x292051a0]
    (0x01001000:Array):Data = (        
      (0x01000000:NameValue):Item  = TRUE (BOOLEAN)
      (0x01000000:NameValue):Item  = FALSE (BOOLEAN)      
     )
)
The following code shows the schema file that defines the JSON array message in the target namespace http://www.ibm.com/iib/msl/json:
<?xml version="1.0" encoding="UTF-8"?>
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"  targetNamespace="http://www.ibm.com/iib/msl/json">
     <xsd:complexType block="#all" name="JSONArray_ofBoolean">
        <xsd:sequence>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="Item" nillable="true" type="xsd:boolean"/>
        </xsd:sequence>
   </xsd:complexType>
</xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model JSONArray_ofBoolean:

Figure that shows the JSON message that is defined in a map by using the cast function.

Example for JSON object message with an array of objects

This example shows how to model a JSON message that is an array of objects.
[ { "nam":"one","val":1 },{ "nam":"two","val":2 }]
The message tree for the JSON object message is described in the following trace:
  
(0x01000000:Object):JSON       = ( ['json' : 0x292051a0]
    (0x01001000:Array):Data = (      
                        (0x01000000:Object):Item = (
                                                  (0x03000000:NameValue):nam = 'one' (CHARACTER)          
                                                  (0x03000000:NameValue):val = 1  (INTEGER)      
                                                   )      
                        (0x01000000:Object):Item = (
                                                  (0x03000000:NameValue):nam = 'two' (CHARACTER)         
                                                  (0x03000000:NameValue):val = 2 (INTEGER)      
                                                  )
                             )
)

You define a schema model for the JSON object message in the default namespace.

The following code shows the schema file that defines the JSON array. You define the JSONArray_ofObjects type in the target namespace http://www.ibm.com/iib/msl/json:
<?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ibm.com/iib/msl/json">
         <xsd:complexType block="#all" name="JSONArray_ofObjects">
             <xsd:sequence>
                 <xsd:element maxOccurs="unbounded" minOccurs="0" name="Item" nillable="true">
                     <xsd:complexType>
                         <xsd:sequence>
                            <xsd:element name="nam" type="xsd:string" nillable="true"/>
                            <xsd:element name="num" type="xsd:int" nillable="true"/>
                         </xsd:sequence>
                    </xsd:complexType>
               </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
 </xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model JSONArray_ofObjects:

Figure that shows the JSON message that is defined in a map by using the cast function.

Example for JSON Object message containing a JSON array

This example shows how to model a JSON object message that contains a JSON array.
{ "state":"ok", "array":[ { "nam":"one","val":1 },{"nam":"two","val":2 } ] }
The message tree for the JSON object message is described in the following trace:
  
(0x01000000:Object):JSON       = ( ['json' : 0x292051a0]
    (0x01000000:Object):Data = (      
             (0x03000000:NameValue):state= 'ok' (CHARACTER)
             (0x01001000:Array):array= (        
                             (0x01000000:Object):Item = (
                                                (0x03000000:NameValue):nam = 'one' (CHARACTER)          
                                                (0x03000000:NameValue):val = 1  (INTEGER)        
                                                         )        
                             (0x01000000:Object):Item = (
                                                (0x03000000:NameValue):nam = 'two' (CHARACTER)          
                                                (0x03000000:NameValue):val = 2 (INTEGER)        
                                                         )
                                         ) 
                              )
)
The object message is defined in the default namespace and imports the type of the JSON array element from the second schema. The following code shows the schema file that defines the JSON object message:
<?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:mjatns="http://www.ibm.com/iib/msl/json">
      <xsd:import namespace="http://www.ibm.com/iib/msl/json" schemaLocation="MyJsonArrayTypes.xsd"/>
         <xsd:complexType name="MyJsonObjWithArrayType1">
             <xsd:sequence>
                 <xsd:element name="state" type="xsd:string" nillable="true"></xsd:element>
                 <xsd:element name="array" type="mjatns:JSONArray_ofObjects" nillable="true"></xsd:element>
              </xsd:sequence>
         </xsd:complexType>
    </xsd:schema>
The following code shows the schema file that defines the JSON array. You define the JSONArray_ofObjects type in the target namespace http://www.ibm.com/iib/msl/json:
<?xml version="1.0" encoding="UTF-8"?>
   <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ibm.com/iib/msl/json">
       <xsd:complexType block="#all" name="JSONArray_ofObjects">
           <xsd:sequence>
                <xsd:element maxOccurs="unbounded" minOccurs="0" name="Item" nillable="true">
                                  <xsd:complexType>
                                             <xsd:sequence>
                                                   <xsd:element name="nam" type="xsd:string" nillable="true"/>
                                                   <xsd:element name="num" type="xsd:int" nillable="true"/>
                                             </xsd:sequence>
                                  </xsd:complexType>
                </xsd:element>
         </xsd:sequence>
     </xsd:complexType>
    </xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model MyJsonObjWithArrayType1:

Figure that shows the JSON message that is defined in a map by using the cast function.

What to do next

Deploy the message map and verify that the output message is valid. For more information, see Troubleshooting a message map.


sm12023_.htm | Last updated 2015-11-27 00:02:41