Skip to content

Fix thumbnail and attachment multipart uploads - #665

Merged
sebbader-sap merged 10 commits into
IDTA-01002-3-2_workingfrom
aaronzi/fix-thumbnail-attachment-uploads
Jul 15, 2026
Merged

Fix thumbnail and attachment multipart uploads#665
sebbader-sap merged 10 commits into
IDTA-01002-3-2_workingfrom
aaronzi/fix-thumbnail-attachment-uploads

Conversation

@aaronzi

@aaronzi aaronzi commented Jul 15, 2026

Copy link
Copy Markdown
Member

The thumbnail and attachment upload request bodies are mandatory, but their multipart schemas do not require the binary file property. An empty object therefore satisfies the OpenAPI contract even though there is no content to store.

The schemas also declare fileName as a separate property. In OpenAPI, each multipart schema property describes a distinct form part. RFC 7578 instead carries an optional source filename in the filename parameter of the binary part's Content-Disposition header. The abstract PutThumbnail and PutFileByPath operations accept only Part 2 File Content, which is defined as binary data and has no separate filename input. Part 1 File.value and thumbnail Resource.path remain model metadata and are not additional multipart parameters.

This change removes the redundant fileName property and requires file in every thumbnail and attachment upload schema. The file property documents the standard multipart filename mechanism, all affected service profiles and the combined API are kept aligned, and a dedicated artifact validator checks every multipart file-upload definition for the same contract. Because the incorrect schemas already existed in V3.1.3, the correction is recorded in the V3.2 changelog.

The AASX upload endpoints are handled separately in #656; this PR covers the remaining thumbnail and attachment uploads.

Validation

  • python3 tools/validate_spec_artifacts.py
  • python3 tools/validate_multipart_uploads.py
  • 20 Query JSON Schema unit tests
  • openapi-spec-validator passes for all six affected service profiles and the combined API
  • Parsed all 21 multipart file-upload definitions and verified that file is required, fileName is absent, and the standard filename mechanism is documented
  • git diff --check

Merge order

Depends on #662. Merge #646 through #662 before this PR.

@github-advanced-security github-advanced-security AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QDJVMC found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

sebbader-sap and others added 3 commits July 15, 2026 15:13
...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>
@aaronzi
aaronzi force-pushed the aaronzi/fix-thumbnail-attachment-uploads branch from ec812b3 to f561041 Compare July 15, 2026 14:32
@aaronzi
aaronzi force-pushed the aaronzi/fix-thumbnail-attachment-uploads branch from f561041 to 21da43a Compare July 15, 2026 14:39
@sebbader-sap
sebbader-sap marked this pull request as ready for review July 15, 2026 18:39

@sebbader-sap sebbader-sap left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked a bit whether or not PUT is a common practice for multpart operations: It's not. But I also didn't find anything which forbids it. Still, something to think about for the next breaking version.

@sebbader-sap
sebbader-sap merged commit 9f8d193 into IDTA-01002-3-2_working Jul 15, 2026
4 checks passed
@sebbader-sap
sebbader-sap deleted the aaronzi/fix-thumbnail-attachment-uploads branch July 15, 2026 18:47
juileetikekar pushed a commit that referenced this pull request Jul 20, 2026
* Update antora.yml

* add parameter id and note to PutAssetAdministrationShellById

* add the 'server not implemented' status code

* Bi bo/editorial changes 3 2 (#498)

* add link to GetFileByPath

* SerializationFormat: remove mentioning of AML, RDF because not (yet contained)
+ outlook that enum may be extended in future releases

* formatting of table for Submodel Interface

* correct link .adoc instead of html

* correct formatting of constraint AASa-003 + update links to V3-1 for Part 1 and 2

* use v3.2 in all files

* Include Note for the Operation GenerateSerializationByIds (#512)

* add note for the operation GenerateSerializationByIds

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

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

---------

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update AasxFileServerServiceSpecification/V3.2_SSP-001.yaml

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update AasxFileServerServiceSpecification/V3.2_SSP-001.yaml

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update documentation/IDTA-01002-3/modules/ROOT/pages/index.adoc

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update documentation/IDTA-01002-3/modules/ROOT/pages/index.adoc

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update documentation/IDTA-01002-3/modules/ROOT/pages/index.adoc

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* replace the old 3.1 version in semanticIds

* replace the old 3.1 version in semanticIds

* Add V3.1.2 Bugfixes into V3.2.0 (#541)

* fix ServiceSpecificationProfileEnum values for 3.0 and 3.1

* remove TREE (#539)

* remove v3.2 profile uris

---------

Co-authored-by: Martin Stemmer <52048213+Martin187187@users.noreply.github.com>

* remove GetAllAssetAdministrationShellDescriptorsByAssetType from openapi (#530)

* add new aas repo identifiable profile

* editorial fixes in table 2 query language (#543)

* BUGFIX Grammar 3-2 (#548)

* fixed grammar

* align with secuity spec

* update BNF based on security BNF

* fixed schema patterns

* fix pattern

* adjust datetime & time patterns

* fixed modelstringpattern in api

* align time pattern to api

* align time pattern to api

* added missing parentheses

* fix grammar bugs

* fix typo in changelog

---------

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>

* remove swaggerhub links (#544)

* remove swaggerhub links

* fix link

* Fix ServiceSpecificationProfileEnum for V3.2 (#528)

* fixing ServiceSpecificationProfileEnum entries + adding v3.2 ones

* extend example list in OpenAPI and provide a description as well

* change application/asset-administration-shell-package+xml to applicat… (#542)

* change application/asset-administration-shell-package+xml to application/zip+xml

* fix review comments

* Async AASX File Server Profile (#531)

* add proposal for an async aasx profile

* correct result of the get .../results/... endpoint

* add missing appearances of the async aasx file server operations

* cherry pick bugfix commit + adjusting the changelog (#567)

* Signing API based on JWS (#527)

* Create signatures.adoc

* Update signatures.adoc

* Update signatures.adoc

* Signature description

* Add JWS

* Add operations for JWS signatures

* Add JWS signature profiles

* Add mapping of JWS signature

* Add signature profiles

* add changelog for PR Signing (#561)

* Add V3.1.2 Bugfixes into V3.2.0 (#541)

* fix ServiceSpecificationProfileEnum values for 3.0 and 3.1

* remove TREE (#539)

* remove v3.2 profile uris

---------

Co-authored-by: Martin Stemmer <52048213+Martin187187@users.noreply.github.com>

* remove GetAllAssetAdministrationShellDescriptorsByAssetType from openapi (#530)

* added changelog for new signing operations and profiles

* undo changes to the profiles table

* fix typo

---------

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>
Co-authored-by: Martin Stemmer <52048213+Martin187187@users.noreply.github.com>

* adding signature profiles as openapi yaml

* editorial fix

* editorial change

* fix typo

---------

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>
Co-authored-by: aorzelskiGH <48956800+aorzelskiGH@users.noreply.github.com>
Co-authored-by: Martin Stemmer <52048213+Martin187187@users.noreply.github.com>

* Add signing of Identifiables (#523)

* Create signatures.adoc

* Update signatures.adoc

* Update signatures.adoc

* Signature description

* Add JWS

* Add operations for JWS signatures

* Add JWS signature profiles

* Add mapping of JWS signature

* Add signature profiles

* Apply suggestion from @BirgitBoss

* Apply suggestion from @BirgitBoss

* Apply suggestion from @BirgitBoss

* Apply suggestion from @BirgitBoss

---------

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>
Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>

* solve conflicts and clean up files

* fix SupplementalSemanticId vs. SupplementalSemanticIds

* adding supplemantalSemanticIds to the AAS Query

* Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt

* bugfix OperationRequestValueOnly and OperationResultValueOnly from SubmodelElementValue to ValueOnly

* adjust README with v3.2 release information

* explaining supplementalSemanticIds[0] vs. supplementalSemanticIds[any]

* typo

* add JSON schema pattern for new supplementalSemanticIds

* update index.adoc and bibliography to include Part 3b for V3.2 (#571)

* fix changelog tables to be consistent, add extended interface AASX File Servier (#574)

* editorial changes (#559)

* remove one level of section structuring to enable better readable in the specification

* fix formatting of bullet list

* wording: implicity to implicit

* Apply suggestion from @sebbader-sap

---------

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>

* Add GetAssetAdministrationShellVersionByIdAndDate and GetSubmodelVersionByIdAndDate (#540)

* add GetAssetAdministrationShellVersionByIdAndDate

* add GetAssetAdministrationShellVersionByIdAndDate in profiles

* add the date query parameter

* adding ...VersionbyIdAndDate operations

* ascidoc format fix

* Added recent changes and moved byIdAndDate to new profile (#565)

* Added recent changes and moved byIdAndDate to new profile

* Many fixes, changed result in openapi

* Fix returntype

* Review fixes

* Fixed parameters in GetAssetAdministrationShellRecentChanges, added GetSubmodelRecentChanges

* adjust copyright year

* Added ConceptDescription and Registry endpoint

* Added ConceptDescription and Registry endpoint to interfaces

* Renamed parameter from createAt/updateAt to createdFrom/updatedFrom and changed description

* Fixed table format

* Fixed semantic ID of /submodels/{submodelIdentifier}/$history

* Fixed operationID of /submodels/{submodelIdentifier}/$history

* Renamed operations from Get.. to GetAll..

* Sorted operations

* GetAllAssetAdministrationShellRecentChanges -> GetAllAssetAdministrationShellsRecentChanges

* remove git conflict marks

---------

Co-authored-by: Alexander Gordt <100141498+alexgordtop@users.noreply.github.com>

* Exemplary Discovery of AAS Objects with LinkSets and ID Link (#536)

* initial version of new section under Interactions

* Added opeartions to profiles and another auth example

* dppVersion to dppSchemaVersion

* provide dpp-service-endpoints

* Adopted changes requested in last api meeting

---------

Co-authored-by: Alexander Gordt <alexander.gordt@objective-partner.com>

* new part 1 openapi classes for metamodel version 3.2

* add missing endpoints and operations for the aas identifiable profile

* Correct endpointProtocolVersion values in the example

* Update changelog.adoc

* fix formatting + remove redundant chapter Interface Changes w.r.t. V3.1.2 to V3.2 + add "none" if not change made

* Chapter 3.1.1 vs. 3.1.2 was there twice: merged

* fix structure of interfaces_payload: ServiceDescription is not subchapter of AssetLink

* update changelog w.r.t. structural change + typo

* added subchapter for V3.2 interface changes again + added issue references

* tyo; “asyncronous” should be “asynchronous”

* typo: PostAsyncAASXPackag ==> PostAsyncAASXPackage

* Apply suggestion from @BirgitBoss

* correct xref IDTA-01001/v3.1 to v3.2 (#605)

* fix: correct AsciiDoc table closing tag in Interface Changes section

* new: Annex on DPP (#620)

* Annex DPP: fix nav.adoc + update text

* Fix response payload type for PutSubmodelById (3.2 Port) (#602)

* Fixes PUT /shells/{aasIdentifier}/submodels/{submodelIdentifier} return type on 201 status

* Fix response payload type for PutSubmodelById: status code 201 now returns a Submodel instead of a Reference

* Corrects changelog

* Fixes wrong version

* Fix response contracts in Discovery OpenAPI files (3.2 Port) (#618)

* Fix response contracts in Discovery OpenAPI files

Remove status codes 404 and 409 for POST /lookup/shells/{aasIdentifier} to align with create-or-replace and replace/update semantics.

* Corrects changelog

* Adds missing empty line in changelog

---------

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>

* Removes wrong 404 status code for getAllSubmodelDescriptors (3.2 Port) (#619)

* Removes wrong 404 status code for getAllSubmodelDescriptors

* Fixes changelog

---------

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>

* add the signature chapter to the contents

* put the JSON into code blocks

* fixing Submodel Service Specification – Read Profile identifier

* editorial fixes for the query language chapter

* address review findings on the new "recent changes" operations

* explain the versioning pattern used for this documents during bugfixes

* previous version is the v3.1.3, not v3.1.2

* docs(annex): add informative Conformance Test Corpus (#590)

Introduce a new annex that defines a structured, informative
set of acceptance tests for conforming implementations. The
corpus covers:

- Query Language parsing and evaluation
- HTTP/REST API (auth, PUT CREATE/UPDATE, invoke, files, query)
- Error handling and edge cases (parse, schema, cast errors,
  profile applicability)

Each test case has a stable ID, one-line purpose and expected
behaviour, so the corpus can be turned directly into an
executable conformance test suite. Aligned with the matching
corpus in IDTA-01004.

Refs: Review Finding T-16
Made-with: Cursor

* docs(query-language): declare IDTA-01002 as SoT for formula grammar (#589)

Add a normative subsection "Single source of truth for the
formula grammar and JSON Schema" to the Query Language chapter.
This clarifies that all formula productions (logical
expressions, comparisons, FieldIdentifiers, value literals,
type casts, $match/$and/$or/$not) are defined here and MUST
NOT be redefined or diverged from in IDTA-01004 (Security).

This matches the long-standing practical situation where the
two specs ship the same BNF fragments and JSON Schema blocks
but did not explicitly name one of them as the authoritative
source.

Refs: Review Finding T-01
Made-with: Cursor

* docs(query-language): align prose tables with BNF and JSON Schema (#583)

Fix several prose inconsistencies in query-language.adoc that contradict
the BNF grammar and modelStringPattern:

- Cast operator table
    Removed duplicate $dateTime row and dropped the stray "$" prefix
    from all entries (str, num, bool, hex, dateTime, time). The BNF
    defines these as "str"/"num"/"hex"/"bool"/"dateTime"/"time"
    without a $ prefix.

- $aas#submodels field table
    Added the mandatory [<index>] segment to submodels so the
    examples match the BNF production
        "submodels" ( "[" [0-9]* "]" ) "." <ReferenceClause>
    and the schema modelStringPattern.

- $aasdesc#submodelDescriptors field table
    Same fix: added [<index>] to the submodelDescriptors prefix in
    all rows (semanticId, supplementalSemanticIds, id, idShort,
    endpoints).

- Comparison examples
    Updated $aas#submodels references in the comparison-result
    tables to $aas#submodels[] so they stay valid against the
    tightened regex.

- idShort example
    Corrected example "$aas#id" for the idShort row to "$aas#idShort".

- Limitations bullet
    Expanded the list of fields available on SubmodelElements to
    match the BNF (semanticId, supplementalSemanticIds, idShort,
    value, valueType, language).

No BNF or schema changes.

Refs: Review Finding T-11
Made-with: Cursor

* docs(profiles): add FieldIdentifier applicability table per profile (#584)

Add a normative summary of which Query / Access-Rule FieldIdentifier
prefix is meaningful per service specification family (Repository vs.
Registry vs. AAS/Submodel service). The table makes it explicit that

- $aasdesc / $smdesc are only applicable in Registry deployments;
- $cd is only applicable in the ConceptDescriptionRepository family;
- queries / access rules referencing a non-applicable prefix in the
  chosen profile are treated as "not applicable" rather than as
  evaluation errors.

Refs: Review Finding T-07
Made-with: Cursor

* docs(query-language): add normative Query Evaluation Semantics (#585)

* docs(query-language): add normative "Query Evaluation Semantics"

Specify how AAS queries MUST be evaluated, covering:

- parse and schema validation (400 / 422 mapping),
- behaviour of FieldIdentifiers that do not resolve on the target
  (candidate excluded, no error),
- behaviour under profile restrictions (non-applicable prefix is
  treated like "field not present"),
- semantics of list-valued FieldIdentifiers (existential match),
- behaviour on casting errors (candidate excluded, query stays green),
- interaction with Access Rules (IDTA-01004): applicable ALLOW rules
  filter the candidate set; "not applicable" rules do not fail the
  query.

Refs: Review Finding T-15
Made-with: Cursor

* fix local reference

---------

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>

* docs(query-language): reference cross-spec terminology matrix (#587)

Add a NOTE next to the FieldIdentifier root-element table that
explicitly maps each $-prefix to the corresponding Metamodel
class (IDTA-01001) and API resource path. References the new
normative terminology matrix in IDTA-01001 as the single source
of truth and states that prefixes are lower-case only.

Refs: Review Finding T-09
Made-with: Cursor

* fix(schema): use anyOf where BNF allows mixed inline and named groups (#581)

The BNF distinguishes concatenation (mix allowed) from alternation
(XOR) for the pairs inline-group / named-group. Three pairs in the
JSON schemas were marked oneOf (XOR) even though the grammar is CAT.

Grammar references (access-rules.bnf / grammar.bnf):

  <AttributeGroup> ::=
      ( <SingleAttribute> <ws> )*
      ( <UseAttributeGroup> <ws> )*     -- CAT

  <AccessPermissionRule> ::=
      "ACCESSRULE:" ...
      ( <ACL> | <UseACL> ) <ws>          -- XOR
      "OBJECTS:" <ws>
      ( <SingleObject> <ws> )*
      ( <UseObjectGroup> <ws> )*         -- CAT (inline, not <ObjectGroup>)
      ( "FORMULA:" ... | <UseFormula> )  -- XOR

Changes:

  - ACL.{ATTRIBUTES, USEATTRIBUTES}              oneOf -> anyOf
  - AccessPermissionRule.{OBJECTS, USEOBJECTS}   oneOf -> anyOf
  - DEFATTRIBUTES item.{attributes, USEATTRIBUTES} oneOf -> anyOf
    (only in aas-specs-security; API schema doesn't have USEATTRIBUTES
     at DEFATTRIBUTES level.)

Kept as oneOf (XOR):

  - AccessPermissionRule.{ACL, USEACL}
  - AccessPermissionRule.{FORMULA, USEFORMULA}
  - DEFOBJECTS item.{objects, USEOBJECTS}
  - SecurityQueryFilter.{CONDITION, USEFORMULA}

Refs: Review Finding T-13
Made-with: Cursor

* fix(bnf,schema): align idShort with Metamodel Constraint AASd-002 (#580)

IDTA-01001 Constraint AASd-002 normatively defines idShort as:

  ^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$

i.e. at least two characters, starting with a letter, not ending with
a hyphen. The BNF productions in grammar.bnf/access-rules.bnf and the
idShort-path regex in query-json-schema.json, schema.adoc and
openapi.yaml marked the trailing character group optional, so single-
character idShorts (e.g. "A") and trailing-hyphen idShorts (e.g.
"Ab-") were accepted.

Changes:

BNF (<idShort>):
  before: ( L (( L | D | "_" | "-" )* ( L | D | "_" ) )? )
  after:  ( L  ( L | D | "_" | "-" )* ( L | D | "_" ) )
  (L = letter, D = digit)

JSON-Schema / OpenAPI regex:
  before: [A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?
  after:  [A-Za-z][A-Za-z0-9_-]*[A-Za-z0-9_]

Equivalent to AASd-002 (min 2 chars, cannot end with hyphen).

Refs: Review Finding T-06
Made-with: Cursor

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>

* docs(annex): add normative Operation-to-RIGHT mapping (#586)

* docs(annex): add normative "Operation to RIGHT Mapping" annex

Add a new annex that defines, for every AAS HTTP/REST API operation,
the RIGHT (per IDTA-01004 rightsEnum) an access-rule enforcement
point MUST use. The table covers:

- AAS Repository and AAS Service operations (shells, submodels,
  submodel elements, attachments, operation invocation),
- Concept Description Repository operations,
- Registry operations (shell- and submodel-descriptors),
- Discovery operations (/lookup/shells),
- /description and /query.

For PUT on client-addressable resources, the required RIGHT is
listed as "CREATE or UPDATE" and the enforcement point resolves
the right at request time based on existence.

Also register the new annex in nav.adoc.

Refs: Review Finding T-10
Made-with: Cursor

* Update documentation/IDTA-01002-3/modules/ROOT/pages/annex/operation-to-right-mapping.adoc

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* fix ASCIIDOC typo

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* fix ASCIIDOC rendering problems

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

---------

Co-authored-by: sebbader-sap <107036549+sebbader-sap@users.noreply.github.com>
Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* fix the signature example

* addressing Bo-#11

* fix(bnf,schema): harmonize SecurityQueryFilter and add FILTERLIST (#579)

The API and Security specs gave two incompatible definitions for
SecurityQueryFilter, and the API grammar lacked FILTERLIST entirely.

BNF (partials/bnf/grammar.bnf):
- <SecurityQueryFilter> now uses "FRAGMENT:" <FieldIdentifierFragment>
  instead of <FragmentObject>, aligning with aas-specs-security.
- <AccessPermissionRule> now accepts an optional FILTERLIST block.
- Added the <FieldIdentifierFragment> production family (AAS, SM, SME,
  CD, AAS Descriptor, SM Descriptor) together with the supporting
  *Fragment clauses (SpecificAssetIds, SemanticId, Reference, Endpoint,
  SmDescriptor).

JSON Schema (partials/query-json-schema.json and pages/schema.adoc):
- Added FragmentFieldIdentifier definition (regex sibling of
  modelStringPattern, restricted to fragment-legal fields).
- SecurityQueryFilter.FRAGMENT now $refs FragmentFieldIdentifier
  (was: plain string).
- AccessPermissionRule gains FILTERLIST (array of SecurityQueryFilter).

Refs: Review Finding T-02
Made-with: Cursor

* Incorporate Findings Annex DPP (#626)

* Annex DPP editorial Note

* DPP Annex: remove Note that Metadata not yet published + add transformation for both compressed and expanded + add information which standards of CEN not yet released + editorial

* DPP Annex: add links to serialization in Part 1 + Metdata = ValueOnly + editorial

* Annex DPP: fix xref

* Annex DPP: IDTA-02099 to IDTA-02099-1

* docs(index): add cross-spec alignment matrix (T-08) (#588)

* docs(index): add cross-spec alignment matrix

Add an explicit "Alignment with other AAS Specifications" table
to the Metamodel Versions section, listing the companion
Metamodel (IDTA-01001 v3.2) and Security (IDTA-01004 v3.1)
versions this API version is designed to be used with, plus a
short note on what each companion spec contributes and the
substitution rule for bugfix releases.

Refs: Review Finding T-08
Made-with: Cursor

* new proposal for Alignment of different specification parts

* editorial index.adoc

---------

Co-authored-by: birgitboss <birgit.boss@de.bosch.com>

* limit the aas/submodelversionbyidanddate operations to their own profiles and adding them in the entire api

* add the *VersionByIdAndDate operations to the mapping table

* Fixes for findings as discussed in workstream meeting (#629)

* MJIO-#1 - Fixed DateTimeUtc types for recent changes parameters

* Added changelog for RecentChanges, fixed semantic-id

* Changed explanation about OR execution semantics for recent changes params again.

* Annex DPP: updated and new Sequence Diagrams, finding Bo-#18 (#628)

* Annex DPP: (updated and new) Sequence Diagrams

* Annex DPP: fix xref

* fix xref + fix naming, not recent-changes but history and GetSubmodelVersionByidAndDate and not GetSubmodelByidAndDate, same for AAS

* Annex DPP:  shells/aasId/$history anstelle von parameter "date"

* correct typo

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Adding Notes for Get*VersionByIdAndDate Interfaces (#630)

* adding notes for clarifying the Get*VersionByIdAndDate semantics

* clarification which version is meant in the note

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* allow $aas#submodels[] in the BNF grammar

* fix(query-schema): make ReferenceClause optional for $aas#submodels[]

Align the JSON schema with the BNF grammar change from commit e162df1
which made the ReferenceClause optional after submodels array index.

This allows field identifiers like:
- $aas#submodels[0]           (now valid - just array reference)
- $aas#submodels[0].type      (still valid - with type)
- $aas#submodels[0].keys[0].value  (still valid - with keys)

Changed pattern from:
  submodels\\[[0-9]*\\]\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value))

To:
  submodels\\[[0-9]*\\](?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?

The `(?:...)?` makes the entire `.type` or `.keys[].value` suffix optional,
matching the BNF: "submodels" ( "[" ( [0-9]* ) "]" ) ("." <ReferenceClause>)?

* allow $aas#submodels[] in the BNF grammar

* remove incorrect example for the bool casting

* add query language fixes to the changelog

* change recent changes to major changes and mark them as experimental

* explain mapping / relation of DPP and AAS IDs

* add operaton GetAllSubmodelDescriptorsRecentChanges

* add missing changelog entry for GetAllConceptDescriptionRecentChanges

* change log entry for switching to github pages instead of swaggerhub

* refactor: migrate from SwaggerHub to GitHub Pages URLs

Replace all SwaggerHub references with GitHub Pages Swagger UI links
and convert OpenAPI $ref to relative paths for self-contained specs.

Changes:
1. Documentation links (44 URLs):
   - Replace app.swaggerhub.com with industrialdigitaltwin.io/aas-specs-api
   - Point to GitHub Pages Swagger UI renderer
   - Files: general.adoc, http-rest-api.adoc, service-specifications-and-profiles.adoc

2. OpenAPI $ref references (5,545):
   - Convert absolute SwaggerHub API URLs to relative paths
   - Pattern: https://api.swaggerhub.com/.../V3.2.0#/... → ../SchemaName/openapi.yaml#/...
   - Makes specs self-contained and independent of external services
   - Files: All 35 service specification YAML files + Part2-API-Schemas

Benefits:
- No dependency on SwaggerHub infrastructure
- OpenAPI parsers can resolve relative paths natively
- Faster resolution (local files)
- Standard OpenAPI practice
- Specs remain fully functional for validation and code generation

BREAKING CHANGE: External tools referencing SwaggerHub URLs must update
to use GitHub Pages or raw GitHub URLs for the YAML files.

* add github pages links for openapi

* make the spelling of the recent changes operations consistent and aligned to the grammar

* remove local-only files and scripts again

* Fixing mandatory flag of recent changes (#634)

* RecentChanges and ByIdAndDate Sequence Diagrams - fixes and new diagrams (#631)

* Annex DPP: (updated and new) Sequence Diagrams

* Annex DPP: fix xref

* fix xref + fix naming, not recent-changes but history and GetSubmodelVersionByidAndDate and not GetSubmodelByidAndDate, same for AAS

* Annex DPP:  shells/aasId/$history anstelle von parameter "date"

* fix naming for GetSubmodelsRecentChanges (Plural, not Singular)

* two new seq diagrams for recent changes with AAS Repo and AAS Registry + structuring of chapter + fix figure plantUML configuration

* DPP: remove seq. diagram for registry since not history for Registry

* remove diagrams not refernces in text

* add .puml files for interaction diagrams

* removing unneeded seq-sm-endpoints-recent-changes.puml file

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Fix array index pattern to prevent leading zeros in BNF grammar and J… (#636)

* recreate query filter pr

* added regex tests and fixed ANOS#1, ANOS#4 and MAST#1

* added supplemementalIds

* added review comments from Birgit

* fix errors introduced by merge

* Fix array index pattern to prevent leading zeros in BNF grammar and JSON schemas

This change addresses the issue raised in PR #627 where the array index
pattern [0-9]* would incorrectly accept indices with leading zeros like
"04" or "007".

Changes:
- BNF grammar: Added new <ArrayIndex> ::= 0 | ([1-9][0-9]*) rule
- BNF grammar: Replaced all [0-9]* patterns in array index contexts with <ArrayIndex>
- JSON schema (query-json-schema.json): Updated modelStringPattern and FragmentFieldIdentifier
- OpenAPI schema (Part2-API-Schemas/openapi.yaml): Updated modelStringPattern

The new pattern correctly validates:
- "0" - valid (single zero)
- "1", "42", "123" - valid (no leading zeros)
- "04", "007" - invalid (leading zeros rejected)

This ensures array indices follow standard conventions where leading zeros
are not permitted except for the value zero itself.

---------

Co-authored-by: Martin Stemmer <52048213+Martin187187@users.noreply.github.com>

* fix(schema): align /// with BNF; widen timeLiteralPattern (#582)

* fix(schema): correct Value semantics for $dayOfWeek/$dayOfMonth/$month/$year and timeLiteralPattern

The BNF defines these keys as numeric-extraction functions over a
dateTime expression:

  <dateTimeToNum> ::=
      ( "$dayOfWeek" | "$dayOfMonth" | "$month" | "$year" )
      <ws> "(" <ws> <dateTimeOperand> <ws> ")" <ws>

where <dateTimeOperand> is a DateTimeLiteral, a cast to dateTime, or
a GlobalAttribute (e.g. GLOBAL(UTCNOW)). The argument is therefore a
Value expression that evaluates to a dateTime, not a literal
xsd:dateTime string.

The JSON schemas typed these four keys as
$ref: "#/definitions/dateTimeLiteralPattern"
which forced them to be literal ISO date-time strings and made
constructs like `{"$dayOfWeek": {"$attribute": {"GLOBAL": "UTCNOW"}}}`
invalid even though the BNF explicitly allows them.

timeLiteralPattern was also stricter than the grammar: it rejected
fractional seconds. The BNF <time> is:

  <hour> ":" <minute> ( ":" <second> )? ( "." <fraction> )?

Changes:

- $dayOfWeek, $dayOfMonth, $month, $year -> $ref Value
- timeLiteralPattern pattern
    before: ^[0-9][0-9]:[0-9][0-9](:[0-9][0-9])?$
    after : ^[0-9]{2}:[0-9]{2}(:[0-9]{2})?(\.[0-9]+)?$

Files:
- aas-specs-api: partials/query-json-schema.json, pages/schema.adoc
- aas-specs-security: partials/json/aas-queries-and-access-rules-schema.json, partials/json/formulas-and-logical-expressions.json

Refs: Review Finding T-14
Made-with: Cursor

* use the more explicit integer and attributeitems for dayofweek, dayofmonth, month, year

* fixing input parameter for time cast functions from integer to dateTimeLiteralPattern

---------

Co-authored-by: Sebastian Bader <s.bader@sap.com>
Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* editorial

* GetAssetAdministrationShellDescriptorsRecentChanges removed but new input parameters added to GetAssetAdministrationShellDescriptors

* interaction text and .puml updated since no GetAASDescriptorsRecentChanges any longer

* GetAllSubmodelDescriptorsRecentChanges removed, additional input parameters added to GetAllSubmodelDescriptros (updated From, createdFrom)

* updated changelog

* Profile: GetAASRecentChanges und GetSubmodelsRecentChange ergänzt wo fehlend

* added that _key_ and _keyIdentifier_ shall be both available or both missing, they are presenting a key-value-pair.

* added that _key_ and _keyIdentifier_ shall be both available or both missing, they are presenting a key-value-pair.

* Mapping to https: note added that key and keyIdentifier are mapped to ?assetids

* Added note: Note: GetAllSubmodelsRecentChanges is not included in the superpath because the superpath operations operate on a single Asset Administration Shell.

* editorial only

* GetAllAAS and GetAllSubmodels: added input parameters as for GetAllAASRecentChanges and GetAllSubmodelsRecentChanges

* updated changelog

* fix xref

* Improves openapi.yml files based on recent-changes discussions

* editorial StatusCode Status code in explanation cell

* GetAllConceptDescriptions: add createdFrom and updatedFrom as input parameter

* correct changelog, mixed Submodels and AAS

* update changelog to include Recentchanges operations

* add isShort to GetAllSubmodelsRecentChanges because contained in /submodels + editorial e|

* improve changelog: add experimental in table as well

* attribute cursive (e|) and StatusCode as attribute statusCode

* GetAasxAsycStatus: todo == handleID, explanation from openAPI

* Revert "editorial"

This reverts commit da9e105.

* binary format removed

* Revert "binary format removed"

This reverts commit 4a84f61.

* remove +: not to be printed

* added missing xref for GetFileByPath

* extend table with appliability of serialization modifier for conceptDescription, AASDescriptor and SubmodelDescriptor

* Addresses remarks

* docs: add changelog entries for PRs #579-#590 (#614)

* docs: add changelog entries for PRs #579-#590

* changelog updates

* sync with v3.1.3 changelog updates

* put changelog entries into the correct section

* remove duplicate changelog entry

* Apply suggestion from @aaronzi

Co-authored-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>

* make urls more consistent

Co-authored-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>

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

* Update documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc

* Update documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/http-rest-api.adoc

* Address PR review comments

- Update Entire-API-Collection/V3.2.yaml: convert all SwaggerHub URLs to relative paths
- Update README.md: remove obsolete SwaggerHub synchronization references
- Clarify that GitHub Pages is now the primary hosting platform
- Remove SwaggerHub GitHub Synchronization section

* correct statement about openapi and swaggerhub

* address review comment

* remove put and patch for submodel /$signed

* adding missing bulk result x-semanticid

* Fix serialization media type in GenerateSerializationByIds

Change from 'application/asset-administration-shell-package+xml' to 'application/aas+zip'
to match the profile specifications (AssetAdministrationShellRepositoryServiceSpecification
and SubmodelRepositoryServiceSpecification).

Note: AASX File Server operations (PostAASXPackage, GetAASXByPackageId, etc.) correctly
keep 'application/asset-administration-shell-package'.

* correct the x-semanticId for get /description

* rotate headers in Overview of Service Specifications and the Contained APIs table (requires new .css in antora-ui

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

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* add link to previous swaggerhub apis

* fixing the bnf for interfaces in the endpoints

* 521: Replace ReferenceValue with Reference to include referredSemanticId (#641)

* fix: Replace ReferenceValue with Reference to include referredSemanticId

Replace all OpenAPI references to the custom ReferenceValue schema with
direct references to Part1's Reference schema. This ensures that the
referredSemanticId field is included in value-only serialization, aligning
with IDTA-01001 specification that mandates Normal serialization format for
References.

Changes:
- Replace ReferenceValue references in AnnotatedRelationshipElementValue
- Replace ReferenceValue references in BasicEventElementValue
- Replace ReferenceValue references in ReferenceElementValue
- Replace ReferenceValue references in RelationshipElementValue
- Remove ReferenceValue schema definition entirely
- Use relative paths (../Part1-MetaModel-Schemas/openapi.yaml) instead of
  SwaggerHub URLs

This fixes the semantic information loss issue where referredSemanticId was
being omitted, preventing proper round-tripping of data.

Fixes #521

* correct changelog entry location

---------

Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>

* changelog editorial fixes

* align api to security spec & automated ci/cd test for json schema, bnf (#642)

* align api to security spec

* add ci workflow

* fix testcases

* small editorial fix

* fix merge conflicts

* fix merge conflicts

* change UpdateDataElement from PUT to PATCH to ensure compatibility with the dpp specs

* incorporate changes from the security group affecting query language constructs (#645)

* merge conflicts, change from query language dateTimeLiteralPattern from "format": "date-time" to explicit regex pattern, also in bnf

* replaced `dateTimeLiteralPattern` OpenAPI `format: date-time` with explicit ISO 8601 regex pattern and strengthened `timeLiteralPattern` validation to enforce proper hour/minute/second ranges and timezone handling in Query Language temporal literals

* Synchronize the embedded query schema (#646)

* Fix recent-change identifier schemas (#647)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths (#648)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts (#649)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Align the history retrieval contract (#650)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts

* Align the history retrieval contract

* Require query request bodies (#651)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts

* Align the history retrieval contract

* Require query request bodies

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Clarify query filter and validation semantics (#652)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts

* Align the history retrieval contract

* Require query request bodies

* Clarify query filter and validation semantics

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Align query schema operand cardinalities (#653)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts

* Align the history retrieval contract

* Require query request bodies

* Clarify query filter and validation semantics

* Align query schema operand cardinalities

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Align the query API schema and JSON grammar (#654)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts

* Align the history retrieval contract

* Require query request bodies

* Clarify query filter and validation semantics

* Align query schema operand cardinalities

* Align the query API schema and JSON grammar

* Repair the AASX documentation contracts (#655)

* Synchronize the embedded query schema

* Fix recent-change identifier schemas

* Fix operation invocation paths

* Fix bulk API request contracts

* Align the history retrieval contract

* Require query request bodies

* Clarify query filter and validation semantics

* Align query schema operand cardinalities

* Align the query API schema and JSON grammar

* Repair the AASX documentation contracts

* Fix the AASX upload multipart contract (#656)

* Align the AASX async contract (#657)

* Fix the AASX upload multipart contract

* Align the AASX async contract

* introduce /status/ for /packages-async

...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* add mapping for the packages async status endpoint mapping

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Align temporal literals with the BNF (#658)

* Fix the AASX upload multipart contract

* Align the AASX async contract

* introduce /status/ for /packages-async

...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* add mapping for the packages async status endpoint mapping

* Align temporal literals with the BNF

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Support the full AAS Identifier character range (#659)

* Fix the AASX upload multipart contract

* Align the AASX async contract

* introduce /status/ for /packages-async

...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* add mapping for the packages async status endpoint mapping

* Align temporal literals with the BNF

* Support the full AAS Identifier character range

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Restore service FieldIdentifier applicability (#660)

* Fix the AASX upload multipart contract

* Align the AASX async contract

* introduce /status/ for /packages-async

...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* add mapping for the packages async status endpoint mapping

* Align temporal literals with the BNF

* Support the full AAS Identifier character range

* Restore service FieldIdentifier applicability

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Complete the operation-to-RIGHT mapping (#661)

* Fix the AASX upload multipart contract

* Align the AASX async contract

* introduce /status/ for /packages-async

...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* add mapping for the packages async status endpoint mapping

* Align temporal literals with the BNF

* Support the full AAS Identifier character range

* Restore service FieldIdentifier applicability

* Complete the operation-to-RIGHT mapping

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* Finalize V3.2 release metadata (#662)

* Fix the AASX upload multipart contract

* Align the AASX async contract

* introduce /status/ for /packages-async

...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* add mapping for the packages async status endpoint mapping

* Align temporal literals with the BNF

* Support the full AAS Identifier character range

* Restore service FieldIdentifier applicability

* Complete the operation-to-RIGHT mapping

* Finalize V3.2 release metadata

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* .rotate does not work (#664)

* Fix thumbnail and attachment multipart uploads (#665)

* Fix the AASX upload multipart contract

* Align the AASX async contract

* introduce /status/ for /packages-async

...to keep it similar to the operations-invoke pattern

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* add mapping for the packages async status endpoint mapping

* Align temporal literals with the BNF

* Support the full AAS Identifier character range

* Restore service FieldIdentifier applicability

* Complete the operation-to-RIGHT mapping

* Finalize V3.2 release metadata

* Fix thumbnail and attachment multipart uploads

---------

Co-authored-by: Sebastian Bader <107036549+sebbader-sap@users.noreply.github.com>

* bumping v3.1 links to v3.2

* upgrading semantic id versions to 3.2

* using correct 26-01 links in the dpp annex

---------

Co-authored-by: Sandeep Rudra <111876087+Rudra-sandeep@users.noreply.github.com>
Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com>
Co-authored-by: Martin Stemmer <52048213+Martin187187@users.noreply.github.com>
Co-authored-by: aorzelskiGH <48956800+aorzelskiGH@users.noreply.github.com>
Co-authored-by: Alexander Gordt <100141498+alexgordtop@users.noreply.github.com>
Co-authored-by: Alexander Gordt <alexander.gordt@objective-partner.com>
Co-authored-by: birgitboss <birgit.boss@de.bosch.com>
Co-authored-by: Aaron Zielstorff <aaron.zielstorff@iese.fraunhofer.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants