Integration mapping file specification

General information

Requiredness

Mapper properties designated as required are not always necessary in every mapping file. You must consider such properties in light of the entire combined mapping. You need not respecify a required property if a combined mapping file already defines it.

For example, suppose an extension mapping file, address_ext-1.0, combines a base mapping file, address-1.0. Further suppose that the base mapping file defines an Address mapper, the extension mapping file can also define the Address mapper. However, the extension mapping file need not redefine the schemaDefinition or root properties even though these properties are required. The Address mapper in the extension mapping file inherits those property values from the Address mapper in the base mapping file.

Combination styles

The combination of mapping files is roughly equivalent to an ordered, textual merge of the files. However, there are some nuances around how the merge works. Depending on the object and property, the following styles are possible:

merged
The referenced subobjects are merged together based on the rules for combining the particular object.
merged by key
The merged by key combination style involves matching up objects based on the keys in a map. For example, elements under the properties property with the same key are merged.
first non-null
Given N objects to be merged together, the mapping takes the first non-null value for the given property.
not inherited
The property is explicitly not inherited across files. This style is generally for root-level defaults that are propagated within only a given file.

Root object

Property Type Required Format Behavior Combination Style
schemaName string Yes The fully-qualified name of the schema targeted by this set of mappings N/A First non-null
combine string[] No Array of fully-qualified integration mapping names Specifies the integration mappings to combine with this file Not inherited
import map<string,string> No Keys are alias names, values are fully-qualified integration mapping names Defines aliases for other integration mapping files to which this mapping can refer Merged by key
mappers map<string, Mapper Object> No Keys are the names of the mappers The integration mappers that this mapping defines Merged by key

Mapper object

Property Type Required Format Behavior Combination Style
schemaDefinition string Yes Name of a schema definition that exists in the schema defined by schemaName The name of the schema definition for which this mapper produces output First non-null
root string Yes A type name The root object type that this mapper takes as input. The relative name of the type will be used as the symbol exposed to the path and predicate properties on mapper properties. First non-null
properties map<string, Property Object> No Keys are the names of the properties The set of properties for this mapper. In general, these properties are expected to match exactly the set of properties on the targeted schema definition. Merged by key

Property object

Property Type Required Format Behavior Combination Style
path string Yes Gosu expression
The Gosu expression to evaluate in order to produce the value of the associated schema property. This expression has a single symbol available, whose name is the relative name of the root type and whose type is exactly the root type. The expected return type of this expression depends upon the schema property this mapping property targets:
  • If the schema property is a simple scalar, this expression will return an object that matches the schema property type. The return object is one of the Java inputs for the schema property type.
  • If the schema property is an array of scalars, this expression will return an Iterable object or an array whose elements match the schema property type.
  • If the schema property is an object property, this expression will return an object that is assignable to the root type of the referenced mapper.
  • If the schema property is an object array property, this expression will return an Iterable object or an array whose elements are assignable to the root type of the referenced mapper.
 First non-null
mapper string No Either #/mappers/<name> or <alias>#/mappers/<name> References the mapper to use to produce output if this schema property corresponds to a JSON object or array of JSON objects. This property is required if the referenced schema property is an object or object array property, otherwise it is not allowed First non-null
predicate string No Gosu expression A predicate expression must return a Boolean object value or a boolean primitive value. If the expression is specified and returns false, the path expression is never evaluated. In addition, the path property is treated as if it had evaluated to a null value. The predicate property can be used to guard execution of the path expression. This guarding occurs in cases where the path expression is relevant for only a particular subtype of the root and contains a downcast. First non-null

See also