Mapping Definition File

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 )"
          }
        }
      }
	"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"
          },


Field	Description
language	The language of the source records, if defined. Otherwise, `zxx`.
name	The name of the mapping.
description	(Optional) A description of the mapping.
version	The zero-based version of the mapping. This value must match the version component of the filename.
targetEntityType	The URI to the entity to map against.
sourceContext	The root where the source fields are located in the source JSON.
sourceURI	The 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`