Mapping

MappingSchema

A schema for mapping data from one schema to another.

A JSON example of this model.

{
  "id": {"const": "123"},
  "name": {
    "firstName": {"field": "first_name"},
    "lastName": {"field": "last_name"},
  },
  "opportunity": {
    "status": {
      "switch": {
        "field": "opportunity_status",
        "case": {
          "active": "open",
          "inactive": "closed",
        }
      }
    },
    "amount": {"field": "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
    - {}
examples:
  - id: {}
    opportunity:
      status:
        switch:
          field: opportunity_status
          case:
            active: open
            inactive: closed
          default: custom
      amount:
        field: opportunity_amount
  - opportunity:
      status:
        switch:
          field: opportunity_status
          case:
            active: open
            inactive: closed
          default: custom
        amount:
          field: opportunity_amount
  - opportunityAmount: {}
    opportunityStatus:
      switch:
        field: opportunity_status
        case:
          active: open
          inactive: closed
        default: custom
  - id: {}
    opportunity:
      status:
        field: opportunity_status
      amount:
        field: opportunity_amount
  - opportunityStatus: {}
    opportunityAmount: {}
description: |-
  A mapping schema for translating data from one schema to another.

  Example:

  The following mapping:

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

  Will translate the following data:

  ```json
  {
    "id": "123",
    "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)
model MappingSchema {
  ...Record<MappingFunction | unknown>;
}

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
description: The set of supported mapping functions.

The TypeSpec code for this model.

/** The set of supported mapping functions. */
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
description: Returns a constant value.

The TypeSpec code for this model.

/** Returns a constant value. */
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
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. */
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	Description
field	string	A dot-separated path to a field in the source schema whose value will be added to the mapping.
case	Record<unknown>	A mapping of source field values to desired output values.
default	unknown	The default value to output if no case matches the source field value.

Formats

A JSON example of this model.

{
  "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:
  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
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. */
model MappingSwitchFunction {
  /** 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;
}