Merge branch 'main' into apache_parquet_format

Author: atextor

.github/workflows/codeql-scanning.yml

@@ -0,0 +1,47 @@
+name: "CodeQL Scanning"
+
+on:
+  push:
+    branches: [ "main" ]
+    paths-ignore:
+      - 'documentation/decisions/**'
+
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '30 0 * * *'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: 'ubuntu-latest'
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v2
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/pull-request-check.yml

@@ -36,12 +36,13 @@ jobs:
         done
         echo "ONLY_MD=true" >> "$GITHUB_ENV"
 
-    - name: Set up JDK 11
-      uses: actions/setup-java@v3
+    - name: Set up JDK 21
+      id: setup-java
+      uses: actions/setup-java@v4
       if: env.ONLY_MD != 'true'
       with:
-        distribution: 'adopt'
-        java-version: '11'
+        distribution: 'temurin'
+        java-version: '21'
 
     - name: Cache Maven packages
       uses: actions/cache@v3
@@ -62,6 +63,13 @@ jobs:
     - name: Build
       if: env.ONLY_MD != 'true'
       run: |
+        export JAVA_HOME=${{ steps.setup-java.outputs.path }}
+        export PATH=$JAVA_HOME/bin:$PATH
+        echo "Using Java version:"
+        java -version
+        echo "JAVA_HOME: $JAVA_HOME"
+        echo "Maven Java version:"
+        ./mvnw --version
         ./mvnw -B generate-resources -pl documentation -Pantora
         ./mvnw -B clean install -pl esmf-samm-build-plugin
         ./mvnw -B clean package -pl esmf-semantic-aspect-meta-model
@@ -76,4 +84,4 @@ jobs:
         name: samm-artifacts
         path: |
           esmf-semantic-aspect-meta-model/target/*.jar
-          SAMM-*-specification.zip
+          SAMM-*-specification.zip

.github/workflows/release-artifact.yml

@@ -11,46 +11,69 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
-    - name: Set up JDK 11
-      uses: actions/setup-java@v3
+    - name: Set up JDK 21
+      uses: actions/setup-java@v4
       with:
-        distribution: 'adopt'
-        java-version: '11'
-        server-id: ossrh
-        server-username: OSSRH_USERNAME
-        server-password: OSSRH_TOKEN
+        distribution: 'temurin'
+        java-version: '21'
+        server-id: central
+        server-username: CENTRAL_SONATYPE_TOKEN_USERNAME
+        server-password: CENTRAL_SONATYPE_TOKEN_PASSWORD
         gpg-private-key: ${{ secrets.PGP_KEY }}
         gpg-passphrase: PGP_KEY_PASSWORD
-        overwrite-settings: true
+        overwrite-settings: false
 
     - name: Set release version in antora.yml
       uses: mikefarah/yq@master
       with:
         cmd: yq eval -i '.version = "${{ github.event.inputs.release_version }}"' documentation/antora.yml
 
-    - name: Build SAMM artifact and release to OSSRH
+    - name: Build SAMM artifact and create Maven Central bundle
       run: |
         set -x
+        
+        export MAVEN_OPTS="-Xmx4096m"
+        export JAVA_TOOL_OPTIONS="-Dfile.encoding=UTF8"
+        release_version=${{ github.event.inputs.release_version }}
+        
         rm -rf ~/.m2/repository/org/eclipse/esmf
-        ./mvnw -B versions:set -DnewVersion=${{ github.event.inputs.release_version }}
+        ./mvnw -B versions:set -DnewVersion=${ release_version }
         ./mvnw -B versions:commit
         # Since the meta model project itself does not inherit from the parent, we must set its version separately
-        ./mvnw -B versions:set -DnewVersion=${{ github.event.inputs.release_version }} -pl esmf-semantic-aspect-meta-model
+        ./mvnw -B versions:set -DnewVersion=${ release_version } -pl esmf-semantic-aspect-meta-model
         ./mvnw -B versions:commit -pl esmf-semantic-aspect-meta-model
         ./mvnw -B clean generate-resources -pl documentation -Pantora
         ./mvnw -B -U clean install -pl esmf-samm-build-plugin
-        ./mvnw -B -U clean deploy -pl esmf-semantic-aspect-meta-model -Psign,release-build
+        ./mvnw -B -U clean deploy -pl esmf-semantic-aspect-meta-model -Psign,release-build -Dmaven.wagon.httpconnectionManager.ttlSeconds=60
+        
+        echo "Contents of target/central-staging:"
+        ls -lR target/central-staging
+        
+        pushd target/central-staging
+        zip -r -9 ../central-bundle.zip .
+        popd
+    
         cd build/
-        mv site SAMM-${{ github.event.inputs.release_version }}
-        zip -r ../SAMM-${{ github.event.inputs.release_version }}-specification.zip SAMM-${{ github.event.inputs.release_version }}
+        mv site SAMM-${ release_version }
+        zip -r ../SAMM-${ release_version }-specification.zip SAMM-${ release_version }
       env:
-        OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
-        OSSRH_TOKEN: ${{ secrets.OSSRH_TOKEN }}
         PGP_KEY_PASSWORD: ${{ secrets.PGP_KEY_PASSWORD }}
 
-    # If the deployment to OSSRH went through, the following steps will
+    - name: Release to Maven Central
+      if: ${{ !contains( github.event.inputs.release_version, '-M' ) }}
+      run: |
+        token_header=$(printf "$CENTRAL_USERNAME:$CENTRAL_TOKEN" | base64)
+        curl --request POST \
+        --header "Authorization: Bearer $token_header" \
+        --form [email protected] \
+        https://central.sonatype.com/api/v1/publisher/upload
+      env:
+        CENTRAL_USERNAME: ${{ secrets.CENTRAL_SONATYPE_TOKEN_USERNAME }}
+        CENTRAL_TOKEN: ${{ secrets.CENTRAL_SONATYPE_TOKEN_PASSWORD }}
+
+    # If the deployment to Maven Central went through, the following steps will
     # - Commit updated version to release branch
     # - Create Github release
 

.gitignore

@@ -14,8 +14,6 @@ local.properties
 .settings/
 .loadpath
 .recommenders
-package-lock.json
-package.json
 
 # External tool builders
 .externalToolBuilders/

README.md

@@ -99,7 +99,7 @@ To build the Semantic Aspect Meta Model Java artifact, run
 ```
 
 This will compile the code and run all tests. The resulting JAR file can be found under
-esmf-semantic-aspect-meta-model > target. Please be aware, that you need JDK 11 to run build and
+esmf-semantic-aspect-meta-model > target. Please be aware, that you need JDK 21 to run build and
 tests.
 
 Before making a contribution, please take a look at the [contribution guidelines](CONTRIBUTING.md).

documentation/decisions/0007-model-resolution.md

@@ -101,7 +101,9 @@ definitions. I.e., it is readable from top to bottom without encountering undefi
   _models_root_/_namespace_main_part_/_namespace_version_part_/AspectModelFile.ttl.
 * In filesystem-based model storage, the namespace file containing an Aspect model element
   definition should have the same name as the Aspect's local name suffixed with ".ttl".
-  
+* In filesystem-based model storage, there may not be two files with the same names that only differ in casing
+  (e.g., FileName.ttl and filename.ttl) in the same namespace directory.
+
 ### Resolution of files
 
 ![Model structure for loaded models](0007-model-resolution.svg)

documentation/modules/ROOT/pages/datatypes.adoc

@@ -13,6 +13,10 @@ SPDX-License-Identifier: MPL-2.0
 [[data-types]]
 = Data Types
 
+This page details *scalar* data types. Such a scalar data type gets used by a Characteristic to further define a Property.
+
+For modeling Properties that require non-scalar data types, use xref:entities.adoc[Entities].
+
 == Type Hierarchy
 
 The system of types used in the {meta-model-full-name} (and subsequently in the models conforming to
@@ -88,6 +92,9 @@ definition in the respective standards and an informative description of their v
 | `https://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal[rdf:langString]` | Strings with language tags | "Hello"@en, "Hallo"@de. Note that this is written in RDF/Turtle syntax, and that only "Hello" and "Hallo" are the actual values. | {ok}
 |===
 
+NOTE: When using `rdf:langString`, a language tag *must always* be provided using the `@` syntax (e.g., `"Hello"@en`).
+Using a typed literal form such as `"Hello"^^rdf:langString` is *invalid* and *should cause* the model loading or validation to fail.
+
 The following types defined by the XSD and RDF specifications, respectively, are considered
 unsuitable in Aspect Models and _should not_ be used:
 

documentation/modules/ROOT/pages/modeling-guidelines.adoc

@@ -18,10 +18,10 @@ SPDX-License-Identifier: MPL-2.0
 === Notes
 
 * As mentioned in the xref:index.adoc[Introduction], Aspect Models are described in RDF Turtle
-  xref:samm-specification:appendix:bibliography.adoc#turtle[[turtle\]]. The aspect specification will
-  therefore assume basic familiarity with Turtle.
+xref:samm-specification:appendix:bibliography.adoc#turtle[[turtle\]]. The aspect specification will
+therefore assume basic familiarity with Turtle.
 * For the definition of the different Model elements please refer to the
-  xref:meta-model-elements.adoc[Meta Model Elements].
+xref:meta-model-elements.adoc[Meta Model Elements].
 
 
 [[naming-rules]]
@@ -32,22 +32,22 @@ https://en.wikipedia.org/wiki/Naming_convention_(programming)#Java[Java naming c
 classes, properties and methods.
 
 * The names of Aspects, Entities, Events, Constraints and Characteristics follow the naming conventions for
-  Java classes, i.e. UpperCamelCase.
+Java classes, i.e. UpperCamelCase.
 * The names of Properties, Operations and Units follow the naming conventions of Java methods, i.e.
-  lowerCamelCase.
+lowerCamelCase.
 
 [[rdf-turtle-formatting-rules]]
 === RDF/Turtle formatting rules
 
 * Each Aspect Model is defined in a separate TTL (Turtle) file.
 * The Turtle file containing an Aspect Model must have the same name as the Aspect.
 * Aspect Model files must be UTF-8 encoded and should not contain a
-  https://en.wikipedia.org/wiki/Byte_order_mark[byte order mark].
+https://en.wikipedia.org/wiki/Byte_order_mark[byte order mark].
 * There should be one empty line between model element definitions.
 * Indentation should be done with three spaces.
 * There should be a space before every separating semicolon.
 * There should be padding spaces inside RDF lists and anonymous nodes (i.e. inside brackets and
-  square brackets)
+square brackets)
 
 [[attributes-that-all-model-elements-have]]
 === Attributes that all model elements have
@@ -59,13 +59,13 @@ attributes:
 |===
 | Attributes | Description | Required
 | `samm:preferredName` | Human readable name in a specific language. This attribute may be defined
-  multiple times for different languages but only once for a specific language. There should be at
-  least one preferredName defined with an "en" language tag. | {nok}
+multiple times for different languages but only once for a specific language. There should be at
+least one preferredName defined with an "en" language tag. | {nok}
 | `samm:description` | Human readable description in a specific language. This attribute may be
-  defined multiple times for different languages but only once for a specific language. There should
-  be at least one description defined with an "en" language tag. | {nok}
+defined multiple times for different languages but only once for a specific language. There should
+be at least one description defined with an "en" language tag. | {nok}
 | `samm:see` | A reference to a related element in an external taxonomy, ontology or other standards
-  document. The datatype is `xsd:anyURI`. This attribute may be defined multiple times. | {nok}
+document. The datatype is `xsd:anyURI`. This attribute may be defined multiple times. | {nok}
 |===
 
 NOTE: Although both `samm:preferredName` and `samm:description` should be set at least once in every
@@ -125,15 +125,15 @@ addition to the general attributes, every Aspect Model element has the following
 |===
 | Attributes | Description | Required
 | `samm:properties` | The list of Properties of this Aspect. Leaving out this
-  attribute completely is equivalent to having it present with an empty list as value. | {nok}
+attribute completely is equivalent to having it present with an empty list as value. | {nok}
 | `samm:operations` | The list of Operations of this Aspect. Leaving out this
-  attribute completely is equivalent to having it present with an empty list as value. | {nok}
+attribute completely is equivalent to having it present with an empty list as value. | {nok}
 | `samm:events` | The list of Events of this Aspect. | {nok}
 |===
 
 * Aspects follow the naming conventions for Java classes, i.e. UpperCamelCase.
 * Each Aspect Model must be defined in its own file. The file name must be the same as the Aspect's
-  name.
+name.
 * The hierarchical namespace part in the Aspect's URN can be freely chosen.
 
 The definition of an Aspect should therefore have the following structure in TTL syntax; note though
@@ -161,7 +161,7 @@ that all model elements have], Properties have the following attributes:
 |===
 | Attributes | Description | Required
 | `samm:characteristic` | The xref:characteristics.adoc#characteristics[Characteristic] describing
-  this Property. | {ok}
+this Property. | {ok}
 | `samm:exampleValue` | An exemplary value that the Property can take, helping to clarify the intended meaning of the Property.
 This attribute supports both scalar literal values (e.g., xsd:string, xsd:float), an anonymous described scalar value,
 and value references that point to example values (i.e., references to instances of xref:modeling-guidelines.adoc#value-type[samm:Value]).
@@ -474,7 +474,7 @@ for Properties when all of the following conditions are met:
 * The value has a well-known structure consisting of different, separate parts
 * The parts can and should be described in more detail
 * The Property should not be decomposed/deconstructed into an Entity with separate Properties for
-  each part
+each part
 
 One of the main use cases is complex identifiers that encode context information such as provenance
 information, version numbers, locations codes and so on. It is unreasonable to split such a value up
@@ -493,10 +493,10 @@ Characteristic, and after that a complete concrete example is given.
 |===
 | Name | Example Value | Deconstruction Rule | Elements
 | ISO 8601 date | "2019-09-27"^^`xsd:date` | `(\d\{4})-(\d\{2})-(\d\{2})` | ( `:year` "-" `:month`
-  "-" `:day` )
+"-" `:day` )
 | Email Address | "\[email protected]" | `([\w\.-]+)@([\w\.-]+\.\w{2,4})` | ( `:username` "@" `:host` )
 | Hex-encoded color | "0xAC03BE" | `0x([0-9A-Fa-f]\{2})([0-9A-Fa-f]\{2})([0-9A-Fa-f]\{2})` | ( "0x"
-  `:red` `:green` `:blue` )
+`:red` `:green` `:blue` )
 |===
 
 The following code shows the Aspect Model for the first example from the table. Note that when
@@ -538,7 +538,7 @@ include::example$reference-declaration.ttl[tags=content]
 
 As explained in the section xref:modeling-guidelines.adoc#declaring-quantifiable-values-and-measurements[Declaring Quantifiables and Measurements], some values only make sense when they also have a unit assigned to them.
 This unit definition is in many cases fixed at design time, does not change thereafter and therefore at runtime (in the JSON payload for example), only the actual value is transported. +
- There may be scenarios, however, where this permanent fixation on a specific unit might not be sufficient because the unit can only be determined dynamically
+There may be scenarios, however, where this permanent fixation on a specific unit might not be sufficient because the unit can only be determined dynamically
 at runtime, or is a kind of configuration parameter which must be set when the system is being deployed/starting up. In cases like this, a xref:characteristics.adoc#unit-reference-characteristic[UnitReference] characteristic instance can be used to include a dynamic reference to the desired unit from the xref:appendix:unitcatalog.adoc[Unit catalog] and this information is then always included in the payload. The runtime payload refers to the unit using its `samm:curie`, i.e., the unit's URN's element name prefixed with `unit:`.
 
 For example an Aspect with the following model:
@@ -554,7 +554,7 @@ can produce a JSON payload that could look something like this:
 ----
 {
   "value" : 2.25,
-  "unit" : "unit:hectopascal" 
+  "unit" : "unit:hectopascal"
 }
 ----
 
@@ -611,7 +611,7 @@ Entities have the following attributes:
 |===
 | Attributes | Description | Required
 | `samm:properties` | The list of Properties which make up the Entity. Leaving out this
-  attribute completely is equivalent to having it present with an empty list as value.| {nok}
+attribute completely is equivalent to having it present with an empty list as value.| {nok}
 | `samm:extends` | The Entity which is extended by this Entity | {nok}
 |===
 
@@ -707,7 +707,7 @@ Operations have the following attributes:
 |===
 | Attributes | Description | Required
 | `samm:input` | A list of references to Properties that describe the input to the operation. The
-  attribute must be present, but the list may be empty. | {ok}
+attribute must be present, but the list may be empty. | {ok}
 | `samm:output` | A single reference to a Property that describes the output of the operation. |
   {nok}
 |===