StediDOCS

Mappings

Mappings lets you map JSON documents from one schema to another, using JSONata for its mapping expressions.

Download OpenAPI

List mapping definitions

GET/mappings
Retrieves a list of all mapping definitions in the current account. The current account is determined by the API key passed in the Authorization-header.
Parameters
Optionalquery

Maximum number of mappings that will be returned in a single response. If there are more mappings, the response will contain a field next_page_token that will allow you to retrieve them.

Optionalquery

A token that allows you to retrieve the next page of mappings. It should have the same value as the next_page_token-field you received in your last response.

Optionalquery

If true, each mapping will only contain metadata fields; no mapping expressions, source and target schema, or lookup tables. If false, each mapping will contain all available fields. The metadata fields are id, name, type, created_at, and updated_at.

Example

GET
https://mappings.us.stedi.com/2021-06-01/mappings?page_size=43&page_token=2t7M75ZN1w4OnYFKKT0SUkT95w_ULzPR...&metadata_only=true

Create a mapping definition

POST/mappings
Creates a mapping definition. A mapping definition describes how to turn input JSON into output JSON.
Request body

application/json

Requiredstring
The name of the mapping definition. Each mapping definition in your account must have a unique name.
Requiredstring

The mapping type, which determines the fields that show up in the output.

Mapping typeDescription
only_mapped_keysOutput fields are created based on the mapping expressions only.
merge_with_target_exampleOutput fields are copied from the target example, and created based on the mapping expressions. If both the target example and a mapping expression produce the same field, the field from the mapping expression takes precedence. Providing a target schema with a default document is mandatory.
pass_throughOutput fields are copied from the input, and created based on the mapping expressions. If both the input and a mapping expression produce the same field, the field from the mapping expression takes precedence.

Possible values

only_mapped_keys merge_with_target_example pass_through

OptionalAny

A schema describing the shape of the input JSON. The schema is not used to map documents, but it can provide valuable assistance while writing mapping expressions in the Mappings UI. The schema can include a default document with values that, also, can be helpful while writing mapping expressions. If you don't plan on editing the mapping definition using the UI, there's no benefit to including a source schema.

One of:
jsonschema@2020-12
Requiredstring
The name of the schema. This is a legacy field and has no practical purpose anymore, but the field is required, so it can't be absent, nor can it be an empty string.
Requiredstring

Specifies the format of the schema. Only JSON Schema is supported, so this must be set to jsonschema@2020-12.

This property is a discriminator.

Possible values

jsonschema@2020-12

Requiredstring

A JSON Schema. For example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "quantity": {
      "type": "number"
    },
    "unit_price": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    }
  },
  "default": {
    "quantity": 1,
    "unit_price": 1.00,
    "currency": "USD"
  }
}

The schema must be provided as a string, so in practice, it doesn't look like the above; it looks like this:

"{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"quantity\":{\"type\":\"number\"},\"unit_price\":{\"type\":\"number\"},\"currency\":{\"type\":\"string\",\"minLength\":3,\"maxLength\":3}},\"default\":{\"quantity\":1,\"unit_price\":1,\"currency\":\"USD\"}}"
OptionalAny

A schema describing the shape of the output JSON. The schema is not used to map documents, but in the Mappings UI, you can only write mapping expressions for fields that are present in the target schema.

The schema can include a default document. When mapping_type is set to merge_with_target_example, the values in this document are used as defaults, i.e. if a mapping expressions doesn't produce a value for a given field, the default value is used. For the mapping type merge_with_target_example, providing a target schema with a default document is mandatory. For all other mapping types, the default document is ignored and the entire target schema is optional.

If you don't plan on editing the mapping definition using the UI, and you're using a mapping type other than merge_with_target_example, there's no benefit to including a target schema.

One of:
jsonschema@2020-12
Requiredstring
The name of the schema. This is a legacy field and has no practical purpose anymore, but the field is required, so it can't be absent, nor can it be an empty string.
Requiredstring

Specifies the format of the schema. Only JSON Schema is supported, so this must be set to jsonschema@2020-12.

This property is a discriminator.

Possible values

jsonschema@2020-12

Requiredstring

A JSON Schema. For example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "quantity": {
      "type": "number"
    },
    "unit_price": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    }
  },
  "default": {
    "quantity": 1,
    "unit_price": 1.00,
    "currency": "USD"
  }
}

The schema must be provided as a string, so in practice, it doesn't look like the above; it looks like this:

"{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"quantity\":{\"type\":\"number\"},\"unit_price\":{\"type\":\"number\"},\"currency\":{\"type\":\"string\",\"minLength\":3,\"maxLength\":3}},\"default\":{\"quantity\":1,\"unit_price\":1,\"currency\":\"USD\"}}"
Requiredstring

A JSONata document describing the mapping expressions. For example:

{
  "total": item.quantity * item.unit_price,
  "currency": item.currency,
  "product": product.id
}

The JSONata document must be converted to a string, so in practice, it doesn't look like the above; it looks like this:

"{ \"total\": item.quantity * item.unit_price, \"currency\": item.currency, \"product\": product.id }"
Optionalarray

A list of lookup tables that the mapping expressions in this mapping definition can use.

A lookup table is often used to convert a value from one format to another. For example, you can have a list of currencies with a short name, a full name, and a symbol for each currency, like this:

codefull namesymbol
USDU.S. dollar$
CADCanadian dollar$
EUREuro

In a mapping expression, you can use the $lookupTable function to convert a value from one format to the other.

Array of LookupTable objects.

Example

POST
https://mappings.us.stedi.com/2021-06-01/mappings

Retrieve a mapping definition

GET/mappings/{mapping_id}
Retrieves the mapping definition with the provided ID.
Parameters
Requiredpath
The ID of the mapping definition. The ID is included in the response when you create a mapping definition, or when you retrieve a list of all your mapping definitions.

Example

GET
https://mappings.us.stedi.com/2021-06-01/mappings/01G3VDJ5XFCEGJMGYVP04WC15R

Update a mapping definition

PUT/mappings/{mapping_id}
Replaces the mapping definition with the given ID by the new mapping definition you provide.
Parameters
Requiredpath
The ID of the mapping definition. The ID is included in the response when you create a mapping definition, or when you retrieve a list of all your mapping definitions.
Request body

application/json

Optionalstring
The name of the mapping definition. Each mapping definition in your account must have a unique name.
Optionalstring

The mapping type, which determines the fields that show up in the output.

Mapping typeDescription
only_mapped_keysOutput fields are created based on the mapping expressions only.
merge_with_target_exampleOutput fields are copied from the target example, and created based on the mapping expressions. If both the target example and a mapping expression produce the same field, the field from the mapping expression takes precedence. Providing a target schema with a default document is mandatory.
pass_throughOutput fields are copied from the input, and created based on the mapping expressions. If both the input and a mapping expression produce the same field, the field from the mapping expression takes precedence.

Possible values

only_mapped_keys merge_with_target_example pass_through

OptionalAny

A schema describing the shape of the input JSON. The schema is not used to map documents, but it can provide valuable assistance while writing mapping expressions in the Mappings UI. The schema can include a default document with values that, also, can be helpful while writing mapping expressions. If you don't plan on editing the mapping definition using the UI, there's no benefit to including a source schema.

One of:
jsonschema@2020-12
Requiredstring
The name of the schema. This is a legacy field and has no practical purpose anymore, but the field is required, so it can't be absent, nor can it be an empty string.
Requiredstring

Specifies the format of the schema. Only JSON Schema is supported, so this must be set to jsonschema@2020-12.

This property is a discriminator.

Possible values

jsonschema@2020-12

Requiredstring

A JSON Schema. For example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "quantity": {
      "type": "number"
    },
    "unit_price": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    }
  },
  "default": {
    "quantity": 1,
    "unit_price": 1.00,
    "currency": "USD"
  }
}

The schema must be provided as a string, so in practice, it doesn't look like the above; it looks like this:

"{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"quantity\":{\"type\":\"number\"},\"unit_price\":{\"type\":\"number\"},\"currency\":{\"type\":\"string\",\"minLength\":3,\"maxLength\":3}},\"default\":{\"quantity\":1,\"unit_price\":1,\"currency\":\"USD\"}}"
OptionalAny

A schema describing the shape of the output JSON. The schema is not used to map documents, but in the Mappings UI, you can only write mapping expressions for fields that are present in the target schema.

The schema can include a default document. When mapping_type is set to merge_with_target_example, the values in this document are used as defaults, i.e. if a mapping expressions doesn't produce a value for a given field, the default value is used. For the mapping type merge_with_target_example, providing a target schema with a default document is mandatory. For all other mapping types, the default document is ignored and the entire target schema is optional.

If you don't plan on editing the mapping definition using the UI, and you're using a mapping type other than merge_with_target_example, there's no benefit to including a target schema.

One of:
jsonschema@2020-12
Requiredstring
The name of the schema. This is a legacy field and has no practical purpose anymore, but the field is required, so it can't be absent, nor can it be an empty string.
Requiredstring

Specifies the format of the schema. Only JSON Schema is supported, so this must be set to jsonschema@2020-12.

This property is a discriminator.

Possible values

jsonschema@2020-12

Requiredstring

A JSON Schema. For example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "quantity": {
      "type": "number"
    },
    "unit_price": {
      "type": "number"
    },
    "currency": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    }
  },
  "default": {
    "quantity": 1,
    "unit_price": 1.00,
    "currency": "USD"
  }
}

The schema must be provided as a string, so in practice, it doesn't look like the above; it looks like this:

"{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"quantity\":{\"type\":\"number\"},\"unit_price\":{\"type\":\"number\"},\"currency\":{\"type\":\"string\",\"minLength\":3,\"maxLength\":3}},\"default\":{\"quantity\":1,\"unit_price\":1,\"currency\":\"USD\"}}"
Optionalstring

A JSONata document describing the mapping expressions. For example:

{
  "total": item.quantity * item.unit_price,
  "currency": item.currency,
  "product": product.id
}

The JSONata document must be converted to a string, so in practice, it doesn't look like the above; it looks like this:

"{ \"total\": item.quantity * item.unit_price, \"currency\": item.currency, \"product\": product.id }"
Optionalarray

A list of lookup tables that the mapping expressions in this mapping definition can use.

A lookup table is often used to convert a value from one format to another. For example, you can have a list of currencies with a short name, a full name, and a symbol for each currency, like this:

codefull namesymbol
USDU.S. dollar$
CADCanadian dollar$
EUREuro

In a mapping expression, you can use the $lookupTable function to convert a value from one format to the other.

Array of LookupTable objects.

Example

PUT
https://mappings.us.stedi.com/2021-06-01/mappings/01G3VDJ5XFFZFA104G03ZRQ8YZ

Delete a mapping definition

DELETE/mappings/{mapping_id}
Deletes the mapping definition with the provided ID.
Parameters
Requiredpath
The ID of the mapping definition. The ID is included in the response when you create a mapping definition, or when you retrieve a list of all your mapping definitions.

Example

DELETE
https://mappings.us.stedi.com/2021-06-01/mappings/01G3VDJ5XFWSWVRXCH3HNWRSQX

Map

POST/mappings/{mapping_id}/map
Maps the provided JSON to a different shape according to the specified mapping definition.
Parameters
Requiredpath
The ID of the mapping definition that specifies how to transform the input.
Request body
The body of the request should be the JSON you want to map. It can take any shape as long as it is valid JSON.

application/json

Requiredobject

Example

POST
https://mappings.us.stedi.com/2021-06-01/mappings/01G3VDJ5XFMPCG6NW41NFPF0Z1/map