extend metadata documentation and open-api specification

Signed-off-by: Johannes Schneider <johannes.schneider@bosch.io>

documentation/README.md

@@ -37,7 +37,8 @@ Watch all resources and start local server serving the Jekyll content at [http:/
 
 ```bash
 cd src/main/resources
-jekyll serve --verbose --unpublished
+bundle install
+bundle exec jekyll serve --verbose --unpublished
 ```
 
 Validate that the HTML does not contain dead links, etc.:

documentation/src/main/resources/Gemfile_ → documentation/src/main/resources/Gemfile

@@ -8,7 +8,7 @@ source "https://rubygems.org"
 #
 # This will help ensure the proper Jekyll version is running.
 # Happy Jekylling!
-gem "jekyll", "~> 3.8.3"
+gem "jekyll", "~> 4.2.2"
 
 # This is the default theme for new Jekyll sites. You may change this to anything you like.
 
@@ -18,11 +18,15 @@ gem "jekyll", "~> 3.8.3"
 
 # If you have any plugins, put them here!
 group :jekyll_plugins do
-  gem "jekyll-sitemap", "~> 1.2.0"
+  gem "jekyll-sitemap", "~> 1.4.0"
 end
 
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem
 gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
 
 # Performance-booster for watching directories on Windows
 gem "wdm", "~> 0.1.0" if Gem.win_platform?
+
+# Webrick is not included in ruby since 3.0.0 https://www.ruby-lang.org/en/news/2020/12/25/ruby-3-0-0-released/
+# This should be fixed with jekyll 4.3 https://github.com/jekyll/jekyll/pull/8524
+gem "webrick", "~> 1.7.0"

documentation/src/main/resources/Gemfile.lock

@@ -0,0 +1,73 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.10)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.15.5)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.8.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-sass-converter (2.2.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.7.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.7)
+    rb-fsevent (0.11.1)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.29.0)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.8.0)
+    webrick (1.7.0)
+
+PLATFORMS
+  arm64-darwin-21
+
+DEPENDENCIES
+  jekyll (~> 4.2.2)
+  jekyll-sitemap (~> 1.4.0)
+  tzinfo-data
+  webrick (~> 1.7.0)
+
+BUNDLED WITH
+   2.3.7

documentation/src/main/resources/openapi/sources/api-2-index.yml

@@ -220,6 +220,10 @@ components:
       $ref: "./parameters/propertyPathPathParam.yml"
     PutMetadataParam:
       $ref: "./parameters/putMetadataParam.yml"
+    GetMetadataParam:
+      $ref: "./parameters/getMetadataParam.yml"
+    DeleteMetadataParam:
+      $ref: "./parameters/deleteMetadataParam.yml"
     RequestedAcksParam:
       $ref: "./parameters/requestedAcksParam.yml"
     ResourcePathPathParam:

documentation/src/main/resources/openapi/sources/parameters/deleteMetadataParam.yml

@@ -0,0 +1,18 @@
+# Copyright (c) 2022 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0
+#
+# SPDX-License-Identifier: EPL-2.0
+name: delete-metadata
+in: header
+description: >-
+  The `delete-metadata` header, which deletes Metadata of the Thing.
+required: false
+schema:
+  type: string
+  description: A string of comma separated JsonPointers to delete from the Metadata of the Thing.

documentation/src/main/resources/openapi/sources/parameters/getMetadataParam.yml

@@ -0,0 +1,18 @@
+# Copyright (c) 2022 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0
+#
+# SPDX-License-Identifier: EPL-2.0
+name: get-metadata
+in: header
+description: >-
+  The `get-metadata` header, which retrieves Metadata of the Thing.
+required: false
+schema:
+  type: string
+  description: A string of comma separated JsonPointers to retrieve from the Metadata of the Thing.

documentation/src/main/resources/openapi/sources/paths/features/definition.yml

@@ -19,6 +19,7 @@ get:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -89,6 +90,8 @@ put:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -187,6 +190,8 @@ patch:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'

documentation/src/main/resources/openapi/sources/paths/features/desiredProperties.yml

@@ -20,6 +20,7 @@ get:
     - $ref: '../../parameters/desiredPropertiesFieldsQueryParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -95,6 +96,8 @@ put:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -205,6 +208,8 @@ patch:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'

documentation/src/main/resources/openapi/sources/paths/features/desiredProperty.yml

@@ -27,6 +27,7 @@ get:
     - $ref: '../../parameters/propertyPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -99,6 +100,8 @@ put:
     - $ref: '../../parameters/propertyPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -185,6 +188,8 @@ patch:
     - $ref: '../../parameters/propertyPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'

documentation/src/main/resources/openapi/sources/paths/features/feature.yml

@@ -21,6 +21,7 @@ get:
     - $ref: '../../parameters/featureFieldsQueryParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -111,6 +112,8 @@ put:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -233,6 +236,8 @@ patch:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'

documentation/src/main/resources/openapi/sources/paths/features/properties.yml

@@ -20,6 +20,7 @@ get:
     - $ref: '../../parameters/propertiesFieldsQueryParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -89,6 +90,8 @@ put:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -198,6 +201,8 @@ patch:
     - $ref: '../../parameters/featureIdPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'

documentation/src/main/resources/openapi/sources/paths/features/property.yml

@@ -26,6 +26,7 @@ get:
     - $ref: '../../parameters/propertyPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -97,6 +98,8 @@ put:
     - $ref: '../../parameters/propertyPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -185,6 +188,8 @@ patch:
     - $ref: '../../parameters/propertyPathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'

documentation/src/main/resources/openapi/sources/paths/things/attribute.yml

@@ -26,6 +26,7 @@ get:
     - $ref: '../../parameters/attributePathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -98,6 +99,8 @@ put:
     - $ref: '../../parameters/attributePathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -187,6 +190,8 @@ patch:
     - $ref: '../../parameters/attributePathPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'

documentation/src/main/resources/openapi/sources/paths/things/attributes.yml

@@ -19,6 +19,7 @@ get:
     - $ref: '../../parameters/attributesFieldsQueryParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/getMetadataParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/conditionParam.yml'
     - $ref: '../../parameters/channelParam.yml'
@@ -86,6 +87,8 @@ put:
     - $ref: '../../parameters/thingIdPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'
@@ -174,6 +177,8 @@ patch:
     - $ref: '../../parameters/thingIdPathParam.yml'
     - $ref: '../../parameters/ifMatchHeaderParamHash.yml'
     - $ref: '../../parameters/ifNoneMatchHeaderParam.yml'
+    - $ref: '../../parameters/putMetadataParam.yml'
+    - $ref: '../../parameters/deleteMetadataParam.yml'
     - $ref: '../../parameters/requestedAcksParam.yml'
     - $ref: '../../parameters/timeoutParam.yml'
     - $ref: '../../parameters/responseRequiredParam.yml'