Casting elements in a message map

In the Graphical Data Mapping editor, use the Cast function to redefine parts of the input or the output model in a message map. This function is also known as a mapping cast.

About this task

To create a flexible message model, you can define elements in your XML schema as wildcards, or you can provide an extension or derived type from a base type. In a JSON schema, you can use the "oneOf" or "anyOf" keywords to allow flexibility.

A wildcard is an element in your XML schema that is defined as xsd:any, xsd:anyType, or xsd:anySimpleType.

A message model schema might contain one or more wildcards. In addition, the model for the Message Assembly Environment, Local Environment, transport header folders, and SOAP and JSON domain messages, include wildcards, such as under the environment Variables folder, which allow you to define data specifically for the operation of your flow.

In the Graphical Data Mapping editor, you can redefine these wildcards by using the Cast function to select an element or type that is defined in a message model, such as an XML schema, DFDL schema, JSON schema, or Swagger document. For more information, see Casting a wildcard defined as xsd:any into a specific type for a SOAP message and Configuring a generic type in the local environment tree by using the Cast function.

If you do not have a message model that provides a suitable element for casting, consider adding a user-defined element, as described in Defining user-defined elements. When you have added a user-defined element, you can set its type from a global type in your message model, as described in Defining the structure of a complex user-defined element.

When you apply a mapping cast, the choices that are available vary according to the type. The following choices are available for the specified type:

xsd:any: All global elements defined in the message models that are contained in the same application or referenced library, and are therefore visible to the map. This includes elements from XML, DFDL, and top-level objects and arrays in JSON schema.
xsd:anyType: All global types defined in the message models that are contained in the same application or referenced library, and are therefore visible to the map. This includes global types from XML, DFDL, and the types defined for top-level objects and arrays in JSON schema.
xsd:anySimpleType: All the standard XML types and any global type extensions for XML simple types defined in the XML message models that are contained in the same application or referenced library, and are therefore visible to the map.
<namespace>:<base XML schema type>: All the XML types that are defined as extensions or derived from this XML schema type.
JSON type defined with "oneOf" or "anyOf": The JSON types defined in the "oneOf" or "anyOf" array.

If you are casting to an element or type that is derived from a JSON schema or Swagger document, see JSON schema requirements for message maps.

You can use the Cast function to redefine a wildcard or base type multiple times. Each type that you cast appears under the wildcard or base type within a choice group.

To define transformations between subtypes of an XML data type, you can use extension or derived types. A derived type is a data type that is related to another data type known as the base type or super type. You can cast a base type to a derived type by using the Cast function. For more information, see Casting an XML schema base type to a derived type or extension type.

When your input message or your output message is the IBM provided JSON domain object or JSON domain array message, you can redefine the Data element that is of type anyType by using the Cast function. For more information, see Modeling a JSON message for use in a message map by using an equivalent XML schema model.

You can also use the JSON schema "oneOf" and "anyOf" keywords, to structure and combine more complex JSON schema. For more information, see Casting with JSON schema types and JSON schema requirements for message maps.

Procedure

To redefine an element in your input or output model by using the Cast function, complete the following steps:

Open the map in the Graphical Data Mapping editor.
Right-click the element that you want to redefine, and select Cast.

The Type Selection dialog opens:
Select the type that you want to cast to, and then click OK.
The Type Selection dialog lists only those elements and types that are appropriate for the element that you want to cast, and that are contained in a referenced application or library. When you cast a base element, the Type Selection dialog lists only derived types.
Note: In the following situations, choice of cast items contains more than one item:
- You cast a wildcard input type to a specific schema type.
- You cast a base schema input type to an extension or a restricted type.
When applying XML extension or derived type schema type casts, the Graphical Data Mapping editor automatically applies an XPath expression to the mappings from these casts. At run time, the XPath expression checks the xsi:type attribute of the input element to determine which of the types is present in the input data. Then, only the mapping from the appropriate type is performed. The expression checks only the name of the type in each cast; the namespace is not considered. If choice of cast items includes types that have the same name but are in different namespaces, you must add your own conditional transform that checks the namespace and name part of the xsi:type attribute of the input data. When choice of cast items includes only a single type, the xsi:type attribute is not checked, and you must ensure that the input data presents only the single cast type.

Results

After you use the Cast function to qualify the type of the element that is defined with a wildcard, the type appears under the wildcard. You can define transformations between the input message and the output message. For more information, see Specifying a transform (mapping operation).