The Transcode for hierarchical lookups resolves parent lookup values and their dependent child lookup values in a single request. The request groups the child values with their parent values, and the response returns the resolved values in the same structure.

RDM resolves each child value against its parent lookup values. When the request contains values from multiple sources, the RDM tenant configuration property transcodeHierarchyOnSource determines which resolved parents RDM uses for validation. For more information, see Lookups and canonical values.

To return the resolved values in a specific language, set the Accept-Language header in the request.

HTTP method and endpoint

Use the following HTTP method and endpoint path to submit the request:

POST https://{{rdm-service}}/transcode/rdm_tenant_name

The following table describes the endpoint path parameter.

Request headers

The following request headers must be included.

Request body

The request body is a JSON array. Each object in the array pairs a set of parent lookup values with the dependent child lookup values that RDM resolves under those parents.

The following table describes the request body parameters.

Example request

The following example shows how a complete request is structured, including the headers and a JSON body.

The example contains two Country values and two dependent City values. Source A provides France and Paris; Source B provides Japan and Paris. In the lookup data for this example, Paris is a valid child of France, but not of Japan. The result depends on whether transcodeHierarchyOnSource is true or false in the RDM tenant configuration.

POST https://{{rdm-service}}/transcode/rdm_tenant_name
[
  {
    "values": {
      "rdm/lookupTypes/Country": [
        {
          "value": "France",
          "source": "SourceA"
        },
        {
          "value": "Japan",
          "source": "SourceB"
        }
      ]
    },
    "dependentValues": [
      {
        "values": {
          "rdm/lookupTypes/City": [
            {
              "value": "Paris",
              "source": "SourceA"
            },
            {
              "value": "Paris",
              "source": "SourceB"
            }
          ]
        }
      }
    ]
  }
]

Response body

The response returns the resolved parent and child values in the same nested structure as the request. The following table describes the fields returned for each resolved value.

Example response

[
  {
    "values": {
      "rdm/lookupTypes/Country": [
        {
          "code": "FR",
          "value": "France",
          "source": "rdm/sources/SourceA",
          "success": true
        },
        {
          "code": "JP",
          "value": "Japan",
          "source": "rdm/sources/SourceB",
          "success": true
        }
      ]
    },
    "dependentValues": [
      {
        "values": {
          "rdm/lookupTypes/City": [
            {
              "code": "PARIS",
              "value": "Paris",
              "source": "rdm/sources/SourceA",
              "success": true
            },
            {
              "code": "PARIS",
              "value": "Paris",
              "source": "rdm/sources/SourceB",
              "success": true
            }
          ]
        }
      }
    ]
  }
]

[
  {
    "values": {
      "rdm/lookupTypes/Country": [
        {
          "code": "FR",
          "value": "France",
          "source": "rdm/sources/SourceA",
          "success": true
        },
        {
          "code": "JP",
          "value": "Japan",
          "source": "rdm/sources/SourceB",
          "success": true
        }
      ]
    },
    "dependentValues": [
      {
        "values": {
          "rdm/lookupTypes/City": [
            {
              "type": "rdm/lookupTypes/City",
              "code": "PARIS",
              "value": "Paris",
              "source": "rdm/sources/SourceA",
              "success": true
            },
            {
              "type": "rdm/lookupTypes/City",
              "value": "Paris",
              "source": "rdm/sources/SourceB",
              "error": "1003: RDM canonical value mapping not found for value [Paris] and source [SourceB] in tenant [rdm_tenant_name]",
              "success": false
            }
          ]
        }
      }
    ]
  }
]

Error codes and recommended actions

The following table lists the possible error responses returned by this API.