Skip to content

Commit c929ad3

Browse files
sebbader-sapBirgitBoss
sebbader-sap
and
BirgitBoss
authored
[Review] Incorporate Findings affecting OpenAPI (#411)
* add comment about the oneOf rendering problem and fixing outdated query result declarations * sync idShort patterns and minLength * add comment about the oneOf rendering problem and fixing outdated query result declarations * Update Part 1 Classes (#413) * incorporate the latest aas json schema changes from part 1 * incorporate valueonly adjustments from part 1 * make the 409 description more generice * make paging_metadata mandatory to match definition in the spec * Update Part2-API-Schemas/openapi.yaml Co-authored-by: Birgit Boss <[email protected]> * Update Part1-MetaModel-Schemas/openapi.yaml Co-authored-by: Birgit Boss <[email protected]> --------- Co-authored-by: Birgit Boss <[email protected]> --------- Co-authored-by: Birgit Boss <[email protected]>
1 parent 9f23c6c commit c929ad3

File tree

10 files changed

+55
-77
lines changed

10 files changed

+55
-77
lines changed

‎AssetAdministrationShellRegistryServiceSpecification/V3.1_SSP-004.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ paths:
3333
content:
3434
application/json:
3535
schema:
36+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
3637
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
3738
responses:
3839
'200':

‎AssetAdministrationShellRepositoryServiceSpecification/V3.1_SSP-003.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ paths:
3333
content:
3434
application/json:
3535
schema:
36+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
3637
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
3738
responses:
3839
'200':

‎ConceptDescriptionRepositoryServiceSpecification/V3.1_SSP-002.yaml

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -34,23 +34,15 @@ paths:
3434
content:
3535
application/json:
3636
schema:
37+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
3738
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
3839
responses:
3940
'200':
4041
description: Requested Concept Descriptions
4142
content:
4243
application/json:
4344
schema:
44-
allOf:
45-
- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
46-
- type: object
47-
properties:
48-
result:
49-
type: array
50-
items:
51-
oneOf:
52-
- $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/ConceptDescription"
53-
- type: string
45+
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/QueryResultConceptDescription'
5446
'400':
5547
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
5648
'401':

‎Entire-API-Collection/V3.1.yaml

Lines changed: 8 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4555,6 +4555,7 @@ paths:
45554555
content:
45564556
application/json:
45574557
schema:
4558+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
45584559
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
45594560
responses:
45604561
'200':
@@ -6088,23 +6089,15 @@ paths:
60886089
content:
60896090
application/json:
60906091
schema:
6092+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
60916093
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
60926094
responses:
60936095
'200':
60946096
description: Requested Submodels
60956097
content:
60966098
application/json:
60976099
schema:
6098-
allOf:
6099-
- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
6100-
- type: object
6101-
properties:
6102-
result:
6103-
type: array
6104-
items:
6105-
oneOf:
6106-
- $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/Submodel"
6107-
- type: string
6100+
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/QueryResultSubmodel'
61086101
'400':
61096102
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
61106103
'401':
@@ -6323,23 +6316,15 @@ paths:
63236316
content:
63246317
application/json:
63256318
schema:
6319+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
63266320
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
63276321
responses:
63286322
'200':
63296323
description: Requested Concept Descriptions
63306324
content:
63316325
application/json:
63326326
schema:
6333-
allOf:
6334-
- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
6335-
- type: object
6336-
properties:
6337-
result:
6338-
type: array
6339-
items:
6340-
oneOf:
6341-
- $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/ConceptDescription"
6342-
- type: string
6327+
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/QueryResultConceptDescription'
63436328
'400':
63446329
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
63456330
'401':
@@ -6671,6 +6656,7 @@ paths:
66716656
content:
66726657
application/json:
66736658
schema:
6659+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
66746660
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
66756661
responses:
66766662
'200':
@@ -7001,10 +6987,11 @@ paths:
70016987
content:
70026988
application/json:
70036989
schema:
6990+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
70046991
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
70056992
responses:
70066993
'200':
7007-
description: Requested Submodels
6994+
description: Requested Submodel Descriptors
70086995
content:
70096996
application/json:
70106997
schema:

‎Part1-MetaModel-Schemas/openapi.yaml

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,18 @@
22
openapi: 3.0.3
33
info:
44
title: DotAAS Part 1 | Metamodel | Schemas
5-
description: >-
5+
description: >-
66
The schemas implementing the [Specification of the Asset Administration Shell: Part 1](http://industrialdigitaltwin.org/en/content-hub).
7-
7+
88
Publisher: Industrial Digital Twin Association (IDTA) 2025
99
contact:
1010
name: Industrial Digital Twin Association (IDTA)
1111
email: [email protected]
12-
license:
12+
license:
1313
name: CC BY 4.0
1414
url: https://creativecommons.org/licenses/by/4.0/
1515
version: V3.1.0
16-
components:
16+
components:
1717
schemas:
1818
AasSubmodelElements:
1919
type: string
@@ -788,16 +788,21 @@ components:
788788
required:
789789
- modelType
790790
Reference:
791+
allOf:
792+
- "$ref": "#/components/schemas/ReferenceParent"
793+
- properties:
794+
referredSemanticId:
795+
"$ref": "#/components/schemas/ReferenceParent"
796+
ReferenceParent:
797+
# This class is introduced due to the recursion issue of the SwaggerUi (see https://github.com/swagger-api/swagger-ui/issues/3325)
791798
type: object
792799
properties:
793800
type:
794-
$ref: '#/components/schemas/ReferenceTypes'
795-
referredSemanticId:
796-
$ref: '#/components/schemas/Reference'
801+
"$ref": "#/components/schemas/ReferenceTypes"
797802
keys:
798803
type: array
799804
items:
800-
$ref: '#/components/schemas/Key'
805+
"$ref": "#/components/schemas/Key"
801806
minItems: 1
802807
required:
803808
- type

‎Part2-API-Schemas/openapi.yaml

Lines changed: 24 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ components:
5252
type: string
5353
minLength: 1
5454
maxLength: 2048
55-
pattern: ^([\\t\\n\\r-\ud7ff\ue000-\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$
55+
pattern: ^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$
5656
Cursor:
5757
name: cursor
5858
in: query
@@ -145,12 +145,7 @@ components:
145145
second:
146146
$ref: "#/components/schemas/ReferenceValue"
147147
annotations:
148-
type: array
149-
items:
150-
$ref: "#/components/schemas/ValueOnly"
151-
required:
152-
- first
153-
- second
148+
$ref: "#/components/schemas/ValueOnly"
154149
type: object
155150
AssetAdministrationShellDescriptor:
156151
allOf:
@@ -177,7 +172,9 @@ components:
177172
pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
178173
idShort:
179174
type: string
175+
minLength: 1
180176
maxLength: 128
177+
pattern: "^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$"
181178
id:
182179
type: string
183180
maxLength: 2048
@@ -208,12 +205,12 @@ components:
208205
type: string
209206
minLength: 1
210207
maxLength: 64
211-
pattern: "^([\\t\\n\\r -\ud7ff\ue000-\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
208+
pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
212209
value:
213210
type: string
214211
minLength: 1
215212
maxLength: 2048
216-
pattern: "^([\\t\\n\\r -\ud7ff\ue000-\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
213+
pattern: "^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$"
217214
BaseOperationResult:
218215
allOf:
219216
- $ref: "#/components/schemas/Result"
@@ -258,9 +255,7 @@ components:
258255
maxLength: 100
259256
value:
260257
type: string
261-
required:
262-
- contentType
263-
- value
258+
minLength: 1
264259
type: object
265260
BooleanValue:
266261
type: boolean
@@ -315,18 +310,13 @@ components:
315310
type: string
316311
minLength: 1
317312
maxLength: 2048
318-
pattern: ^([\\t\\n\\r-\ud7ff\ue000-\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$
313+
pattern: ^([\\x09\\x0a\\x0d\\x20-\\ud7ff\\ue000-\\ufffd]|\\ud800[\\udc00-\\udfff]|[\\ud801-\\udbfe][\\udc00-\\udfff]|\\udbff[\\udc00-\\udfff])*$
319314
specificAssetIds:
320315
type: array
321316
items:
322317
$ref: "#/components/schemas/SpecificAssetIdValue"
323318
statements:
324-
items:
325-
$ref: "#/components/schemas/ValueOnly"
326-
type: array
327-
required:
328-
- statements
329-
- entityType
319+
$ref: "#/components/schemas/ValueOnly"
330320
type: object
331321
ExecutionState:
332322
enum:
@@ -347,9 +337,6 @@ components:
347337
type: string
348338
minLength: 1
349339
maxLength: 2048
350-
required:
351-
- contentType
352-
- value
353340
type: object
354341
FileMetadata:
355342
allOf:
@@ -522,6 +509,7 @@ components:
522509
$ref: '#/components/schemas/stringItems'
523510
$boolean:
524511
type: boolean
512+
# Note: It is a known problem that SwaggerHub cannot render the following oneOf declaration.
525513
oneOf:
526514
- required:
527515
- $and
@@ -712,6 +700,8 @@ components:
712700
cursor:
713701
type: string
714702
example: wJlCDLIl6KTWypN7T6vc6nWEmEYe99Hjf1XY1xmqV-M=#
703+
required:
704+
- paging_metadata
715705
PackageDescription:
716706
properties:
717707
aasIds:
@@ -831,6 +821,8 @@ components:
831821
type: array
832822
items:
833823
$ref: "#/components/schemas/AssetAdministrationShellDescriptor"
824+
required:
825+
- paging_metadata
834826
QueryResultConceptDescription:
835827
type: object
836828
properties:
@@ -851,6 +843,8 @@ components:
851843
oneOf:
852844
- $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/ConceptDescription"
853845
- type: string
846+
required:
847+
- paging_metadata
854848
QueryResultSubmodel:
855849
type: object
856850
properties:
@@ -871,6 +865,8 @@ components:
871865
oneOf:
872866
- $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/Submodel"
873867
- type: string
868+
required:
869+
- paging_metadata
874870
QueryResultSubmodelDescriptor:
875871
type: object
876872
properties:
@@ -891,6 +887,8 @@ components:
891887
oneOf:
892888
- $ref: "#/components/schemas/SubmodelDescriptor"
893889
- type: string
890+
required:
891+
- paging_metadata
894892
RangeMetadata:
895893
allOf:
896894
- $ref: "#/components/schemas/SubmodelElementAttributes"
@@ -930,9 +928,6 @@ components:
930928
$ref: "#/components/schemas/ReferenceValue"
931929
second:
932930
$ref: "#/components/schemas/ReferenceValue"
933-
required:
934-
- first
935-
- second
936931
type: object
937932
Result:
938933
properties:
@@ -1045,7 +1040,9 @@ components:
10451040
type: array
10461041
idShort:
10471042
type: string
1043+
minLength: 1
10481044
maxLength: 128
1045+
pattern: "^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$"
10491046
id:
10501047
type: string
10511048
minLength: 1
@@ -1090,8 +1087,7 @@ components:
10901087
allOf:
10911088
- $ref: "#/components/schemas/SubmodelElementAttributes"
10921089
SubmodelElementCollectionValue:
1093-
type: object
1094-
description: Since patternProperties and propertyNames are not supported by OpenApi yet, the ValueOnly serialization for this elements works with the key-attribute as the JSON-property name and the value-attribute as the corresponding value.
1090+
$ref: "#/components/schemas/ValueOnly"
10951091
SubmodelElementMetadata:
10961092
allOf:
10971093
- $ref: "#/components/schemas/SubmodelElementAttributes"
@@ -1268,7 +1264,7 @@ components:
12681264
schema:
12691265
$ref: '#/components/schemas/Result'
12701266
'conflict':
1271-
description: Conflict, a resource which shall be created exists already. Might be thrown if a Submodel or SubmodelElement with the same ShortId is contained in a POST request.
1267+
description: Conflict, a resource which shall be created exists already. Might be thrown if an object with the same id (for Identifiables) or idShort (for Referables within the same Container Element or Submodel) is contained in a POST request.
12721268
content:
12731269
application/json:
12741270
schema:

‎SubmodelRegistryServiceSpecification/V3.1_SSP-004.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ paths:
3333
content:
3434
application/json:
3535
schema:
36+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
3637
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
3738
responses:
3839
'200':

‎SubmodelRepositoryServiceSpecification/V3.1_SSP-005.yaml

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,23 +33,15 @@ paths:
3333
content:
3434
application/json:
3535
schema:
36+
# Note: It is a known problem that SwaggerHub cannot render the oneOf statement in the Query definition.
3637
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/Query'
3738
responses:
3839
'200':
3940
description: Requested Submodels
4041
content:
4142
application/json:
4243
schema:
43-
allOf:
44-
- $ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/PagedResult'
45-
- type: object
46-
properties:
47-
result:
48-
type: array
49-
items:
50-
oneOf:
51-
- $ref: "https://api.swaggerhub.com/domains/Plattform_i40/Part1-MetaModel-Schemas/V3.1.0#/components/schemas/Submodel"
52-
- type: string
44+
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/schemas/QueryResultSubmodel'
5345
'400':
5446
$ref: 'https://api.swaggerhub.com/domains/Plattform_i40/Part2-API-Schemas/V3.1.0#/components/responses/bad-request'
5547
'401':

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ Major Changes:
3535
* change: ProtocolInformation/securityAttributes changed from mandatory to optional.
3636
* change: Endpoint/interface extended with "VALUE" and "METADATA" aspects.
3737
* new: Added 'Role' and 'NotApplicable' wherever AssetAdministrationShellDescriptor/AssetKind is used.
38+
* change: Added minLength=1 requirement and regex pattern "^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$" to all classes with idShort parameters to keep definitions in sync with the declaration of link:https://admin-shell-io.github.io/aas-specs-antora/IDTA-01001/v3.1/spec-metamodel/common.html#referable-attributes[Referable/idShort]
3839
* change: Fix missing 'Repository' in ConceptDescriptionServiceSpecification to ConceptDescriptionRepositoryServiceSpecification (https://github.com/admin-shell-io/aas-specs-api/issues/171[#171])
3940

4041
Minor Changes:

0 commit comments

Comments
 (0)