Supplementing ADAPT Reference Id Mappings with Option for Embedded Resources

[kelly-nelson]

Use Case

To support standalone documents, foreign-key identifier properties in ADAPT objects should allow either an identifier reference or an embedded representation of the related resource. Many integrations exchange single documents containing a small, self-contained set of resources, and requiring all data to be expressed as a fully normalized dataset is not a canonical pattern for API payloads.

Current Processes

We have historically modeled everything by reference in a normalized dataset approach.

Touchpoints

This is a major functional change that will impact the large number of ADAPT components.

Proposed Object Model

Given an object such as this, there are several possibilities:

"products": [
      {
        "brandId": "27",
        "cropId": "25",
        "id": {
          "referenceId": "28"
        },
        "manufacturerId": "26",
        "name": "ABC6789",
        "productFormCode": "SOLID",
        "productTypeCode": "SEED"
      }]

1. Change id properties to ref properties with 2 optional children. BIE authors will select the appropriate item for inclusion. The downside is the redundant nesting of brandRef.brand when used as a resource.

"brandRef":
{
   "id":"27",
   "brand": 
    {
        "id": {
          "referenceId": "27"
        },
       "name": "ABC Seed"
    }
}

2. Model as a Union
   Either
   "brandRef": "27"
   or

"brandRef":
{
       "id": {
          "referenceId": "27"
        },
       "name": "ABC Seed"
}

(Json Schema)

"brandRef": {
  "oneOf": [
    { "$ref": "#/$defs/BrandId" },
    { "$ref": "#/$defs/Brand" }
  ]
}

3. Sideloaded Pattern. While perhaps tempting due to limited changes required, this is a clumsy pattern.

"products": [
      {
        "brandId": "27",
         ...
      }]
"included":[
  "brands": [
           {
             "id": {
                "referenceId": "27"
              },
             "name": "ABC Seed"
      }
   ]
]

[dubnemo]

Or you could use the qualifying term approach, e.g., (qualifier)Name. This is found in a LOT of naming and design rules specifications for other standards:

"products": [
      {
        "brandId": "27",
        "brandName":  "ABC Seed",
        "cropId": "25",
        "cropName": "Corn",
        "id": {
          "referenceId": "28"
        },
        "manufacturerId": "26",
        "manufacturerName": "Seeds R Us",
        "name": "ABC6789",
        "productFormCode": "SOLID",
        "productTypeCode": "SEED"
      }]

or if RESTful with the actual resource on the URL resource name, e.g., /adapt/v3/products

[
      {
        "brandId": "27",
        "brandName":  "ABC Seed",
        "cropId": "25",
        "cropName": "Corn",
        "id": {
          "referenceId": "28"
        },
        "manufacturerId": "26",
        "manufacturerName": "Seeds R Us",
        "name": "ABC6789",
        "productFormCode": "SOLID",
        "productTypeCode": "SEED"
      }]

[jim-wilson-kt]

Kelly will summarize a set of questions intended to inform further discussion.