Integration mapping file combination

The combination process for integration mapping files and the target use cases for it are similar to the process and use cases for JSON schemas and Swagger schemas. Most of the JSON schema file combination reference applies to integration mappings as well.

Integration mapping combination specifics

Integration mapping files are simple compared to JSON schemas and Swagger schemas. Hence, the combination process for mapping files is just as simple as the process is for schemas. Exact details for how to combine specific elements are in the Integration mapping file specification. To validate combined mappings, you follow a philosophy similar to the philosophy you would follow for validating the structure of JSON schema and Swagger schema combinations. If a mapping named Ext combines with a mapping named Base, the following rules would apply:

If Ext changes the root schemaName from BaseJson to ExtJson, the schema definitions in ExtJson that the mapper uses must be compatible from a structural standpoint with the schema definitions in BaseJson.
If Ext changes the root type of a mapper defined in Base, the root type defined in Ext must be contravariant with respect to the type defined in Base.
If Ext changes a path expression that is defined in Base, the new path expression must have a return value that is covariant with respect to the expression defined in Base.

The net intent for these rules is that you be able to substitute references to mappers in Ext for references to mappers defined in Base. That is, if code refers to the Address mapper from the Base mapping, you can change that code to refer to the Address mapper from the Ext mapping.

In this case, the code will continue to execute at runtime. Moreover, the code will execute because the Ext version of the mapper accepts either the input type or a more generic type. In addition, the code will produce output that is a superset of the Base output. This relationship between outputs exists because the schema definitions in Ext are structurally compatible the definitions in Base.

Schema overrides

You can change the effect of downstream schemas to which the schema Base refers by modifying the mapping Ext. You effect this change by changing the root schemaName property on the mapping. PolicyCenter resolves mapper schema references with respect to the root schemaName property. Consequently, changing the root schemaName property will cause all mapper schema definitions to resolve in terms of the new schema. The common extension pattern looks like this:

A first schema, base_schema-1.0, is the starting point.
A first mapping, base_mapping-1.0, refers to base_schema-1.0 in the mapping schemaName attribute.
A second schema, ext_schema-1.0, combines base_schema-1.0 and adds new definitions and properties.
A second mapping, ext_mapping-1.0, combines base_mapping-1.0 and uses ext_schema-1.0 as a value for the schemaName attribute.

The mappers that the second mapping, ext_mapping-1.0, inherits from the first mapping, base_mapping-1.0, will be pointing to the schema definitions in ext_schema-1.0. The second schema, ext_schema-1.0, will in turn inherit the properties and definitions from base_schema-1.0. The second schema will also add new properties and definitions not in the first schema.