Response Representations#
BaSyx Go Repository APIs expose different views of the same model content through distinct endpoints. A normal read uses the resource endpoint without a representation suffix. The other representations append /$value, /$metadata, /$reference, or /$path. Query parameters such as level and extent modify supported responses but do not select a representation.
Representation Overview#
Representation |
What you get |
|---|---|
Normal |
Complete model JSON for the resource, including metadata and values. |
|
ValueOnly content: a scalar for a simple Property and structured JSON for complex elements. |
|
Model structure and metadata with runtime values omitted according to the metadata rules. |
|
An AAS Reference identifying the resource instead of the resource itself. |
|
An array of paths addressing the resource and its contained elements. |
The standalone Submodel Repository exposes these representations for Submodels and Submodel Elements, on both collection and single-resource operations where defined by its API. The AAS Repository exposes the same Submodel behavior through AAS-scoped routes, and the AAS Environment exposes both AAS-scoped and /submodels route forms. An AAS itself has normal and $reference reads, not every Submodel representation. Registry descriptors do not use these Repository representation routes.
Representation support depends on the operation and resource type. Check the deployed component’s Swagger UI before adding a suffix to an endpoint.
One Resource in Different Representations#
The following examples use Submodel urn:example:submodel:1, whose Base64URL path value is dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ. It contains this small Nameplate collection:
{
"modelType": "SubmodelElementCollection",
"idShort": "Nameplate",
"value": [
{
"modelType": "Property",
"idShort": "SerialNumber",
"valueType": "xs:string",
"value": "SN-12345"
},
{
"modelType": "Property",
"idShort": "ManufacturerName",
"valueType": "xs:string",
"value": "Example Motors"
}
]
}
Set ${BASE_URL} to the root URL of a Submodel Repository or AAS Environment that exposes the /submodels routes. For an AAS-scoped route, insert /shells/{aasIdentifier} before /submodels.
Normal Representation#
GET ${BASE_URL}/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber
The normal response is the complete Property model:
{
"idShort": "SerialNumber",
"modelType": "Property",
"valueType": "xs:string",
"value": "SN-12345"
}
$value#
GET ${BASE_URL}/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber/$value
For this Property, the ValueOnly response is a JSON string:
"SN-12345"
$value reduces the AAS model structure and focuses on values. It is not always a scalar: collections, lists, ranges, files, blobs, and other complex elements have structured ValueOnly JSON.
ValueOnly Types and Validation#
Property values and Range bounds use the JSON types defined by their stored valueType:
Stored type or value |
ValueOnly JSON |
|---|---|
Numeric XSD type, such as |
Number, for example |
|
Boolean, for example |
Other XSD types, including |
String. |
Property without a value, addressed directly or as a list member |
|
|
String, because it has no valid JSON number/boolean representation. |
Normal model JSON uses lexical strings: an xs:integer Property with "value": "42" reads as 42 through $value. Preserve numeric precision when parsing large numbers.
Elements and optional fields without a value are omitted instead of being returned as null or empty values. This applies to members of Submodels, collections, Entity statements, and annotations, to the Submodel Element listing, to Operation result arguments, and to fields such as an unset Range bound or a Blob’s contentType. SubmodelElementList members are always kept so that indices match the normal representation. Operations and Capabilities have no ValueOnly form: they are omitted, and a list that contains them is omitted as a whole.
A $value PATCH validates the complete payload against the stored element types before writing. Numeric and boolean types also accept valid lexical strings such as "42" or "true". Other types require strings. Invalid values, incompatible JSON types, and unsupported fields in an element’s ValueOnly object return 400 Bad Request. Nonexistent elements return 404 Not Found. Use creation routes to add them.
Omitted members remain unchanged. null clears a Property value, a Range bound, or the reference of a ReferenceElement. For an existing numeric Range, {"min": null, "max": 42} clears its lower bound and sets its upper bound.
$metadata#
GET ${BASE_URL}/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber/$metadata
The metadata response retains the Property’s model information but omits its runtime value:
{
"idShort": "SerialNumber",
"modelType": "Property",
"valueType": "xs:string"
}
A Submodel Element’s metadata contains only the fields of the Part 2 metadata schema for its type. Child elements of collections, lists, Entities, and annotated relationships are not included, and neither are value fields such as valueId, contentType, first, second, observed, entityType, globalAssetId, specificAssetIds, or Operation variables. GET .../submodel-elements/$metadata therefore returns only top-level elements.
$reference#
GET ${BASE_URL}/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber/$reference
The response is a ModelReference to the Property, including the containing Submodel and collection:
{
"type": "ModelReference",
"keys": [
{
"type": "Submodel",
"value": "urn:example:submodel:1"
},
{
"type": "SubmodelElementCollection",
"value": "Nameplate"
},
{
"type": "Property",
"value": "SerialNumber"
}
]
}
Each key uses the model type of the element it refers to. The key of a SubmodelElementList member therefore has the member’s type, such as Property or SubmodelElementCollection, and its index as value.
$path#
Use level=deep on the collection to include its descendants:
GET ${BASE_URL}/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate/$path?level=deep
The response is an array of addressable idShort paths. It includes the requested collection itself, followed by its descendants in path order:
[
"Nameplate",
"Nameplate.ManufacturerName",
"Nameplate.SerialNumber"
]
These entries identify elements. They are not AAS model objects or References. With level=core, the response contains the path of the requested element and of its direct children.
Depth and Blob Content#
Where the read operation exposes them:
Modifier |
Effect |
|---|---|
|
Include nested content. |
|
Include only direct children. A Submodel or list of Submodels contains its top-level elements without their children; in |
|
Omit Blob payload values. |
|
Include Blob payload values. |
These modifiers change the response, not the stored resource. extent only controls inline Blob values. It does not include the binary content referenced by a File element. Retrieve that content through the corresponding /attachment endpoint.
Encode a Blob’s binary content as a standard Base64 string in the JSON value field when creating or updating it.
Writing Representations#
For Submodel and Submodel Element operations, the request body format depends on the endpoint you call.
Representation |
Write operations |
Request body |
|---|---|---|
Normal |
|
Normal Submodel or Submodel Element representation |
|
|
Submodel or Submodel Element metadata representation |
|
|
Submodel or Submodel Element ValueOnly representation |
|
None |
Read-only |
|
None |
Read-only |
Normal POST endpoints create resources. On the Submodel and Submodel Element by-identifier or by-path endpoints, PUT uses the complete normal representation and creates a missing resource or replaces an existing one. A $value or $metadata response is not a complete request body for a normal PUT.
PATCH performs a partial update using the representation of its endpoint. The normal endpoint accepts fields from the normal model representation, /$metadata accepts the metadata representation, and /$value accepts ValueOnly content. For example, these Submodel Element routes have different request schemas:
PATCH .../submodel-elements/{idShortPath}
PATCH .../submodel-elements/{idShortPath}/$metadata
PATCH .../submodel-elements/{idShortPath}/$value
For a normal Submodel Element PATCH, supplying a container’s child-bearing field replaces its stored children rather than merging them. This applies to value for SubmodelElementCollection and SubmodelElementList, statements for Entity, and annotations for AnnotatedRelationshipElement: omitted children are removed, and an empty array removes all children. If the request omits the child-bearing field, existing children remain unchanged. A $metadata PATCH does not replace child content.
BaSyx Submodel PATCH endpoints use partial AAS representations, not RFC 6902 JSON Patch documents. Send the fields to update in the representation expected by the endpoint instead of an array of op, path, and value operations.
Write support and field-level restrictions are operation-specific. Check the running Swagger UI for the exact request schema and see Submodel Repository Usage for concrete PATCH examples.