Collection resource properties

When a resource has a property that is a collection, this collection can also be modified. Although making a PATCH request allows to pass only specific properties that need to be changed, passing such a collection property in a PATCH request will replace the entire collection. This means that it is not possible to add/update/remove specific items in the collection.

Taking the Form questions endpoints as an example, a GET /forms/123/questions/456 response might look as follows:

{
  "data": {
    "id": "456",
    "inputType": "SELECT",
    "order": 5,
    "required": true,
    "label": {
      "language": "en",
      "value": "Marital status"
    },
    ...
    "answerOptions": [
      {
        "label": {
          "language": "en",
          "value": "Single"
        },
        "value": "single",
        "externalId": null,
        "order": 0,
        "translations": {
          "label": [
            {
              "language": "en",
              "value": "Single"
            },
            {
              "language": "nl",
              "value": "Alleenstaand"
            }
          ]
        }
      },
      {
        "label": {
          "language": "en",
          "value": "Married"
        },
        "value": "married",
        "externalId": null,
        "order": 1,
        "translations": {
          "label": [
            {
              "language": "en",
              "value": "Married"
            },
            {
              "language": "nl",
              "value": "Getrouwd"
            }
          ]
        }
      }
    ]
  }
}

A PATCH /forms/123/questions/456 request body to make the question optional and add an answer option should be made as follows:

{
  "required": false,
  "answerOptions": [
    {
      "label": {
        "language": "en",
        "value": "Single"
      },
      "value": "single",
      "externalId": null,
      "order": 0,
      "translations": {
        "label": [
          {
            "language": "en",
            "value": "Single"
          },
          {
            "language": "nl",
            "value": "Alleenstaand"
          }
        ]
      }
    },
    {
      "label": {
        "language": "en",
        "value": "Married"
      },
      "value": "married",
      "externalId": null,
      "order": 1,
      "translations": {
        "label": [
          {
            "language": "en",
            "value": "Married"
          },
          {
            "language": "nl",
            "value": "Getrouwd"
          }
        ]
      }
    },
    {
      "label": {
        "language": "en",
        "value": "Widowed"
      },
      "value": "widowed",
      "externalId": null,
      "order": 2,
      "translations": {
        "label": [
          {
            "language": "en",
            "value": "Widowed"
          },
          {
            "language": "nl",
            "value": "Verweduwd"
          }
        ]
      }
    }
  ]
}

Note that even though the first two answer options remained untouched, they still need to be provided in the request because of the behavior of the PATCH operation on collection properties (replacement of the entire collection).