Requirements for the Default Mapping

Model-to-model mapping is ideal if all of the following conditions are true:

  • Your source records are flat JSON; i.e., all source fields are at the root level.
  • The relationship between source fields and entity properties is one-to-one.
  • The source value requires only a simple transformation, such as a simple typecast.

However, even if not all conditions are met, you can still create a mapping in QuickStart to generate your baseline code and then customize it to handle more complex properties and transformations.

Flat JSON Requirement

The following table shows examples of valid and invalid source records. The valid source is a flat JSON hierarchy where id, firstname, and lastname are at the root level. In the invalid source, first and last are nested in an object inside name; therefore, only id can be mapped.

Valid Source JSON (flat) Invalid Source JSON (nested) 
   { "id": 1234,
    "firstname": "John",
    "lastname": "Smith"
  }

   { "id": 1234,
    "name": {
      "first": "John",
      "last": "Smith"
    }
  }

One-to-One Mapping Requirement

Suppose your Order entity represents an order from a customer. An order would have only one customer; therefore, each of the customer-related properties (e.g., id, contactname, companyname, address, phone) would have a one-to-one correspondence with the source fields. This meets the one-to-one requirement for the default mapping.

However, the customer order might include multiple products, which are represented by an array of references to different instances of your Product entity. This is a many-to-one relationship which requires custom mapping code.

Simple Value Transformation Requirement

The default mapping can handle simple transformations, such as a simple type conversion. For example, a string with a numeric value, such as "1234", can be easily converted and assigned to an entity property of type decimal.

However, if a source value requires a more sophisticated transformation, such as date normalization, string concatenation, or a computation, then the code generated from a mapping must be customized to handle these transformations. For example, computing the total amount to bill in an invoice.