Using the Submodel Repository#
This walkthrough creates a motor nameplate Submodel, works with Submodel Elements and a File attachment, changes metadata and values, and lists Submodels with filters and pagination. You will then remove the example data.
The examples use the unsecured Docker Compose setup at http://localhost:8085 with an empty context path. Run them in order against an empty example database. Save the JSON files in your working directory. The curl commands are single-line commands usable in Bash. In Windows PowerShell, invoke curl.exe instead of curl.
You need only the Submodel Repository and the database services from Setup. A separate AAS Repository or Registry is not required for these examples.
Create a Submodel#
Save this as submodel.json:
{
"modelType": "Submodel",
"id": "urn:example:submodel:1",
"idShort": "MotorNameplate",
"semanticId": {
"type": "ExternalReference",
"keys": [
{ "type": "GlobalReference", "value": "urn:example:semantic:nameplate" }
]
},
"submodelElements": [
{
"modelType": "Property",
"idShort": "ManufacturerName",
"valueType": "xs:string",
"value": "Example Motors"
},
{
"modelType": "SubmodelElementCollection",
"idShort": "Nameplate",
"value": [
{
"modelType": "Property",
"idShort": "SerialNumber",
"valueType": "xs:string",
"value": "SN-001"
}
]
}
]
}
curl -i -X POST http://localhost:8085/submodels -H 'Content-Type: application/json' --data-binary '@submodel.json'
Expect 201 Created and a JSON body containing id: "urn:example:submodel:1" and idShort: "MotorNameplate". The Submodel is now stored in the Repository. Generating a Registry descriptor requires Registry Integration or explicit registration; neither is needed to continue here.
If you repeat this step, 409 Conflict means a Submodel with the same id already exists. Continue with that resource only if it is your earlier example, or use different identifiers consistently throughout the walkthrough.
Retrieve and Replace the Submodel#
The request URL uses the encoded Submodel identifier, not its idShort or semantic identifier:
Original identifier |
Base64URL path value |
|---|---|
|
|
|
|
Path identifiers use Base64URL encoding of the identifier’s UTF-8 bytes. BaSyx Go accepts valid padded and unpadded Base64URL values. The examples below use the unpadded form. The same rule applies to Base64URL-encoded filters such as semanticId. Identifiers in JSON request bodies remain unencoded. The example values above are already substituted into every URL.
curl -i http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ
Expect 200 OK and the Submodel. Change idShort in submodel.json to MotorNameplateUpdated, then submit the complete document:
curl -i -X PUT http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ -H 'Content-Type: application/json' --data-binary '@submodel.json'
Expect 204 No Content for replacement. Verify it:
curl -i http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ
The response should now contain "idShort": "MotorNameplateUpdated" and the original elements. PUT creates a missing Submodel with 201 Created. The body’s id must match the decoded path identifier; a mismatch returns 400 Bad Request.
PUT replaces the complete Submodel. Later in this walkthrough you will change elements through separate API calls. Those calls do not update your local submodel.json. Before replacing the Submodel again, retrieve its current state and preserve the elements, values, and metadata you want to keep. Reusing the initial file would undo those later changes.
Submodel Element Paths#
The Submodel identifier is encoded; idShortPath is not. Use dot-separated names to address nested elements:
Path |
Target |
|---|---|
|
Top-level Property in this example. |
|
Top-level collection. |
|
Property inside that collection. |
|
First member of a list named |
List indices are zero-based and can change when list content changes. List members are addressed by index rather than their own idShort. Apply normal URL escaping to path characters when constructing requests. With curl, use --globoff when a URL contains list brackets so curl does not interpret them as a URL range.
curl -i http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber
Expect 200 OK and the Property, including modelType, idShort, valueType, and value.
Create, Replace, and Delete an Element#
Save this as property.json:
{
"modelType": "Property",
"idShort": "ProductCode",
"valueType": "xs:string",
"value": "MOTOR-100"
}
Add it at the top level:
curl -i -X POST http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements -H 'Content-Type: application/json' --data-binary '@property.json'
Expect 201 Created and the element. To add a child to an existing collection instead, POST to the collection’s path, for example /submodel-elements/Nameplate, with a child element body.
Change value in property.json to MOTOR-200 and replace the top-level Property:
curl -i -X PUT http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/ProductCode -H 'Content-Type: application/json' --data-binary '@property.json'
curl -i http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/ProductCode
Expect 204 No Content for replacement, then 200 OK with the new value. Preserve the addressed element’s idShort and supply the complete element. PUT can create a missing element when its parent exists; use POST to the parent when adding a new child explicitly.
curl -i -X DELETE http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/ProductCode
Expect 204 No Content; a subsequent GET of that element returns 404. Other elements remain available.
File Attachments#
File Submodel Elements provide a separate /attachment resource for their content. Create the File element first. Save this as manual-file.json:
{
"modelType": "File",
"idShort": "Manual",
"contentType": "application/pdf",
"value": ""
}
curl -i -X POST http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements -H 'Content-Type: application/json' --data-binary '@manual-file.json'
Place a file named manual.pdf in the working directory, then upload it as multipart form data:
curl -i -X PUT http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Manual/attachment -F 'file=@manual.pdf;type=application/pdf'
Expect 204 No Content. The stored file name comes from the filename parameter of the file part’s Content-Disposition header, which curl sets from the uploaded file. A separate fileName form field is not read. An upload without a file name keeps the previously stored name, or else is named after the element’s idShort (file for a list member) with an extension matching the content type, for example Manual.pdf. Download the stored content with GET on the same attachment resource:
curl --fail-with-body --output downloaded-manual.pdf http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Manual/attachment
Delete the attachment content when it is no longer needed:
curl -i -X DELETE http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Manual/attachment
Expect 200 OK. The File element remains, but its value is empty and a later attachment download returns 404 Not Found.
If a File element’s value starts with http:// or https://, GET on its /attachment resource returns 302 Found with that URL in the Location header instead of locally stored content. A client may follow that redirect to retrieve the remote file.
Representations and Partial Updates#
See Response Representations for the meaning of each suffix and the supported depth and Blob modifiers. The following examples show the Submodel-specific request and response shapes.
These representations have distinct schemas. Do not send a normal Property object to a value-only endpoint. For example:
curl -i 'http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber/$value'
curl -i 'http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/$metadata'
curl -i 'http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/$reference'
curl -i 'http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/$path'
The first request returns the JSON string "SN-001". Save the new value as serial-value.json:
"SN-002"
curl -i -X PATCH 'http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber/$value' -H 'Content-Type: application/json' --data-binary '@serial-value.json'
Expect 204 No Content. GET the normal Property again: value is now SN-002, while idShort and valueType are retained. This changes the existing value without replacing the collection or Submodel.
ValueOnly PATCH validates the complete payload before applying changes. See ValueOnly Types and Validation for accepted values and error responses. To prevent overwriting another client’s changes, send the resource’s ETag in If-Match; see Conditional Requests.
To update metadata, save this as serial-metadata.json:
{
"modelType": "Property",
"idShort": "SerialNumber",
"description": [
{ "language": "en", "text": "Manufacturer-assigned serial number" }
]
}
curl -i -X PATCH 'http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ/submodel-elements/Nameplate.SerialNumber/$metadata' -H 'Content-Type: application/json' --data-binary '@serial-metadata.json'
Expect 204 No Content. The normal Property now includes the description and retains the previously stored SN-002 value and xs:string datatype. Fields omitted from a $metadata PATCH, the element’s value, and its children remain unchanged. modelType is required and must match the stored element.
Besides the common metadata fields, a $metadata PATCH accepts the type-specific fields of the Part 2 metadata schemas:
Element type |
Additional fields |
|---|---|
|
|
|
|
|
|
Other fields are rejected with 400 Bad Request. A valueType that the stored value cannot be converted to is rejected as well. The updated element is verified according to the configured verification mode, including its list members or enclosing list.
PATCH on normal, metadata, and value endpoints expects the corresponding representation, not an RFC 6902 array of op/path instructions. Use element creation routes to add elements, complete PUT bodies to replace resources, and the relevant PATCH representation to update existing content. A $metadata update changes metadata while retaining values. Follow its schema in Swagger rather than including value fields in that payload.
For container-like elements, a normal PATCH that includes the child-bearing field replaces the stored child list: omitted children are removed, and an empty list removes all children. This applies to value for SubmodelElementCollection and SubmodelElementList, statements for Entity, and annotations for AnnotatedRelationshipElement. If the PATCH omits the applicable child-bearing field, existing children remain unchanged. A $metadata PATCH changes metadata without replacing child content.
See Response Representations for the shared meaning of level and extent. For example:
curl -i -G http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ --data-urlencode 'level=deep' --data-urlencode 'extent=withoutBlobValue'
Keep URLs containing $value, $metadata, $reference, or $path in single quotes so the shell does not expand the dollar sign.
Filtering and Pagination#
See Pagination for limit, cursor handling, and the shared response structure. The examples below show this component’s requests and filters.
Create a Second Submodel#
Add a second Submodel so you can try pagination with two resources. Save this as second-submodel.json:
{
"modelType": "Submodel",
"id": "urn:example:submodel:2",
"idShort": "PumpNameplate"
}
curl -i -X POST http://localhost:8085/submodels -H 'Content-Type: application/json' --data-binary '@second-submodel.json'
Expect 201 Created. Your example database now contains MotorNameplateUpdated and PumpNameplate.
Read One Submodel per Page#
Request the collection without filters so both Submodels are eligible. Set limit=1 to return at most one Submodel in each response:
curl -i -G http://localhost:8085/submodels --data-urlencode 'limit=1'
Expect 200 OK. The body contains one Submodel in result and a non-empty paging_metadata.cursor indicating that another page is available. A Submodel without elements, such as PumpNameplate, is returned without submodelElements. Copy that cursor string into the next request:
curl -i -G http://localhost:8085/submodels --data-urlencode 'limit=1' --data-urlencode 'cursor=RETURNED_CURSOR'
Replace RETURNED_CURSOR with the value from the first response, without its surrounding JSON quotes. In a database containing only these two Submodels, the second response contains the other Submodel and has no next cursor. If additional Submodels exist, keep following the returned cursor until none is supplied.
See Limit and Cursor for the general rules when adapting this example.
Filter the Collection#
Now select only the motor nameplate Submodel by its short name:
curl -i -G http://localhost:8085/submodels --data-urlencode 'idShort=MotorNameplateUpdated'
Expect 200 OK with only MotorNameplateUpdated in result. PumpNameplate does not match the filter. There is no need to force pagination for this single match.
Parameter |
Meaning |
|---|---|
|
Plain short-name filter. |
|
Base64URL-encoded semantic key-value string matched against |
|
Page size and continuation cursor. |
|
RFC 3339 lower bounds on administrative creation/update timestamps. |
|
Representation controls described below. |
For the example’s semantic identifier, encode the string urn:example:semantic:nameplate, not the complete reference JSON:
curl -i -G http://localhost:8085/submodels --data-urlencode 'semanticId=dXJuOmV4YW1wbGU6c2VtYW50aWM6bmFtZXBsYXRl'
The decoded value is compared with individual semanticId.keys[].value entries, not with the complete multi-key reference.
Timestamp filters use administration.createdAt and administration.updatedAt supplied in the resource payload, rather than automatically recording each write. The example does not supply them. Maintain those fields if using timestamp-filtered lists; current-resource lists do not provide deletion notifications.
Structured Queries#
Use POST /query/submodels when the predefined list filters are not sufficient. Structured queries can combine conditions and filter on Submodel content, including Submodel Element values. Query results use the same limit parameter and cursor-based pagination as other collection requests.
See the shared Query Language for conditions, operators, $sm and $sme fields, fragment filters, and matching semantics. Use the running Swagger UI for the operation contract. Adding arbitrary field names as list query parameters does not create a structured query.
Invoke an Operation#
Storing a Submodel Element with modelType: Operation defines the operation and its variables; it does not supply executable behavior. Invocation requires an invocationDelegation qualifier that identifies a reachable delegation endpoint and an explicit trust configuration for that destination.
Use /invoke for a synchronous response or /invoke-async to receive a status location and later retrieve the result. The Operation Invocation and Delegation guide configures the trust boundary and demonstrates both routes with 5 + 3 = 8.
Delete the Example Content#
Once you have finished, delete both example Submodels. If continuing with the AAS Repository walkthrough, postpone deleting the motor nameplate until you finish using it. Consider every AAS/client that uses the same identifier before deleting shared content.
curl -i -X DELETE http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ
curl -i -X DELETE http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6Mg
Expect 204 No Content for each existing Submodel. Deleting a Submodel also deletes its contained elements. Verify the motor nameplate is no longer available:
curl -i http://localhost:8085/submodels/dXJuOmV4YW1wbGU6c3VibW9kZWw6MQ
The expected 404 Not Found confirms deletion. The example identifiers can now be used for a fresh walkthrough.