Add GetAssetAdministrationShellVersionByIdAndDate and GetSubmodelVersionByIdAndDate by sebbader-sap · Pull Request #540 · admin-shell-io/aas-specs-api

sebbader-sap · 2026-02-27T14:12:36Z

No description provided.

CLAassistant · 2026-02-27T14:12:46Z

All committers have signed the CLA.

aaronzi

The OpenAPI yaml files look good to me. But on the documentation side, I'm missing the following two things:

Which field in the AAS (or underlying database) is used to find an AAS/Submodel by date? Is it createdAt or updatedAt from the new administrative-information in the metamodel or is this just a field that exists on the server but not in the AAS itself?
What happens if an AAS/Submodel is not found based on the given date? Is the most recent version from before that given date returned or a 404?

And a general remark here. Is it expected that when a new AAS/Submodel is created or updated that the server sets the createdAt and updatedAt fields on it's own or is just the user input used no matter if the given dates make actual sense? Should access rules be used here to only allow setting the createdAt during AAS/Submodel creation and updatedAt when the AAS/Submodel are updated?

BirgitBoss · 2026-03-12T12:36:08Z

documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc

+h|Name h|Description h|Mand. h|Type h|Card.
+5+h|Input Parameter
+|id |The Submodel’s unique ID |yes |link:https://industrialdigitaltwin.io/aas-specifications/IDTA-01001/v3.1/spec-metamodel/datatypes.html#Identifier[Identifier] |1
+|date |The point in time at which the Submodel version is requested |no |link:https://industrialdigitaltwin.io/aas-specifications/IDTA-01001/v3.2/spec-metamodel/datatypes.html#DateTimeUtc[DateTimeUtc] |1


in the explanation you write: "if not date is provided" but here date is mandatory. Change to 0..1 or change explanation

True, makes no sense. I tend to make it mandatory on Operation level, but optional on HTTP endpoint level, GetSubmodelVersionByIdAndDate without the date parameter is exactly the GetSubmodelVersionById endpoint. Does this make sense?

yes, I would approve

BirgitBoss · 2026-03-12T12:45:47Z

documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc

 |===

+
+==== Operation GetSubmodelVersionByIdAndDate


#346 should be supported as well, see #346 (comment) for possible solution

#346 goes way beyond the target of feature equivalence to the ReadDPPVersionByProductIdAndDate. If #346 is needed for v3.2, we can discuss about it, but that's then a somehow related but first of all independent feature request.

depends on whether it will be realized by the same http endpoint operation

BirgitBoss · 2026-03-12T12:46:38Z

documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc

 h|Operation Name 4+e|[[GetAssetAdministrationShell]]GetAssetAdministrationShell
 h|Explanation 4+a|Returns the Asset Administration Shell
-h|semanticId 4+|`\https://admin-shell.io/aas/API/GetAssetAdministrationShell/3/2`
+h|semanticId 4+|`\https://admin-shell.io/aas/API/GetAssetAdministrationShell/3/1`


why did you change to /3/1, it is /3/2 here

Most likely a copy-paste issue...

BirgitBoss · 2026-03-12T12:51:03Z

documentation/IDTA-01002-3/modules/ROOT/pages/specification/interfaces.adoc

+h|Name h|Description h|Mand. h|Type h|Card.
+5+h|Input Parameter
+|id |The Asset Administration Shell’s unique ID |yes |link:https://industrialdigitaltwin.io/aas-specifications/IDTA-01001/v3.1/spec-metamodel/datatypes.html#Identifier[Identifier] |1
+|date |The point in time at which the Asset Administration Shell version is requested |no |link:https://industrialdigitaltwin.io/aas-specifications/IDTA-01001/v3.2/spec-metamodel/datatypes.html#DateTimeUtc[DateTimeUtc] | 1


see above, same comment as for GetSubmodelVersionByIdAnddate: either date is optional with defulat "latest" or it is mandatory, then update explanation with "If no date is provided, the latest version is returned."

BirgitBoss · 2026-03-12T12:53:58Z

documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc

 [%autowidth,width="100%",cols="40%,15%,45%",options="header",]
 |===
 h|Operation  h|Kind of Change h|Comment
+ | a| GetAssetAdministrationShellVersionByIdAndDate | New a| new API-Operation for AAS Repository interface to retrieve a specific version of an AAS from a given point in time.


probably wrong formatting?change | a| to |

BirgitBoss · 2026-03-12T12:54:50Z

...ation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/service-specifications-and-profiles.adoc

 This endpoint will return the related profile string.
 It is sufficient to only expose the latest service specification identifier in case a server supports different minor versions of a service specification at the same time.
-For instance, if both "https://admin-shell.io/aas/API/3/2/SubmodelRegistryServiceSpecification/SSP-002" and "https://admin-shell.io/aas/API/3/2/SubmodelRegistryServiceSpecification/SSP-002" are supported, the server may only include "https://admin-shell.io/aas/API/3/2/SubmodelRegistryServiceSpecification/SSP-002" in its profiles list.
+For instance, if both "https://admin-shell.io/aas/API/3/1/SubmodelRegistryServiceSpecification/SSP-002" and "https://admin-shell.io/aas/API/3/2/SubmodelRegistryServiceSpecification/SSP-002" are supported, the server may only include "https://admin-shell.io/aas/API/3/2/SubmodelRegistryServiceSpecification/SSP-002" in its profiles list.


should be /3/2

BirgitBoss

see comments with respect to also support also #346
versioning of operation IDs etc: should be /3/2, not /3/1
Same operation as for repository also needed for AAS and SubmodelDescriptors

documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc

sebbader-sap · 2026-03-12T14:55:29Z

@aaronzi

Which field in the AAS (or underlying database) is used to find an AAS/Submodel by date? Is it createdAt or updatedAt from the new administrative-information in the metamodel or is this just a field that exists on the server but not in the AAS itself?

This is intentionally, because nobody right now knows what are business data attributes and what shall be seen as technical timestamps. If you would ask me as a developer, I'd use my DB-internal createdAt and changedAt timestamps. But of course not every underlying DB schema has them.

administrative-information.createdAt and administrative-information.updatedAt are only two points in time. I can't see how the realisation of a proper GetXyzVersionByIdAndDate operation can be implemented. So here the system implementers themselves have to find a solution.

sebbader-sap · 2026-03-12T15:01:08Z

What happens if an AAS/Submodel is not found based on the given date? Is the most recent version from before that given date returned or a 404?

Good question... I can imagine the following cases:

date before AAS_creation_date: 404 seems wrong to me, as the resource itself exists right now. A query parameter should not make a difference between a 200 and a 404. So either an empty response body, or a respective error message ("400: Object did not exist at this date")?
date same_or_after AAS_creation_date: Then the server has to provide the correct AAS version at that given date.
date same_or_after AAS_creation_date AND date before administrative-information.updatedAt: If the server has no memory of that version, the implementation is not correct...

BirgitBoss · 2026-03-12T15:55:34Z

@aaronzi

Which field in the AAS (or underlying database) is used to find an AAS/Submodel by date? Is it createdAt or updatedAt from the new administrative-information in the metamodel or is this just a field that exists on the server but not in the AAS itself?

administrative-information.createdAt and administrative-information.updatedAt are only two points in time. I can't see how the realisation of a proper GetXyzVersionByIdAndDate operation can be implemented. So here the system implementers themselves have to find a solution.

Perhaps we need to defined that in case of the creation of a new AAs/Submodel administrative-information.createdAt and administrative-information.updatedAt shall be identical. For this API operation then only the updatedAt attribute is relevant.

BirgitBoss · 2026-03-12T15:59:19Z

What happens if an AAS/Submodel is not found based on the given date? Is the most recent version from before that given date returned or a 404?

Good question... I can imagine the following cases:

1. date  _before_  AAS_creation_date: 404 seems wrong to me, as the resource itself exists right now. A query parameter should not make a difference between a 200 and a 404. So either an empty response body, or a respective error message ("400: Object did not exist at this date")?

2. date  _same_or_after_  AAS_creation_date: Then the server has to provide the correct AAS version at that given date.

3. date  _same_or_after_  AAS_creation_date  AND  date  _before_  `administrative-information.updatedAt`:  If the server has no memory of that version, the implementation is not correct...

I think it should be Is the most recent version from before that given date returned, at least for DPP applications: the real question is "Which DPP was valid at this point in time", so you cannot return a newer Version.

sebbader-sap added 4 commits February 27, 2026 12:51

add GetAssetAdministrationShellVersionByIdAndDate

61fd432

add GetAssetAdministrationShellVersionByIdAndDate in profiles

55eec46

add the date query parameter

4fcf008

adding ...VersionbyIdAndDate operations

739818a

sebbader-sap requested review from BirgitBoss, aaronzi, alexgordtop, aorzelskiGH, danielporta, g1zzm0, mdanish98, mjacoby, waltersve, whamm86 and zrgt as code owners February 27, 2026 14:12

sebbader-sap changed the base branch from main to IDTA-01002-3-2_working February 27, 2026 14:12

sebbader-sap added this to the 3.2 milestone Feb 28, 2026

whamm86 approved these changes Mar 4, 2026

View reviewed changes

aaronzi reviewed Mar 5, 2026

View reviewed changes

aaronzi mentioned this pull request Mar 12, 2026

Add filter for created / updated to Shells / Submodels #551

Open

1 task

BirgitBoss reviewed Mar 12, 2026

View reviewed changes

BirgitBoss requested changes Mar 12, 2026

View reviewed changes

sebbader-sap commented Mar 12, 2026

View reviewed changes

documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc Outdated Show resolved Hide resolved

ascidoc format fix

01e9bd6

Conversation

sebbader-sap commented Feb 27, 2026

Uh oh!

CLAassistant commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aaronzi left a comment

Choose a reason for hiding this comment

Uh oh!

BirgitBoss Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BirgitBoss left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sebbader-sap commented Mar 12, 2026

Uh oh!

sebbader-sap commented Mar 12, 2026

Uh oh!

BirgitBoss commented Mar 12, 2026

Uh oh!

BirgitBoss commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

CLAassistant commented Feb 27, 2026 •

edited

Loading

BirgitBoss Mar 12, 2026 •

edited

Loading