Mapping Definition File

Information in a mapping definition.

A mapping defines the correspondence between the fields of the source dataset and the properties of the entity model. The mapping definition file is used by the mapping step in a flow.

All mapping definition files are stored as JSON in the directory your-project-root/mappings/yourflowname-yourmappingstepname. The filename must be in the format yourflowname-yourmappingstepname-version.mapping.json. For example, the first version of a mapping called ProductMapping is stored as your-project-root/mappings/MyFlow-ProductMapping/MyFlow-ProductMapping-0.mapping.json.

See About Mapping.

Mapping Definition File Template

   {
    "language" : "zxx",
    "name" : "MyFlow-MyMappingStep",
    "description" : "",
    "version" : 1,
    "targetEntityType" : "http://example.org/MyEntity-0.0.1/MyEntity",
    "sourceContext" : "/",
    "sourceURI" : "/q/data-hub/....json",
    "properties" : {
      "my-entity-property-1": {
        "sourcedFrom": "my-source-field-1"
      },
      "my-entity-property-2": {
        "sourcedFrom": "myFunction( my-source-field-X, my-source-field-Y )"
      }
    }
  }
Field Description
languageThe language of the source records, if defined. Otherwise, zxx.
nameThe name of the mapping. If generated by QuickStart, the format is yourflowname-yourmappingstepname.
description(Optional) A description of the mapping.
versionThe zero-based version of the mapping. This value must match the version component of the filename.
targetEntityTypeThe URI to the entity to map against. If generated by QuickStart, the format is yourentitybaseuri/yourentityname-yourentityversion/yourentityname.
sourceContextThe root where the source fields are located in the source JSON.
sourceURIThe URI of the source record from which to extract the source fields.
properties Key-value pairs where:
  • the key is the name of the target entity property, and
  • the value is an array of sources and other properties.
The value of sourcedFrom can be:
  • a specific source field,
  • a mapping function that calculates the value to assign to the target entity property, or
  • an XPath 2.0 expression.

sourcedFrom Expressions

Expressions in the sourcedFrom must conform to the XPath 2.0 standards. Examples:

Expression Example Description
for ... in ... return ... 
   "my-entity-property": {
    "sourcedFrom": "for $item in items/* return $item"
  },
The entity property is assigned the last item in items/*.
if (...) then ... else ... 
   "my-entity-property": {
    "sourcedFrom": "if (price > 100) then 'high' else 'low'"
  },
The entity property is assigned either the string "high" or the string "low".

The following operators are allowed in the expressions:

Mathematical operators +, -, *, idiv, div, mod
Comparison operators is, eq, ne, lt, le, gt, ge, =, !=, <, <=, >, >=, <<, >>
Logical operators AND, OR