Query Language#
BaSyx Go supports the AAS Query Language defined by IDTA-01002 v3.2 for selecting repository resources and Registry descriptors and filtering fragments inside returned objects. This page covers the BaSyx Go extensions and deviations from the standard. Use the component’s Swagger UI to check endpoint availability, URL parameters, and general request and response shapes. Use this page for the runtime-specific query grammar and semantics.
Supported Endpoints#
Component |
Endpoint |
Returned object |
Valid field roots |
|---|---|---|---|
AAS Repository |
|
Asset Administration Shell |
|
AAS Environment |
|
Asset Administration Shell |
|
Submodel Repository and AAS Environment |
|
Submodel |
|
AAS Registry, Digital Twin Registry, and AAS Environment |
|
AAS Descriptor |
|
Submodel Registry and AAS Environment |
|
Submodel Descriptor |
|
Concept Description Repository and AAS Environment |
|
Concept Description |
|
The standalone AAS Repository rejects $sm and $sme fields on /query/shells with 400 Bad Request. Only the AAS Environment follows the candidate AAS’s model references into locally stored Submodels and Submodel Elements. Registry roots address descriptors, not Repository resources: $aasdesc is not interchangeable with $aas, and $smdesc is not interchangeable with $sm.
The Digital Twin Registry exposes the same /query/shell-descriptors language as the standalone AAS Registry.
Query Structure#
Every request requires a top-level $condition. It determines which parent objects appear in result. Optional $filters entries control fragments inside those returned objects. A fragment is a nested part of a returned resource, such as a field, contained object, or entry in a list. Fragment filters control whether those nested parts are retained in the returned representation. They do not determine whether the parent resource itself appears in result.
{
"$condition": {
"$eq": [
{ "$field": "$aas#idShort" },
{ "$strVal": "MotorAAS" }
]
}
}
Each $filters entry requires both $fragment and $condition. The standard defines only those members. BaSyx Go additionally supports a Boolean $match extension for row-local fragment filtering. This flag is distinct from the logical $match expression used inside $condition:
{
"$condition": { "$boolean": true },
"$filters": [
{
"$fragment": "$sm#supplementalSemanticIds[]",
"$match": true,
"$condition": {
"$eq": [
{ "$field": "$sm#supplementalSemanticIds[].keys[].value" },
{ "$strVal": "urn:example:semantic:public" }
]
}
}
]
}
Unknown members, a missing $condition, malformed expressions, unsupported field paths, and roots that are invalid for the endpoint result in 400 Bad Request.
Omit $select to return objects, or use Identifier Projection to return identifiers. $filters serve a different purpose: they conditionally retain or prune supported fragments.
For example, query a local AAS Repository for shells whose idShort is MotorAAS:
curl -sS -X POST 'http://localhost:8084/query/shells?limit=1' -H 'Content-Type: application/json' -d '{"$condition":{"$eq":[{"$field":"$aas#idShort"},{"$strVal":"MotorAAS"}]}}'
A successful response uses the endpoint’s normal paging envelope:
{
"paging_metadata": {},
"result": [
{
"modelType": "AssetAdministrationShell",
"id": "urn:example:aas:motor",
"idShort": "MotorAAS",
"assetInformation": { "assetKind": "Instance" }
}
]
}
Fields#
Field Roots#
The root identifies the model being addressed:
Root |
Refers to |
|---|---|
|
An Asset Administration Shell |
|
A Submodel |
|
A Submodel Element |
|
An AAS Descriptor, including paths into its embedded Submodel Descriptors |
|
A Submodel Descriptor |
|
A Concept Description |
Field Paths#
A field reference uses $field and separates its model selector from its field with #. See the specification’s Identification of Fields for the standard notation. Examples:
$aas#assetInformation.globalAssetId
$sm#semanticId.keys[].value
$sme#value
$sme.Metrics.Temperature#value
$aasdesc#submodelDescriptors[].idShort
$smdesc#endpoints[0].protocolinformation.href
$cd#idShort
Use dots for nested object members. For supported list paths, [] addresses any entry and [0], [1], and so on address one zero-based position. The part between $sme. and # is the dot-separated idShort path of the element and may also contain list selectors. Omitting that path, as in $sme#value, searches matching Submodel Elements recursively across the relevant Submodel Element hierarchy. $sme.Metrics.Temperature#value targets the explicit path.
Field names and roots are case-sensitive. For descriptor endpoint URLs, the query token is protocolinformation.href with a lowercase i, even though the regular AAS JSON property is protocolInformation. The accepted paths are an explicit subset of the model, so a field that exists in an AAS JSON document is not automatically queryable.
Values and Types#
Values are typed expressions rather than bare JSON scalars:
Expression |
Value |
|---|---|
|
String |
|
Number |
|
Boolean; it can also be a complete condition |
|
RFC 3339 date-time |
|
RFC 3339 full-time |
|
Uppercase hexadecimal literal |
Note
The AAS metamodel uses the XML Schema types xs:dateTime and xs:time, which also allow values without a time zone; see the AAS data types. BaSyx Go query literals $dateTimeVal and $timeVal use RFC 3339 formats instead: seconds and an explicit time zone (Z or an offset such as +01:00) are required, and fractional seconds are supported. Date-time literals also require the T separator. For example, 2026-01-15T10:30:00 and 10:30:00 are rejected because they omit the time zone.
The language also provides explicit cast and date-part expressions:
Expression |
Accepted operand |
|---|---|
|
Any valid value expression |
|
A string-valued expression, including a field, string literal, or |
|
A string-valued or date-time expression |
|
A date-time expression, such as |
For example:
{
"$lt": [
{ "$numCast": { "$field": "$sme.Temperature#value" } },
{ "$numVal": 48 }
]
}
Implicit casting of field operands is part of the standard AAS Query Language. BaSyx Go enables it by default with general.enableImplicitCasts: true, converting a field operand to the type of the other operand where the conversion is supported. In the example above, $numCast can therefore be omitted: comparing the field directly with $numVal automatically applies the numeric cast. Explicit casts make the intended interpretation clear and remain useful when general.enableImplicitCasts is false.
The public query language has no null or list literal and no dedicated membership operator.
Conditions and Operators#
Every expression object contains exactly one operator.
Comparison and String Operators#
Operators |
Meaning |
Operands |
|---|---|---|
|
Equal, not equal |
Exactly two compatible values; booleans are supported |
|
Greater than, greater than or equal, less than, less than or equal |
Exactly two compatible ordered values |
|
Substring matching |
Exactly two string expressions |
|
Starts or ends with |
Exactly two string expressions |
|
Matches a regular expression |
Exactly two string expressions |
ABAC policies additionally support claim-array membership through $contains; see Claim Array Membership.
String matching is case-sensitive. Field-to-field comparisons and field-to-field string operations are not supported. Use a field and an appropriately typed literal or cast in normal API queries.
Logical Operators#
Operator |
Shape |
Meaning |
|---|---|---|
|
Array of at least two conditions |
All child conditions must hold |
|
Array of at least two conditions |
At least one child condition must hold |
|
One condition |
Negates the child condition |
|
Array of at least one match expression |
All child predicates must hold in one shared list or hierarchy scope |
|
|
Constant condition |
$match is not simply another spelling of $and. It correlates predicates that address nested data. The separate Boolean $match inside a fragment filter has a different purpose, described below.
Direct children of a logical $match are limited to comparison expressions, string expressions, or another $match. They cannot be arbitrary $and, $or, $not, or $boolean expressions.
Querying Nested Data#
Parent Selection#
A condition on a wildcard list path is existential: the parent qualifies when at least one relevant nested entry satisfies that predicate. The parent resource is returned once, not once per matching child. A top-level condition selects parents but does not remove their non-matching nested content.
Predicates inside $and have independent nested scopes. They may therefore be satisfied by different list entries or, in an AAS Environment hierarchy query, different referenced Submodels. Use the logical $match operator when the predicates must describe the same entry or hierarchy branch.
On the AAS Environment’s POST /query/shells endpoint, a logical $match can combine $aas, $sm, and $sme predicates across related models. The Submodels and their elements need not be embedded in the AAS JSON: BaSyx follows the candidate AAS’s model references into locally stored Submodels and their element hierarchies. The $sm and $sme predicates must hold within the same referenced Submodel. This does not fetch data from remote endpoints. The standalone AAS Repository rejects $sm and $sme fields on this endpoint.
For example, this AAS Environment query selects shells whose idShort is MotorAAS and that reference a locally stored CarbonFootprint Submodel containing an AggregatedCarbonFootprint element with a numeric value below 48:
{
"$condition": {
"$match": [
{
"$eq": [
{ "$field": "$aas#idShort" },
{ "$strVal": "MotorAAS" }
]
},
{
"$eq": [
{ "$field": "$sm#idShort" },
{ "$strVal": "CarbonFootprint" }
]
},
{
"$lt": [
{ "$numCast": { "$field": "$sme.AggregatedCarbonFootprint#value" } },
{ "$numVal": 48 }
]
}
]
}
}
With $and instead, the AAS must still have idShort equal to MotorAAS, but one referenced Submodel could satisfy the $sm#idShort condition while another supplies the matching element.
Fragment Paths#
$fragment identifies a part of the returned representation, while $field identifies a scalar value used by a condition. The two therefore use different allowed path sets: a valid $field path is not automatically a valid $fragment path.
For the standard fragment paths, see the FieldIdentifierFragment productions in the specification’s Query Grammar. These examples illustrate the distinction:
|
|
|---|---|
|
|
|
|
|
|
BaSyx Go differs from the standard fragment grammar in these ways:
Filters cannot target mandatory identifiers:
$sm#idand theidShortof a named Submodel Element, such as$sme.Nameplate.SerialNumber#idShort, are rejected with400 Bad Request. An elementidShortcan be targeted only for SubmodelElementList members, with a path that ends in a list selector, such as$sme.Items[]#idShortor$sme.Items[0]#idShort. The general$sme#idShortfragment likewise applies only to list members.Fragments selecting
specificAssetIds,submodels,submodelDescriptors,endpoints, or referencekeysrequire brackets: use[]for any entry or a zero-based index such as[0]for one position. For example, use$aas#submodels[]and$smdesc#endpoints[]. The bare forms$aas#submodelsand$smdesc#endpointsare rejected.
The selected root must also be valid for the query endpoint; see Supported Endpoints.
Fragment Filters#
$fragment identifies a supported field, object, or list within the returned parent. Its $condition determines whether that fragment remains visible. It does not determine whether the parent is included in result.
When the filter’s Boolean $match is omitted or false, its condition is evaluated at parent scope. If any relevant nested entry satisfies the condition, the complete fragment is preserved. For a Submodel with ten supplementalSemanticIds, if one has the requested key value, all ten remain in the response.
When the BaSyx-specific $match flag is true, the condition is evaluated against each current fragment row. Only matching rows remain. With the same ten references, the response retains only those whose own data satisfies the condition. If no row matches, the fragment is empty or omitted as appropriate for that representation, but the parent can still remain in result because parent selection is controlled by the top-level $condition.
Multiple filters for the same fragment are combined with AND. Filters for different fragments are applied independently. Explicit indices restrict filtering to the selected position. Unselected siblings remain unchanged.
Each fragment affects only the model it names. A $sm fragment such as $sm#idShort, $sm#semanticId, or $sm#supplementalSemanticIds[] filters the Submodel’s own field and leaves the same fields of its Submodel Elements unchanged; use $sme fragments for those.
More Examples#
Combine conditions with $and:
{
"$condition": {
"$and": [
{
"$starts-with": [
{ "$field": "$sm#idShort" },
{ "$strVal": "Motor" }
]
},
{
"$eq": [
{ "$field": "$sme.Status#value" },
{ "$strVal": "READY" }
]
}
]
}
}
Select AAS Descriptors by an embedded Submodel Descriptor field:
{
"$condition": {
"$eq": [
{ "$field": "$aasdesc#submodelDescriptors[].idShort" },
{ "$strVal": "Nameplate" }
]
}
}
The first request is valid for /query/submodels. The second is valid for /query/shell-descriptors. A field root valid for one endpoint is not automatically valid for another.
For additional query examples, see the Query Language Examples in the BaSyx Go repository.
Results and Pagination#
Successful query responses contain the endpoint’s top-level objects in result and continuation information in paging_metadata. Each matching top-level resource appears once even when several nested entries match. Fragment filters and runtime authorization may remove fields or nested entries from each returned representation.
Query endpoints accept limit and cursor as URL query parameters. Omit the cursor for the first page, then send the returned opaque cursor with the same request body and limit for the next page. See Pagination for the shared response and cursor rules.
The query language provides no caller-controlled sort expression. Results use the endpoint’s server-defined cursor order. Clients should not rely on another ordering.
Identifier Projection#
Every query endpoint listed above supports "$select": "id", including the descriptor queries and the corresponding AAS Environment routes:
{
"$condition": { "$boolean": true },
"$select": "id"
}
The response contains original, unencoded identifiers rather than objects:
{
"paging_metadata": { "resultType": "Identifier" },
"result": ["urn:example:submodel:1"]
}
The same access rules apply as for object results. Projection does not reveal identifiers of hidden resources. Continue with paging_metadata.cursor when present and keep the query body unchanged. All other $select values, including arrays, return 400 Bad Request.
Limits#
BaSyx Go accepts at most 64 JSON container nesting levels and 8192 JSON tokens in a query. Queries that exceed either complexity limit are rejected with 400 Bad Request.
See Also#
Pagination for cursor handling.
Runtime Security for OIDC, ABAC, and authorization filters.
Swagger UI and OpenAPI for endpoint schemas and availability in the running component.