PATCH in combintation with content modifiers

[mjacoby]

The API explicitly allows the usage of content modifiers such as $value, $metadata, etc. with HTTP PATCH, for example in the SubmodelServiceSpecification

HTTP PATCH /submodel/submodel-elements/{idShortPath}
HTTP PATCH /submodel/submodel-elements/{idShortPath}/$metadata
HTTP PATCH /submodel/submodel-elements/{idShortPath}/$value

As an HTTP PATCH request typically only contains the properties that should be updated leaving out all other properties, how exactly do these calls differ? The only way this differentiation makes sense that I can think of is if it is required to always send the full object - but this would contradict the fundamental principle of HTTP PATCH (only sending the properties that actually should be updated) and be more in line with HTTP PUT.

Please, either

1. provide a detailed explanation/justification how this is intended to work and why it is in line with the concept of HTTP PATCH, or
2. change HTTP PATCH to HTTP PUT, or
3. disallow the usage of HTTP PATCH im combination with content modifiers, i.e. only keep a single PATCH operation without content modifiers in the path (e.g. HTTP PATCH /submodel/submodel-elements/{idShortPath}). The payload should contain only the properties that should be updated according to JSON Merge Patch.

Personally, I would strongly prefer option 3 as it would allow to minimize the payload while at the same time keep the API small and simple and follow well established patterns and standards.

[x] I have signed the required Developer Certificate of Origin (DCO) already.

[arnoweiss]

I think it'd be elegant to use the $value serialization to update resources. This lowers the required client-side knowledge of the AAS-json-serialization significantly (while introducing some more server-side). I think option 3 would remove functionality from the spec that use-cases have already started implementing against. Options 1 & 2 may be breaking changes but would at least provide backward feature-parity.

[mjacoby]

I agree that updating values using .../$value requires a slightly less verbose payload, e.g. to update a property of type string this would be "newValue" (with value-only serialization) vs. { "value": "newValue" } (with JSON Merge Patch). I also acknowledge that this would be in line with earlier versions of the API (although v3.0 is the only officially released stable version of the API so far).

So a 4th option would be to keep .../$value but make it PUT instead of PATCH, remove other modifiers such as .../$metadata and explicitly specify that PATCH only contains the properties that should be updated as right now such calls take a full version of the element to update which, to my understanding, would require the minimal JSON to update a value to be something like this

{
	"modelType": "Property",
	"idShort": "...",
	"valueType": "xs:string",
	"value": "newValue"
}

Option 1 would of course be backwards compatible because it actually does not change anything. But personally, I don't think that is feasible but maybe I did not fully understand the concept.
Option 2 would also mean a breaking change as the PATCH requests would no longer be supported and removed/replace by PUT.

[BirgitBoss]

We could set #metadata operations in this context to deprecated