Mapping

MappingSchema

A schema for mapping data from one schema to another.

Example

The following mapping:

{
  "id": { "const": "123" },
  "opportunity": {
    "status": {
      "switch": {
        "field": "summary.opportunity_status",
        "case": { "active": "open", "inactive": "closed" },
        "default": "custom"
      }
    },
    "amount": { "field": "summary.opportunity_amount" }
  }
}

Will translate the following input:

{
  "id": "123",
  "summary": {
    "opportunity_status": "active",
    "opportunity_amount": 100
  }
}

To the following output:

{
  "id": "123",
  "opportunity": {
    "status": "open",
    "amount": 100
  }
}

Formats

A JSON example of this model.

{
  "id": { "const": "123" },
  "opportunity": {
    "status": {
      "switch": {
        "field": "summary.opportunity_status",
        "case": { "active": "open", "inactive": "closed" },
        "default": "custom"
      }
    },
    "amount": { "field": "summary.opportunity_amount" }
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: MappingSchema.yaml
type: object
properties: {}
unevaluatedProperties:
  anyOf:
    - $ref: MappingFunction.yaml
    - $ref: MappingSchema.yaml
examples:
  - id: {}
    opportunity:
      status: {}
      amount: {}
  - opportunity:
      status: {}
      amount: {}
  - opportunityAmount: {}
    opportunityStatus: {}
  - id: {}
    opportunity:
      status: {}
      amount: {}
  - id: {}
    opportunityStatus: {}
    opportunityAmount: {}
description: |-
  A mapping format for translating data from one schema to another.

  Example:

  The following mapping:

  ```json
  {
    "id": { "const": "123" },
    "opportunity": {
      "status": {
        "switch": {
          "field": "summary.opportunity_status",
          "case": { "active": "open", "inactive": "closed" },
          "default": "custom",
        },
      },
      "amount": { "field": "summary.opportunity_amount" },
    }
  }
  ```

  Will translate the following data:

  ```json
  {
    "id": "123",
    "summary": {
      "opportunity_status": "active",
      "opportunity_amount": 100,
    },
  }
  ```

  To the following data:

  ```json
  {
    "id": "123",
    "opportunity": { "status": "open", "amount": 100 },
  }
  ```

The TypeSpec code for this model.

@example(Examples.Mapping.withLiteralValues)
@Versioning.added(CommonGrants.Versions.v0_2)
model MappingSchema {
  ...Record<MappingFunction | MappingSchema>;
}

MappingFunction

A function for mapping data from one schema to another.

Sub-types

Sub-type	Description
MappingConstantFunction	Returns a constant value.
MappingFieldFunction	Returns the value of a field in the source data.
MappingSwitchFunction	Returns a new value based on the value of a field in the source data using a switch-case lookup.

Formats

A JSON example of this model.

{
  "id": {"const": "123"},
  "name": {
    "firstName": {"field": "first_name"},
    "lastName": {"field": "last_name"},
  },
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: MappingFunction.yaml
anyOf:
  - $ref: MappingConstantFunction.yaml
  - $ref: MappingFieldFunction.yaml
  - $ref: MappingSwitchFunction.yaml
examples:
  - switch:
      field: summary.opportunity_status
      case:
        active: open
        inactive: closed
      default: custom
  - field: summary.opportunity_amount
  - const: "123"
description: The set of supported mapping functions.

The TypeSpec code for this model.

/** The set of supported mapping functions. */
@example(Examples.Mapping.constId)
@example(Examples.Mapping.amountField)
@example(Examples.Mapping.statusSwitch)
@Versioning.added(CommonGrants.Versions.v0_2)
union MappingFunction {
  `const`: MappingConstantFunction,
  field: MappingFieldFunction,
  switch: MappingSwitchFunction,
}

MappingConstantFunction

Returns a constant value.

Table

Property	Type	Description
const	string	A constant value to add to the mapping.

Formats

A JSON example of this model.

{
  "const": "123",
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: MappingConstantFunction.yaml
type: object
properties:
  const: {}
required:
  - const
unevaluatedProperties:
  not: {}
examples:
  - const: "123"
description: Returns a constant value.

The TypeSpec code for this model.

/** Returns a constant value. */
@example(Examples.Mapping.constId)
@Versioning.added(CommonGrants.Versions.v0_2)
model MappingConstantFunction {
  `const`: unknown;
}

MappingFieldFunction

Returns the value of a field in the source data.

Table

Property	Type	Description
field	string	A dot-separated path to a field in the source schema whose value will be added to the mapping.

Formats

A JSON example of this model.

{
  "field": "opportunity_status",
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: MappingFieldFunction.yaml
type: object
properties:
  field:
    type: string
required:
  - field
unevaluatedProperties:
  not: {}
examples:
  - field: summary.opportunity_amount
description: Returns the value of a field in the source data.

The TypeSpec code for this model.

/** Returns the value of a field in the source data. */
@example(Examples.Mapping.amountField)
@Versioning.added(CommonGrants.Versions.v0_2)
model MappingFieldFunction {
  field: string;
}

MappingSwitchFunction

Returns a new value based on the value of a field in the source data using a switch-case lookup.

Table

Property	Type	Required	Description
switch	object	Yes	The switch configuration object containing field, case, and optional default.

Where the switch configuration object has the following properties:

Property	Type	Required	Description
field	string	Yes	A dot-separated path to a field in the source schema whose value will be used for switching.
case	Record<unknown>	Yes	A mapping of source field values to desired output values.
default	unknown	No	The default value to output if no case matches the source field value.

Formats

A JSON example of this model.

{
  "switch": {
    "field": "opportunity_status",
    "case": {
      "active": "open",
      "inactive": "closed"
    },
    "default": "custom"
  }
}

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: MappingSwitchFunction.yaml
type: object
properties:
  switch:
    type: object
    properties:
      field:
        type: string
        description: The field in the source data to switch on.
      case:
        $ref: "#/$defs/RecordUnknown"
        description: An object mapping source field values to desired output values.
      default:
        description: The default value to output if no case matches the source field value.
    required:
      - field
      - case
    unevaluatedProperties:
      not: {}
required:
  - switch
unevaluatedProperties:
  not: {}
examples:
  - switch:
      field: summary.opportunity_status
      case:
        active: open
        inactive: closed
      default: custom
description: Returns a new value based on the value of a field in the source data using a switch statement.
$defs:
  RecordUnknown:
    type: object
    properties: {}
    unevaluatedProperties: {}

The TypeSpec code for this model.

/** Returns a new value based on the value of a field in the source data using a switch statement. */
@example(Examples.Mapping.statusSwitch)
@Versioning.added(CommonGrants.Versions.v0_2)
model MappingSwitchFunction {
  switch: {
    /** The field in the source data to switch on. */
    field: string;

    /** An object mapping source field values to desired output values. */
    case: Record<unknown>;

    /** The default value to output if no case matches the source field value. */
    default?: unknown;
  };
}