Integration mapping file imports

Overview

Integration mapping files define an import reference in addition to a combine composition. The import reference for mapping files is analogous to the import reference for JSON schema files.

In addition, the differences between the import reference and combine composition are roughly analogous. On the one hand, the combine composition will stitch together all mappers with the same name. On the other hand, the import reference will keep everything in a separate namespace.

Choose between the composition and the reference based on whether you want the combination behavior or the import behavior. The combination behavior is ideal when logically extending another mapping file. The import behavior is ideal when reusing a standard mapping or mapper for a shared schema.

Import syntax

Integration mapping imports look similar to JSON schema imports, but they use the import property name instead of x-gw-import. References to imported mappers have a prefix with the alias name as in the following example:

{
  "schemaName": "gw.px.ete.contact-1.0",
  "import" : {
    "address" : "gw.px.ete.address-1.0"
  },
  "mappers": {
    "Contact" : {
      "schemaDefinition" : "Contact",
      "root" : "entity.Contact",
      "properties" : {
        "EmailAddress1" : {
          "path" : "Contact.EmailAddress1"
        },
        "HomePhone" : {
          "path" : "Contact.HomePhone"
        },
        "HomePhoneCountry" : {
          "path" : "Contact.HomePhoneCountry"
        },
        "AllAddresses" : {
          "path" : "Contact.AllAddresses",
          "mapper" : "address#/mappers/Address"
        },
        "PrimaryAddress" : {
          "path" : "Contact.PrimaryAddress",
          "mapper" : "address#/mappers/Address"
        }
      }
    }
  }
}

Import overrides

Just like with JSON schema imports, you can override mapping file imports in a combined mapping by re-declaring the imported alias with a different fully-qualified mapping name:

{
  "schemaName" : "customer.contact-1.0",
  "combine" : ["gw.px.ete.contact-1.0"],
  "import" : {
    "address" : "customer.address-1.0"
  }
}

Overriding a mapping file import will cause all inherited mapper references to the address alias to reference mappers from the customer.address-1.0 mapping rather than the gw.px.ete.address-1.0 mapping.