Add the reworked API Versioning chapter + annotations in ChangeLog

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

@@ -72,6 +72,10 @@ Major:
 * Remove “format: byte” from OpenAPI files, as this annotation enforces base64 encodings while base64url is actually required.
 * Remove the QueryParameter “level” from all requests ending with /$metadata in the OpenAPI files.
 * Change the values for the ServiceDescription class from enum to a list of strings in the OpenAPI definition for the Part 2 classes.
+* Clause 11.4.2 and 11.4.3: Change the ValueOnly attribute “annotation” to “annotations” for the AnnotatedRelationshipElementValue class in the examples and schema to match the “AnnotatedRelationshipElement/annotation” attribute. OpenAPI files had the right attribute already.
+* Clause 11.4.2: Add serialisation rule for empty "FileValue/value" and "BlobValue/value".
+* Clause 11.4.3: Adjust ValueOnly schema so that "FileValue/value" and "BlobValue/value" ar optional but non-empty attributes.
+* Clause 12.3: Relax the requirements for API paths and version declaration.
 * (Editorial) Clause 12.8: Added constraint on the return object for ValueOnly requests and that the Level modifier is undefined for Metadata requests
 
 Minor:

documentation/IDTA-01002-3/modules/ROOT/pages/IDTA-01002_HTTP-REST-API.adoc

@@ -94,37 +94,39 @@ Note: this is conformant to the change made in Part 1 V3.0 link:#bib1[[1\]].
 
 == API Versioning
 
-API versioning provides a way to deal with different versions of the same API at the same time. This way, older versions may still be accessible on the same server to provide services to legacy clients without breaking existing functionality.
+The versioning scheme for AAS API related services follows semantic versioningfootnote:[http://semver.org]. Very briefly, this defines version numbers as a format following: <MAJOR>.<MINOR>.<PATCH>.
 
-There are different solutions regarding API versioning involving URL-based versioning, query parameter-based versioning, as well as HTTP header-oriented solutions using custom or standard headers. +
-As different solutions also provide different advantages and disadvantages, *URL-based versioning* has been selected as the most suitable method for the AAS API. Among other advantages, implementation complexity on clients as well as servers is rather low and different versions can be easily accessed through browsers without the need for specific development tools or extensions.
+The major version changes in case of breaking or incompatible changes that need to be addressed by clients. Minor versions add (new) functionality in a backwards compatible way and allow clients with lower minor versions to keep their existing functionality. Patch versions only include backwards compatible bug fixes.
 
-.Example of an URL Scheme for AAS API Versioning
-image::image23.png[Ein Bild, das Dunkel enthält. Automatisch generierte Beschreibung,width=481,height=110]
+AAS API versioning uses the major and minor version as described above. A specific AAS API version uses specific related versions of the metamodel as defined in Clause 1.2. AAS API versions with the same major version must remain compatible, i.e. a client written for an older or a newer minor version must still work. This requires corresponding testing of clients and servers.
 
-.Alternative URL example (TODO)
-image::image23.png[Ein Bild, das Dunkel enthält. Automatisch generierte Beschreibung,width=481,height=110]
+Additionally, "Release candidates" are variants of the implementation of the denoted major version. For example, "3.1.0RC2" should be interpreted as the second (alternative) release candidate for version 3.1.0.
 
-Upcoming implementations of AAS related servers may implement the version prefix “*api/v<X.Y>/*” to provide information of the specific major version regarding AAS Part 2 version, where <X> denotes the implemented major version and <Y> denotes the minor version, e.g. “api/v3.0/” (see Figure 4).
+As multiple versions will be supported in the future, an AAS ecosystem consisting of Registry / Discovery services as well as AAS Repository, Submodel (standalone), or AAS (standalone) services should share a consistent version. Therefore, a consistent interface description in the form of OpenAPI documents shall be provided with each major version.
 
-====
-Note:* all URLs mentioned in this document regarding the REST mapping of the AAS APIs have to be understood with this prefix in mind.
-====
+Upcoming compatibility constraints regarding newer versions will be elaborated in further iterations of this document and related technical descriptions (OpenAPI specification).
 
+API versioning provides a way to deal with different versions of the same API at the same time. This way, older versions may still be accessible on the same server to provide services to legacy clients without breaking existing functionality. 
 
-The versioning scheme for AAS API related services follows semantic versioning footnote:[http://semver.org]. Very briefly, this defines version numbers as a format following: <MAJOR>.<MINOR>.<PATCH>.
+There are different solutions regarding API versioning involving URL-based versioning, query parameter-based versioning, as well as HTTP header-oriented solutions using custom or standard headers.
 
-The major version changes in case of breaking or incompatible changes that need to be addressed by clients. Minor versions add (new) functionality in a backwards compatible way and allow clients with lower minor versions to keep their existing functionality. Patch versions only include backwards compatible bug fixes.
+.Example of an AAS endpoint with URL-based versioning
+image::image23.png[width=481,height=110]
 
-AAS API versioning uses the major and minor version as described above. A specific AAS API version uses specific related versions of the metamodel as defined in Clause 1.2. AAS API versions with the same major version must remain compatible, i.e. a client written for an older or a newer minor version must still work. This requires corresponding testing of clients and servers.
+As different solutions also provide different advantages and disadvantages, URL-based versioning is recommended for the AAS API. Among other advantages, implementation complexity on clients as well as servers is rather low and different versions can be easily accessed through browsers without the need for specific development tools or extensions.
 
-Additionally, “Release candidates” are variants of the implementation of the denoted major version. For example, “3.1.0 RC2” should be interpreted as the second (alternative) release candidate for version 3.1.0. This will still result in the version prefix “/api/v3.1/”.
+Upcoming implementations of AAS related servers may implement the version prefix “api/v<X>/” to provide information of the specific major version regarding AAS Part 2 version, where <X> denotes the implemented major version, e.g. “api/v3/” (see Figure 4). As minor releases of one major version must not contain any breaking changes, the declaration of the minor version can be omitted.
 
-As multiple versions will be supported in the future, an AAS ecosystem consisting of Registry / Discovery services as well as AAS Repository, Submodel (standalone), or AAS (standalone) services should share a consistent version. Therefore, a consistent interface description in the form of OpenAPI documents shall be provided with each major version.
+Nevertheless, AAS servers may decide to use different paths depending on their context, see Figure 5. A client shall not assume that the pattern from Figure 4 is supported by all servers.
 
-Upcoming compatibility constraints regarding newer versions will be elaborated in further iterations of this document and related technical descriptions (OpenAPI specification).
+.Example of an AAS endpoint with an arbitrary path
+image::image88.png[width=481,height=110]
 
-Finally, it is recommended to include an additional "/description” endpoint into each service to further denote information about APIs / servers capabilities. This endpoint provides further information about the API and its supported profiles. The “/description” will be extended with additional information in later versions.
+Finally, it is recommended to include an additional "/description” endpoint into each service to further denote information about APIs / servers capabilities. This endpoint provides further information about the API and its supported profiles, and in particular the version of the profiles. The “/description” will be extended with additional information in later versions.
+
+====
+Note: The profile identifiers provided at the "/description" endpoint (see Clause 10.2.6) contain both the major and minor version declaration.
+====
 
 == Addressing Resources