PATCH requests on list with mutable and immutable properties

[jlnaps]

Current API standards dictate that a PATCH request on an array is a full replacement of that array. We have a use case in our pipeline in which at least one of the properties of our PATCH request body will be a list that contains fields which are a mix of mutable and immutable. For a more concrete example, consider the following object:

{
	"mutablePropertyOne": "My example object",
	"mutablePropertyTwo": "example",
	"partiallyMutableList": [{
			"immutableItemProperty": "STRING",
			"description": "This is a mutable description if immutableNameOne",
			"name": "immutableNameOne"
		},
		{
			"immutableItemProperty": "STRING",
			"description": "This is a mutable description if immutableNameTwo",
			"name": "immutableNameTwo"
		}
	],
	"immutablePropertyOne": {
		"$schema": "my-schema"
	}
}

Deciding how to handle mutablePropertyOne, mutablePropertyTwo, and immutablePropertyOne is simple. The mutable properties will be part of the PATCH request body, and the immutable one will not. The main discussion question comes with how to handle the partiallyMutableList property. We have the following restrictions:

1. Users can not add or subtract elements from the list.
2. name and immutableItemProperty are immutable fields
3. description is mutable

One solution is, we could have our PATCH endpoint still require the full list that would eventually replace partiallyMutableList and then have a variety of validations to make sure that above constraints are met. So a valid example would be

{
	"partiallyMutableList": [{
			"immutableItemProperty": "STRING",
			"description": "My new description",
			"name": "immutableNameOne"
		},
		{
			"immutableItemProperty": "STRING",
			"description": "This is a mutable description if immutableNameTwo",
			"name": "immutableNameTwo"
		}
	]
}

The number of items is the same, the immutable fields allow us to know which item is which, and the changes to the mutable fields can be reflected in the object. This seems verbose though, and I'm not sure if the validations would run afoul of current standards.

It would be nice if there was some way to represent this call without having to provide the full list, but I'm not sure what that would look like, which I why I wanted to bring this issue to the discussion board here. Thanks!

[jlnaps]

It was decided that we will solve this issue using a PATCH call. Should the caller want to change the partially mutable list, we will require them to provide the entire list, as a PATCH of a list is considered a full replace. We will also perform validation on the input to make sure that only fields that are allowed to be changed are modified in the PATCH request.