Merge pull request #269 from bci-oss/feature/OMP-SDK-248-document-OpenAPI-JSON-schema-mapping

Describe the mapping between Aspects and the OpenAPI specification.

Author: atextor

documentation/developer-guide/modules/tooling-guide/pages/bamm-cli.adoc

@@ -3,7 +3,7 @@
 [[bamm-cli]]
 = BAMM CLI
 
-The BAMM CLI is a command line tool for the validation of Aspect models and the generation of artifacts, such as documentation or code, from Aspect models.
+The BAMM CLI is a command line tool for the validation of Aspect Models and the generation of artifacts, such as documentation or code, from Aspect Models.
 
 TIP: Download latest version: icon:download[] https://github.com/OpenManufacturingPlatform/sds-sdk/releases/download/v{sds-sdk-version}/bamm-cli-{sds-sdk-version}.jar[bamm-cli-{sds-sdk-version}.jar]
 
@@ -140,10 +140,386 @@ The full command would result in:
 java -jar bamm-cli-{sds-sdk-version}.jar aspect _AspectModel.ttl_ to openapi -b "https://www.example.org" -r "/resources/\{resourceId}" -p _fileLocation_
 ----
 
+=== Mapping between the Aspect Models and the OpenAPI Specification
+
+In this section, a detailed description of the mapping between individual Aspect elements and the OpenAPI specification is given.
+To make it easier to follow, the mapping is explained based on a concrete example, divided into logically coherent blocks.
+Please bear in mind that these blocks are snippets or fragments of a larger whole; viewed in isolation they do not necessarily form a valid or meaningful Aspect Model or OpenAPI specification.
+
+==== Naming and versioning
+
+Please consider the following model fragment, with the attention focused on the numbered elements:
+
+----
+@prefix bamm: <urn:bamm:io.openmanufacturing:meta-model:2.0.0#>.
+@prefix : <urn:bamm:test:2.0.0#>. <1>
+
+:Test a bamm:Aspect; <3>
+    bamm:preferredName "TestAspect"@en ; <2>
+    bamm:preferredName "TestAspekt"@de .
+----
+
+<1> prefix used to build the full URN of :Test Aspect
+<2> the preferred name of the Aspect in language of user's choice
+<3> the name of the Aspect
+
+For the generated OpenAPI Specification, the following mapping would apply:
+
+[source,JSON]
+----
+{
+  "openapi" : "3.0.3",
+  "info" : {
+    "title" : "TestAspect", // <2> <3>
+    "version" : "v2" // <1>
+  }
+}
+----
+
+<1> depending on parameters used when generating the specification, this is either the major version of the full Aspect URN (*2*.0.0), or it can be the full version (`v2.0.0`), if using `-sv` (semantic version) command line switch
+<2> if present, `bamm:preferredName` is used as the value for the `title` element of the specification
+<3> as `bamm:preferredName` is an optional element, in cases when it is missing the name of the Aspect is used instead
+
+The version information as described above is also used in the URL definitions of the `servers` block of the specification:
+
+[source,JSON]
+----
+{
+ "servers" : [ {
+    "url" : "http://mysite/api/v2", // <1>
+    "variables" : {
+      "api-version" : {
+        "default" : "v2" // <1>
+      }
+    }
+  } ]
+}
+----
+
+The name of the Aspect is used to generate several important OpenAPI artifacts, like the path definitions for the API:
+
+[source,JSON]
+----
+{
+ "paths" : {
+    "/{tenant-id}/test" : { // <3>
+      "get" : {
+        "tags" : [ "Test" ], // <3>
+        "operationId" : "getTest" // <3>
+      }
+    }
+  }
+}
+----
+
+and the definitions for request bodies and responses in the corresponding blocks (`requestBodies` and `responses`) of the OpenAPI specification (example omitted for simplicity).
+
+==== Mapping of Aspect and its properties
+
+For each Aspect in the model, an entry in the `components/schemas` part of the OpenAPI specification is generated.
+For an example Aspect from the following fragment:
+
+----
+:Test a bamm:Aspect; <1>
+    bamm:properties (
+        :prop1 <2>
+        [ bamm:property :prop2; bamm:payloadName "givenName"; ] <3>
+        [ bamm:property :prop3; bamm:optional true; ] ). <4>
+
+:prop1 a bamm:Property;
+    bamm:description "Description of Property1"@en; <5>
+    bamm:characteristic :Enum. <6>
+----
+
+an entry like the one given in the following JSON will be generated:
+
+[source,JSON]
+----
+"Test" : { // <1>
+  "type" : "object",
+    "properties" : {
+      "prop1" : { // <2>
+        "description" : "Description of Property1", // <5>
+        "$ref" : "#/components/schemas/urn_bamm_test_2.0.0_Enum" // <6>
+      },
+      "givenName" : { // <3>
+        "$ref" : "#/components/schemas/urn_bamm_test_2.0.0_EntityChar"
+      },
+      "prop3" : { // <4>
+        "$ref" : "#/components/schemas/urn_bamm_test_2.0.0_StringCharacteristic"
+      }
+    },
+    "required" : [ "prop1", "givenName" ] // <2> <3>
+}
+----
+
+<1> the name of the Aspect is used to name the schema object for the aspect
+<2> with plain property references, the name of the property is used to name the property definition
+<3> in cases where a payload name is defined on a specific property, it is used in preference to the plain property name
+<4> if the property use is also defined as optional, the property will not be included in the list of the required properties
+<5> the values of `bamm:description` elements in property definitions are included in the generated JSON
+<6> for each of the properties characteristics an entry in `components/schemas` is generated and referenced here; if the characteristic is of complex type, the whole procedure is applied recursively to the complex type's properties
+
+==== Mapping of Aspect's operations
+
+If the Aspect also has a non-empty list of operations defined, like the one in the following example:
+
+----
+:AspectWithOperation a bamm:Aspect ;
+   bamm:properties ( ) ;
+   bamm:operations ( :testOperation ) .
+
+:testOperation a bamm:Operation ;
+   bamm:input ( :input ) ; <1>
+   bamm:output :output . <2>
+
+:output a bamm:Property ;
+   bamm:characteristic bamm-c:Text . <3>
+
+:input a bamm:Property ;
+   bamm:characteristic bamm-c:Text . <4>
+----
+
+then additional entries are added to the generated OpenAPI specification.
+First, there is an additional entry in the `paths` section of the specification: `/{tenant-id}/aspect-with-operation/*operations*`.
+The available operations are then added to the `components/schemas` part:
+
+[source,JSON]
+----
+{
+ "Operation" : {
+    "allOf" : [ {
+      "$ref" : "#/components/schemas/JsonRpc"
+    }, {
+      "properties" : {
+        "params" : {
+          "type" : "object",
+          "required" : [ "input" ], // <1>
+          "properties" : {
+            "input" : { // <1>
+              "$ref" : "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" // <3>
+            }
+          }
+        },
+        "method" : {
+          "type" : "string",
+          "description" : "The method name",
+          "example" : "testOperation"
+        }
+      }
+    } ]
+  },
+ "OperationResponse" : {
+    "allOf" : [ {
+      "$ref" : "#/components/schemas/JsonRpc"
+    }, {
+      "properties" : {
+        "result" : {
+          "type" : "object",
+          "required" : [ "output" ], // <2>
+          "properties" : {
+            "output" : { // <2>
+              "$ref" : "#/components/schemas/urn_bamm_io.openmanufacturing_characteristic_2.0.0_Text" // <4>
+            }
+          }
+        }
+      }
+    } ]
+  }
+}
+----
+
+<1> the names of the input
+<2> and output parameters are reflected in the properties generated for the request/response objects
+<3> the characteristics are generated
+<4> and referenced as described in the point 6 of the section "Mapping of Aspect and its properties"
+
+As usual, corresponding entries referencing the definitions above are added to the `requestBodies` and `responses` sections (examples omitted for simplicity).
+For technical reasons, there may be a slight variation in the generated JSON depending on whether the aspect has one or more operations defined.
+
+==== Mapping of Collections
+
+There are some additional JSON entries generated for complex types related to various types of collections to facilitate access to the individual elements of these collections via paging.
+As these entries are rather of static character without direct references to any aspect elements, it suffices here to give a short overview about which kind of paging is available for which type of collection:
+
+* a general Collection - cursor and/or offset based paging
+* TimeSeries - cursor, offset and/or time based paging
+
+For all these paging mechanisms, an additional entry with the name `PagingSchema` is generated in the `components/schemas` part of the specification,
+which is then used as the main response schema for the Aspect. Basically, instead of a single Aspect, a collection of Aspects is returned,
+together with optional total number of Aspects available in the collection:
+
+[source,JSON]
+----
+"PagingSchema" : {
+  "type" : "object",
+  "properties" : {
+    "items" : {
+      "type" : "array",
+      "items" : {
+        "$ref" : "#/components/schemas/Test"
+      }
+    },
+    "totalItems" : {
+      "type" : "number"
+    }
+  }
+}
+----
+
+Depending on the concrete paging model selected, there can be additional properties in the `PagingSchema` object.
+For cursor based paging, the `cursor` object denotes the position of the returned Aspects in relation to some other
+uniquely identifiable Aspect (`before` or `after` it):
+
+[source,JSON]
+----
+"cursor" : {
+  "type" : "object",
+  "properties" : {
+    "before" : {
+      "type" : "string",
+      "format" : "uuid"
+    },
+    "after" : {
+      "type" : "string",
+      "format" : "uuid"
+    }
+  }
+},
+----
+
+For offset and time based paging, the data is returned in batches of requested size ("pages"), described using the following properties (the meaning of which is self explanatory):
+
+[source,JSON]
+----
+"totalPages" : {
+  "type" : "number"
+},
+"pageSize" : {
+  "type" : "number"
+},
+"currentPage" : {
+  "type" : "number"
+}
+----
+
+In addition to the `PagingSchema` object, also several new parameters are added to the request parameters section of the generated document,
+with the help of which the size and/or the relative position of the returned data can be controlled.
+All paging mechanisms have the following parameters in common, the meaning of which can be discerned from their descriptions:
+
+[source,JSON]
+----
+{
+  "name" : "count",
+  "in" : "query",
+  "description" : "Number of items to return per call.",
+  "required" : false,
+  "schema" : {
+    "type" : "number"
+  }
+},
+{
+  "name" : "totalItemCount",
+  "in" : "query",
+  "description" : "Flag that indicates that the total counts should be returned.",
+  "required" : false,
+  "schema" : {
+    "type" : "boolean"
+  }
+}
+----
+
+Depending on the exact paging model selected, additional paging specific parameters are available.
+For offset based paging:
+[source,JSON]
+----
+"name" : "start",
+"in" : "query",
+"description" : "Starting index which is starting by 0",
+"required" : false,
+"schema" : {
+  "type" : "number"
+}
+----
+
+For cursor based paging:
+[source,JSON]
+----
+{
+  "name" : "previous",
+  "in" : "query",
+  "description" : "URL to request the previous items. An empty value indicates there are no previous items.",
+  "required" : false,
+  "schema" : {
+    "type" : "string",
+    "format" : "uri"
+  }
+},{
+  "name" : "next",
+  "in" : "query",
+  "description" : "URL to request the next items. An empty value indicates there are no other items.",
+  "required" : false,
+  "schema" : {
+    "type" : "string",
+    "format" : "uri"
+    }
+}, {
+  "name" : "before",
+  "in" : "query",
+  "description" : "The cursor that points to the start of the page of items that has been returned.",
+  "required" : false,
+  "schema" : {
+   "type" : "string",
+    "format" : "uuid"
+  }
+}, {
+  "name" : "after",
+  "in" : "query",
+  "description" : "The cursor that points to the end of items that has been returned.",
+  "required" : false,
+  "schema" : {
+    "type" : "string",
+    "format" : "uuid"
+  }
+}
+----
+
+And finally for the time based paging:
+[source,JSON]
+----
+{
+  "name" : "since",
+  "in" : "query",
+  "description" : "A timestamp that points to the start of the time-based data.",
+  "required" : false,
+  "schema" : {
+    "type" : "string",
+    "format" : "date-time"
+  }
+}, {
+  "name" : "until",
+  "in" : "query",
+  "description" : "A timestamp that points to the end of the time-based data.",
+  "required" : false,
+  "schema" : {
+    "type" : "string",
+    "format" : "date-time"
+  }
+}, {
+  "name" : "limit",
+  "in" : "query",
+  "description" : "Number of items to return per call.",
+  "required" : false,
+    "schema" : {
+    "type" : "number"
+  }
+}
+----
+
 [[models-directory-structure]]
 == Understanding the models directory structure
 
-An Aspect model file can contain an Aspect definition as well as other model elements that are defined in the same versioned namespace, as described in the xref:bamm-specification:ROOT:namespaces.adoc[Namespaces section of the
+An Aspect Model file can contain an Aspect definition as well as other model elements that are defined in the same versioned namespace, as described in the xref:bamm-specification:ROOT:namespaces.adoc[Namespaces section of the
 specification].
 Additionally, it is possible to split one versioned namespace across multiple files, for example to define a Characteristic that is usable in multiple Aspects into its own file.
 In order for BAMM CLI to be able to resolve references to such externally defined model elements, the model files must be organized in a directory structure as follows: