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 directoryyour-project-root/mappings/yourflowname-yourmappingstepname. The filename must be in the formatyourflowname-yourmappingstepname-version.mapping.json. For example, the first version of a mapping calledProductMapping is stored asyour-project-root/mappings/MyFlow-ProductMapping/MyFlow-ProductMapping-0.mapping.json.

SeeAbout 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 )"          }        }      }"relatedEntityMappings": [         {        "relatedEntityMappingId": "Customer.customerId:Order",        "collections": ["mapCustomersWithRelatedEntitiesJSON", "Order"],        "expressionContext": "/Orders",        "uriExpression": "hubURI('Order')",        "permissions": "data-hub-common,read,data-hub-common,update",        "properties": {          "orderId": {            "sourcedFrom": "OrderId"          },          "orderDateTime": {            "sourcedFrom": "parseDateTime(DateAndTime, 'YYYY/MM/DD-hh:mm:ss')"          },          "orderedBy": {            "sourcedFrom": "/CustomerID"          },          "deliveredTo": {            "sourcedFrom": "SendToID"          },          "lineItems": {            "sourcedFrom": "Products",            "properties": {              "quantity": {                "sourcedFrom": "Quantity"              },          "includes": {            "sourcedFrom": "ProductId"           }          },            "targetEntityType": "#/definitions/LineItem"           }          },            "targetEntityType": "http://marklogic.com/example/Order-0.0.1/Order"          },
FieldDescription
languageThe language of the source records, if defined. Otherwise,zxx.
nameThe name of the mapping.
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.
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.
propertiesKey-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 ofsourcedFrom 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 thesourcedFrom must conform to theXPath 2.0 standards. Examples:

ExpressionExampleDescription
for ... in ... return ...
   "my-entity-property": {    "sourcedFrom": "for $item in items/* return $item"  },
The entity property is assigned the last item initems/*.
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 operatorsis,eq,ne,lt,le,gt,ge,=,!=,<,<=,>,>=,<<,>>
Logical operatorsAND,OR