Supplementing ADAPT Reference Id Mappings with Option for Embedded Resources #174
Description
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"
}]
- 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"
}
}
- 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" }
]
}
- 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"
}
]
]