Expected result and usefulness of /submodels/{submodelIdentifier}/submodel-elements/$value

[mjacoby]

According to Swagger API v3.0.1 the call /submodels/{submodelIdentifier}/submodel-elements/$value returns a page of element values of a Submodel as a JSON array of valueOnly-serialized elements. This does not include the idShorts of the elements and therefore it is unclear how this information is of any value to a user as elements in a submodel are by definition unordered because the user does not know which value belongs to which element.

Example

Submodel S has two properties of type integer P1 and P2.
A call to /submodels/{submodelIdentifier}/submodel-elements/$value, according to the Swagger document, would return

{
	"paging_metadata":
	{
		"cursor": "..."
	},
	"result": [
		42,
		17
	]
}

I would expect the result to contain the idShorts so that the user knows which value belongs to which element

{
	"paging_metadata":
	{
		"cursor": "..."
	},
	"result": [
		{
			"P1": 42
		},
		{
			"P2": 17
		}
	]
}

This behavior would also be in line with the specifiation part 2 (010002-3-0 June 2023), Section 11.4.2 "ValueOnly-Serialization in JSON", which defines that the valueOnly serialization of a property look like this ${Property/idShort}: ${Property/value} where ${Property/value}.

• I have signed the required Developer Certificate of Origin (DCO) already.

[sebbader-sap]

Actually, the following response is expected:

{
	"paging_metadata":
	{
		"cursor": "..."
	},
	"result": [
		{
			"P1": 42,
			"P2": 17
		}
	]
}

[sebbader-sap]

We will provide an example in the https://github.com/admin-shell-io/questions-and-answers, enhanced with additional explanations on the desired responses of ValueOnly calls.

[sebbader-sap]

Generally, this is not a bug but a lack of documentation.

[mjacoby]

If the expected response is as described, this would imply that the OpenAPI definition is incorrect, i.e. this is not only lack of documentation but at least a bug in OpenAPI.

Also all essential information on how valueOnly serialization works should be part of the specification document and not only the https://github.com/admin-shell-io/questions-and-answers page (and within the normative part of the document and not some example section in the annex).