Altova MapForce 2024 Enterprise Edition

JSON

JSON (JavaScript Object Notation) is a very popular data format for storing and transporting data. In MapForce Enterprise Edition, you can map data from any formats supported by MapForce to JSON, and vice versa. You can also serialize JSON data as a string (for example, for writing to a database) or parse a JSON string into a JSON structure with the help of Parse/Serialize components. For more information, see Parsing and Serializing Strings.

To use JSON files in mappings, the mapping language must be set to one of the following: Built-in, C#, Java. For more information, see Transformation Languages.

Similar to other component types supported by MapForce, a schema file is required before you can read or write JSON data. If you don't have a schema file, MapForce can generate one automatically. See Adding JSON Files as Mapping Components. If you supply a JSON schema file not generated by MapForce, then MapForce expects it to be of version Draft 04, Draft 06, Draft 07, Draft 2019-09, Draft 2020-12 or have no version at all. For more information about JSON Schema versions, see the JSON Schema Specification.

The following is an example of how a JSON structure appears in MapForce:

JSON Component in MapForce

As illustrated above, the structure of nodes in the JSON component reflects the structure of the JSON instance file. The basic JSON types are conventionally represented in MapForce as shown below.

Type	MapForce representation
Array
Boolean
Null
Number or integer
Object
String

There are also special cases, described below:

Case	Description
additionalProperties, patternProperties	The node appears on the JSON component under any object whose additionalProperties property is true or not present in the schema. It allows you to map to or from properties not explicitly listed in the schema (see also Example: Mapping from JSON to CSV). This node can also appear for objects having the patternProperties property.
Subtypes	JSON schema allows defining subtypes for objects and arrays (anyOf, allOf, oneOf). MapForce displays such subtypes using special structure nodes ( ) that do not have a direct representation in the JSON instance file. If your mapping is reading from a JSON file, such subtype nodes provide a value only if the current input value is valid according to the subtype schema. If your mapping is writing to a JSON file, make sure that you choose the correct subtype to fill. Filling multiple subtypes may lead to duplicate object properties and, thus, may result in invalid output JSON files.
Multiple types at the same location	JSON schema allows multiple types to occur at the same location. In such cases, the MapForce component displays separate structure nodes for all basic types that can occur at that location.
Type names	MapForce displays the title and description properties of types in the JSON schema in the "type" and "annotation" fields, if available. If title is absent, MapForce may also use part of the URI from the \$ref property as a type name.
Arrays containing mixed item types	If an array has different types of items in the JSON schema (for example, both strings and numbers), MapForce displays an "item" node for each item type. When writing to a JSON file, this enables you to create arrays which contain items of different types.
Arrays defined as tuples	If an array has items whose type is assigned by position in the JSON schema, MapForce displays the zero-based index of the item as separate structure nodes (for example item[0], item[1], and so on. When writing to a JSON file, this enables you to specify the type of each individual item in the array by its zero-based index.