### Example of Aas4j Class Setup for Native Image

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/decisions/0003-warp-packer.md

This code snippet demonstrates a build-time-only setup for Aas4j's reflection configuration, which is necessary for GraalVM native-image compilation. It generates a properties file included as a resource in the build.

```java
package org.eclipse.esmf.buildtime;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Properties;

import org.eclipse.esmf.esmf.core.util.EsmfCoreUtil;

public class Aas4jClassSetup {

	public static void main(String[] args) throws IOException {
		// This code is executed at build time only.
		// It reproduces the reflection setup of aas4j and creates a properties file from it.
		// This properties file is included in the build as a resource, to be loaded at native initialization time again.

		Properties properties = new Properties();

		// Example: Add properties for reflection configuration
		properties.setProperty("com.example.MyClass.field1", "public");
		properties.setProperty("com.example.MyClass.method1", "public");

		Path outputDir = Paths.get(args[0]);
		Files.createDirectories(outputDir);
		Path outputFile = outputDir.resolve("aas4j-reflection.properties");

		try (OutputStream outputStream = Files.newOutputStream(outputFile)) {
			properties.store(outputStream, "Aas4j Reflection Configuration");
		}
		System.out.println("Generated aas4j-reflection.properties at: " + outputFile.toAbsolutePath());
	}
}
```

--------------------------------

### Get Overview of SAMM CLI Commands

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Use the 'help' command to get an overview of all available commands and subcommands for the SAMM CLI.

```shell
samm help
```

--------------------------------

### OpenAPI Template with Default Queries

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Example of an OpenAPI template file that includes default query parameters and response configurations for GET and POST operations.

```yaml
info:
  termsOfService: 'https://example.com/terms-of-service'

servers:
  - url: https://{environment}.example.com/api/v1
    variables:
      environment:
        default: api
        enum:
          - api
          - sandbox-api

components:
    responses:
      InternalServerError:
        description: An error occurred while processing the request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorResponse'

paths:
  /status:
    get:
      tags:
        - Maintenance
      operationId: getHealthStatus
      description: Check the health status of the service.
      responses:
        "200":
          description: The service is up and running.
        "503":
            description: The service is down.

  __DEFAULT_QUERIES_TEMPLATE__:
    get:
      parameters:
        - name: request-id
          in: header
          description: The unique identifier for the request. If it isn't provided, it will be auto-generated.
          required: false
          schema:
            type: string
            format: uuid
      responses:
        "500":
          $ref: '#/components/responses/InternalServerError'
    post:
      parameters:
        - name: request-id
          in: header
          description: The unique identifier for the request. If it isn't provided, it will be auto-generated.
          required: false
          schema:
            type: string
            format: uuid
```

--------------------------------

### AbstractGenerator Output Stream Example

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-documentation-generation.adoc

This example demonstrates how to define a method for calling generators, which accepts a Function<String, java.io.OutputStream> to manage output file streams.

```java
public <T extends AbstractGenerator> void generate(T generator, Function<String, OutputStream> outputStreamProvider) throws IOException {
    generator.generate(outputStreamProvider);
}
```

--------------------------------

### Get Help for SAMM CLI Subcommands

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Use the 'help' command followed by specific subcommands to get detailed help information. This is useful for understanding options and usage for particular functionalities.

```shell
samm help aspect
```

```shell
samm help aspect to svg
```

```shell
samm help aspect validate
```

--------------------------------

### Aspect Model Naming and Versioning Example

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Turtle syntax defining an Aspect Model, focusing on prefix, name, preferred name, and description.

```turtle
@prefix : <urn:samm:{example-ns}.myapplication:1.0.0#> . # <1>
@prefix samm: <{samm}> .

:Movement a samm:Aspect ; # <3>
   samm:name "Movement" ;
   samm:preferredName "My Movement Aspect"@en ; # <2>
   samm:description "Aspect for movement information"@en .
```

--------------------------------

### OpenAPI Specification - Offset Paging Query Parameter

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Specific query parameter ('start') for offset-based paging in OpenAPI, indicating the starting index.

```JSON
"name" : "start",
"in" : "query",
"description" : "Starting index which is starting by 0",
"required" : false,
"schema" : {
  "type" : "number"
}
```

--------------------------------

### Define Resource Path and Parameter File

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Example of using the samm-cli to generate an OpenAPI specification from an Aspect Model, specifying a custom resource path and a parameter file.

```shell
samm aspect _AspectModel.ttl_ to openapi -b "https://www.example.org" -r "/resources/\{resourceId}" -p _fileLocation_
```

--------------------------------

### Formatted Aspect Data Output Example (Bash)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-static-meta-classes.adoc

An example of how Aspect data can be nicely formatted for console output, including nested structures and indentation. This illustrates the desired output format that the Java code aims to achieve.

```bash
[Movement]
- Is moving: YES
- Speed: 35 km/h
- Speed limit warning: yellow
- Position:
  - Latitude: 45.2
  - Longitude: 32.7
  - Altitude: 17.0
...
```

--------------------------------

### OpenAPI Template for Security Schemas (OAuth2)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Example of an OpenAPI template file demonstrating the configuration of OAuth2 security schemes, including authorization flows and scopes.

```yaml
security:
  - OAuth2:
      - read:aspects

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://{environment}.example.com/oauth2/authorize
          tokenUrl: https://{environment}.example.com/oauth2/token
          scopes:
            read:aspects: Read access to aspects
            write:aspects: Write access to aspects

paths:
  __DEFAULT_QUERIES_TEMPLATE__:
    post:
      security:
        - OAuth2:
            - read:aspects
            - write:aspects
```

--------------------------------

### Define Resource Path and Parameter File (Java JAR)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Example of using the Java JAR version of samm-cli to generate an OpenAPI specification, specifying a custom resource path and a parameter file.

```shell
java -jar samm-cli-{esmf-sdk-version}.jar aspect _AspectModel.ttl_ to openapi -b "https://www.example.org" -r "/resources/\{resourceId}" -p _fileLocation_
```

--------------------------------

### Example Aspect and Operation Definition (Turtle)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Defines a 'Movement' aspect and its associated 'getSpeed' operation using Turtle syntax. This example illustrates how operations, inputs, and outputs are structured within SAMM.

```turtle
:Movement a samm:Aspect ;
   samm:preferredName "movement"@en ;
   samm:description "Aspect for movement information"@en ;
   samm:properties ( ) ;
   samm:operations ( :getSpeed ) ;
   samm:events ( ) .

:getSpeed a samm:Operation ;
   samm:preferredName "Get speed"@en ;
   samm:description "Returns the current speed"@en ;
   samm:input ( :getSpeedInput ) ;
   samm:output :getSpeedOutput .

:getSpeedOutput a samm:Property ;
   samm:preferredName "getSpeed output"@en ;
   samm:description "Return value of the getSpeed operation"@en ;
   samm:characteristic :OutputCharacteristic .

:OutputCharacteristic a samm:Characteristic ;
   samm:preferredName "Output"@en ;
   samm:description "Describes the output of the getSpeed operation"@en ;
   samm:dataType :OutputEntity .

:OutputEntity a samm:Entity ;
   samm:preferredName "Output entity"@en ;
   samm:description "The structured response of getSpeed"@en ;
   samm:properties ( :outputEntityMessage ) .

:outputEntityMessage a samm:Property ;
   samm:characteristic samm-c:Text .

:getSpeedInput a samm:Property ;
   samm:preferredName "getSpeed input"@en ;
   samm:description "The input to the getSpeed operation"@en ;
   samm:characteristic samm-c:Text .
```

--------------------------------

### Define Custom Velocity Macro

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-code-generation.adoc

Example of a Velocity template file used to customize generated code sections like the file header.

```vm
include::example$sample-file-header.vm[]
```

--------------------------------

### Build ESMF SDK Core Components

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/README.md

Commands to compile and install the core modules of the ESMF SDK using Maven. The first command builds core components excluding the CLI, while the second specifically targets the CLI tool.

```bash
mvn -pl '!org.eclipse.esmf:samm-cli' clean install
```

```bash
mvn -pl org.eclipse.esmf:samm-cli clean verify
```

--------------------------------

### Aspect Naming and Versioning Example

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

This snippet shows a Turtle definition of an Aspect with preferred names and versioning information. It illustrates how these elements map to the OpenAPI specification's info block.

```turtle
@prefix : <urn:samm:{example-ns}.myapplication:1.0.0#> . # <1>
@prefix samm: <{samm}> .

:Test a samm:Aspect; # <3>
    samm:preferredName "TestAspect"@en ; # <2>
    samm:preferredName "TestAspekt"@de .

```

--------------------------------

### Example Aspect Definition (JSON)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Defines a 'Movement' aspect with its address, description, and parameters. This serves as a basic structure for an aspect in the SAMM model.

```JSON
{
 "channels" : {
    "Movement" : {
      "address" : "movement/0.0.1/Movement",
      "description" : "This channel for updating Movement Aspect.",
      "parameters" : {
        "namespace" : "movement",
        "version" : "0.0.1",
        "aspect-name" : "Movement"
      },
      "messages" : {}
    }
  }
}
```

--------------------------------

### Generate JSON Payload

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Generates example JSON payload data for an Aspect Model. Options include specifying the output path and using a custom resolver.

```bash
samm aspect AspectModel.ttl to json
```

--------------------------------

### Generate Parquet Payload

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Generates example Apache Parquet payload data for an Aspect Model. Options include specifying the output path and using a custom resolver.

```bash
samm aspect AspectModel.ttl to parquet
```

--------------------------------

### OpenAPI Paths Block Mapping

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

This JSON snippet shows how the Aspect name is used to generate path definitions in the OpenAPI specification. It includes an example of a GET operation for a resource.

```JSON
{
 "paths" : {
    "/{tenant-id}/test" : { // <3>
      "get" : {
        "tags" : [ "Test" ], // <3>
        "operationId" : "getTest" // <3>
      }
    }
  }
}

```

--------------------------------

### Generate HTML Documentation for Aspect Model

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Generates HTML documentation for an Aspect Model. Options include specifying output file, CSS styles, language, and a custom resolver.

```bash
samm aspect AspectModel.ttl to html
```

```bash
samm aspect AspectModel.ttl to html -o c:\\Model.html
```

```bash
samm aspect AspectModel.ttl to html -c c:\\styles.css
```

```bash
samm aspect AspectModel.ttl to html -l de
```

```bash
samm aspect AspectModel.ttl to html --custom-resolver myresolver.bat
```

--------------------------------

### Enforce Project Coding Conventions

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/README.md

Commands to verify or automatically apply project-specific code style and formatting rules using Spotless and Checkstyle plugins.

```bash
mvn spotless:check
mvn checkstyle:check
mvn spotless:apply
```

--------------------------------

### Generate SQL Script from Aspect Model

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Creates an SQL script for setting up a table based on an Aspect Model. Allows customization of output, language, SQL dialect, mapping strategy, and comment inclusion. Can also define custom columns.

```bash
samm aspect AspectModel.ttl to sql
```

```bash
samm aspect AspectModel.ttl to sql --custom-column "column_name STRING NOT NULL COMMENT 'custom'"
```

--------------------------------

### Mutating Property Values

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-static-meta-classes.adoc

Example of updating a property value on a model instance using the setValue method. Note that this requires setter generation to be enabled.

```java
SPEED.setValue(movementInstance, 12.0f);
```

--------------------------------

### Import Namespace Package

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Import a Namespace Package (from a file or URL) into a specified models directory. The --models-root option is required when importing.

```bash
samm package MyPackage.zip import --models-root c:\models
```

--------------------------------

### AsyncAPI Specification for SpeedUpdateEvent

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

An example of an AsyncAPI v3.1.0 specification defining channels, operations, messages, and schemas related to the SpeedUpdateEvent. This is used for asynchronous communication protocols.

```json
{
"channels" : {
    "Movement" : {
      "address" : "movement/0.0.1/Movement",
      "description" : "This channel for updating Movement Aspect.",
      "parameters" : {
        "namespace" : "movement",
        "version" : "0.0.1",
        "aspect-name" : "Movement"
      },
      "massages" : {
        "SpeedUpdateEvent" : {
          "$ref" : "#/components/messages/SpeedUpdateEvent" // <1>
        },
      }
    }
  },
  "operations" : {
    "SpeedUpdateEvent" : {
      "action" : "receive", // <5>
      "channel" : {
        "$ref" : "#/channels/Movement"
      },
      "messages" : [ {
        "$ref" : "#/channels/Movement/messages/SpeedUpdateEvent" // <1>
      } ]
    },
  },
  "components" : {
    "messages" : {
      "SpeedUpdateEvent" : { // <1> <2>
        "name" : "SpeedUpdateEvent", // <1>
        "title" : "Speed Update",
        "summary" : "This is event for update speed property",
        "content-type" : "application/json",
        "payload" : {
          "$ref" : "#/components/schemas/SpeedUpdateEvent" // <1>
        }
      }
    },
    "schemas" : {
      "SpeedUpdateEvent" : { // <1>
        "type" : "object",
        "properties" : {
          "updatedSpeed" : { // <3> <4>
            "title" : "updated speed",
            "type" : "string",
            "description" : "the updated speed value"
          },
          "updateAcceleration" : { // <3> <4>
            "title" : "updated acceleration",
            "type" : "string",
            "description" : "the updated acceleration value"
          }
        }
      }
    }
  }
}

```

--------------------------------

### Create AsyncAPI Spec (Native Executable)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Command to generate an AsyncAPI specification from an Aspect Model using the native SAMM CLI executable.

```shell
samm aspect _AspectModel.ttl_ to asyncapi -ca "123-456/789-012/test/1.0.0/Aspect"
```

--------------------------------

### Example Maximum Count Exceeded Violation

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/error-codes.adoc

Shows a cardinality violation where a property is used more times than permitted. This helps in identifying and correcting redundant property declarations.

```text
ERR_MAX_COUNT: Property :description is used 3 times on :Aspect, but may only be used 1 time.
```

--------------------------------

### Get Aspect Model Usage

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Show where model elements are used within an Aspect Model. This command can take an Aspect Model file or an element URN as input.

```bash
samm aspect AspectModelFile.ttl usage
```

--------------------------------

### Generate HTML Documentation

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-documentation-generation.adoc

Generates HTML reference documentation for an Aspect model, including an overview diagram and descriptions of model elements. HTML generation can be controlled via options, and the generator is initialized with the model context.

```java
HtmlGenerator htmlGenerator = new HtmlGenerator(new HtmlGenerationConfiguration());
htmlGenerator.generate(model, outputStreamProvider);
```

--------------------------------

### Load Aspect Model from File

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-aspect-tooling.adoc

Demonstrates how to instantiate the AspectModelLoader and load an Aspect Model from a file. This process automatically handles meta-model version translation.

```java
AspectModelLoader loader = new AspectModelLoader();
AspectModel model = loader.load(new File("path/to/model.json"));
```

--------------------------------

### Configure GitHub Server in Maven Settings

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/maven-plugin.adoc

Configure your Maven settings.xml to include server entries for GitHub repositories used by the plugin. This is necessary when using the GitHubStrategy for model resolution.

```xml
<settings>
  <!-- ... -->
  <servers>
    <!-- ... -->
    <server>
      <id>my-gh-repo</id>
      <configuration>
        <!-- Which repository on GitHub does this server refer to -->
        <repository>ownername/repositoryname</repository>
        <!-- Which directory inside the repository is the models root -->
        <directory>src/main/resources/aspects</directory>
        <!-- branch (or tag) -->
        <branch>main</branch>
        <!-- Only required for private repositories: GitHub access token -->
        <token>...</token>
      </configuration>
    </server>
  </servers>
</settings>
```

--------------------------------

### Example Data Type Violation

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/error-codes.adoc

Illustrates a data type mismatch for a property. This occurs when a property is assigned a value of an incorrect data type according to the SAMM specification.

```text
ERR_TYPE: Property :speed on :Vehicle uses data type :string, but only :decimal is allowed.
```

--------------------------------

### Generate HTML Documentation with Maven Plugin

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/maven-plugin.adoc

Configure the Maven plugin to generate HTML reference documentation for Aspect Models. Specify the root directory for models, include specific models by URN, and define the output directory for the generated files.

```xml
<build>
  <plugins>
    <plugin>
      <artifactId>esmf-aspect-model-maven-plugin</artifactId>
      <executions>
        <execution>
          <id>generate-html-doc</id>
          <goals>
            <goal>generateDocumentation</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <modelsRootDirectory>$\{path-to-models-root}</modelsRootDirectory>
        <includes>
          <include>$\{urn-of-aspect-model-to-be-included}</include>
        </includes>
        <outputDirectory>$\{directory-for-generated-source-files}</outputDirectory>
      </configuration>
    </plugin>
  </plugins>
</build>
```

--------------------------------

### Example of ERR_INVALID_PROPERTY with optional property

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/error-codes.adoc

This Turtle snippet demonstrates how to correctly reference an optional property within an Entity's 'samm:properties' list using a blank node.

```turtle
:MyEntity a samm:Entity ;
   samm:properties ( :directProperty [ samm:property :optProp ; samm:optional "true"^^xsd:boolean ] ) .
```

--------------------------------

### Add ESMF Aspect Model Starter Dependency

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/ROOT/partials/esmf-aspect-model-starter-artifact.adoc

Configures the esmf-aspect-model-starter dependency for build automation tools. This library is required to work with ESMF aspect models in your application.

```maven
<dependency>
    <groupId>org.eclipse.esmf</groupId>
    <artifactId>esmf-aspect-model-starter</artifactId>
    <version>{esmf-sdk-version}</version>
</dependency>
```

```gradle
implementation 'org.eclipse.esmf:esmf-aspect-model-starter:{esmf-sdk-version}'
```

```kotlin
implementation("org.eclipse.esmf:esmf-aspect-model-starter:{esmf-sdk-version}")
```

--------------------------------

### Example Pattern Violation

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/error-codes.adoc

Demonstrates a value constraint violation where a property's value does not conform to a specified regular expression pattern. This is common for fields like version numbers or identifiers.

```text
ERR_PATTERN: Property :version on :Aspect has value "1.0", which does not match the required pattern "^\d+\.\d+\.\d+$".
```

--------------------------------

### Create AsyncAPI Spec (Java JAR)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Command to generate an AsyncAPI specification from an Aspect Model using the Java version of the SAMM CLI.

```shell
java -jar samm-cli-{esmf-sdk-version}.jar aspect _AspectModel.ttl_ to asyncapi -ca "123-456/789-012/test/1.0.0/Aspect"
```

--------------------------------

### Configure Maven Plugin for JSON Schema Generation

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/maven-plugin.adoc

Example of how to configure the esmf-aspect-model-maven-plugin in your pom.xml to generate a JSON Schema from an Aspect Model. Specify the root directory of your models, the models to include, and the output directory for the generated schema.

```xml
<build>
  <plugins>
    <plugin>
      <artifactId>esmf-aspect-model-maven-plugin</artifactId>
      <executions>
        <execution>
          <id>generate-json-schema</id>
          <goals>
            <goal>generateJsonSchema</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <modelsRootDirectory>$\ {{path-to-models-root}}</modelsRootDirectory>
        <includes>
          <include>$\ {{urn-of-aspect-model-to-be-included}}</include>
        </includes>
        <outputDirectory>$\ {{directory-for-generated-source-files}}</outputDirectory>
      </configuration>
    </plugin>
  </plugins>
</build>
```

--------------------------------

### Accessing Meta Class Information

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-static-meta-classes.adoc

Explains how to retrieve general model information and property details from generated Meta classes.

```APIDOC
## Meta Class Overview

### Description
Meta classes provide static fields and methods to access model metadata, including namespaces, URNs, and property definitions.

### General Information Fields
- **NAMESPACE** (String) - The namespace of the Model Element.
- **MODEL_ELEMENT_URN** (String) - The full URN of the Model Element.
- **CHARACTERISTIC_NAMESPACE** (String) - The Characteristic Namespace of the Model.
- **INSTANCE** (MetaClass) - The singleton instance of the Meta class.

### Property Access Methods
- **getModelClass()** (Class) - Returns the Java Class for the Model Element.
- **getAspectModelUrn()** (AspectModelUrn) - Returns the URN of the Model Element.
- **getMetaModelVersion()** (KnownVersion) - Returns the used Meta Model version.
- **getName()** (String) - Returns the name of the Model Element.
- **getProperties()** (List<StaticProperty>) - Returns all StaticProperties of the Model Element.
- **getAllProperties()** (List<StaticProperty>) - Returns all StaticProperties, including inherited ones.

### Usage Example
```java
// Accessing properties safely
List<Property> allProperties = getAllProperties();
if (mode != "VERBOSE") {
   allProperties.removeAll(List.of(MetaMovement.SPEED_LIMIT, MetaMovement.SPEED_LIMIT_WARNING));
}
```
```

--------------------------------

### Generate Java Classes with Name Postfix

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Generates Java domain classes for a Static Meta Model with a specified name postfix. This is useful for appending a consistent suffix to generated class names.

```bash
samm aspect AspectModel.ttl to java -namePostfix "Postfix"
```

--------------------------------

### Iterating Over Aspect Properties with Java

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-static-meta-classes.adoc

Demonstrates how to iterate over all properties of an Aspect Model and print their names and values. This approach uses generated artifacts for property retrieval, allowing the code to remain stable even when the Aspect Model changes.

```java
Movement movement = retrieveMovement();

for ( Property p : getAllProperties() ) {
   System.out.println( String.format( "- %s: %s", p.getName(), p.getValue( movement ) ) );
}
```

--------------------------------

### Import JSON Schema to Aspect Model

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Imports a JSON Schema file and translates it into an Aspect Model. The --output-directory option specifies where to write the generated files. Use --json-schema if the input file does not end with .schema.json.

```bash
samm import MyModel.schema.json urn:org.example:1.0.0#MyModel --output-directory models
```

--------------------------------

### License Header Template for Java Files

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/CONTRIBUTING.md

This template provides the required format for license and copyright headers in Java source files. It includes placeholders for the year and company names, specifies the license (MPL-2.0), and references the AUTHORS file. Ensure all involved companies and contribution years are listed.

```Java
/*
 * Copyright (c) {YEAR} {NAME OF COMPANY X}
 * Copyright (c) {YEAR} {NAME OF COMPANY Y}
 *
 * See the AUTHORS file(s) distributed with this work for additional
 * information regarding authorship.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 *
 * SPDX-License-Identifier: MPL-2.0
 */
```

--------------------------------

### Defining Container Property Chains

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-static-meta-classes.adoc

Shows how to define Property Chains that include container types like Optional or Collection. These chains propagate the container type through the navigation path.

```java
ContainerPropertyChain<Movement, Optional<Float>, Float> altitude = PropertyChain.from( MetaMovement.POSITION ).to( MetaSpatialPosition.ALTITUDE );

ContainerPropertyChain<Aspect, List<String>, String> nestedEntityCollectionStrings = PropertyChain.from( MetaAspect.ENTITY ).viaCollection( MetaEntity.SUB_ENTITY_LIST ).to( MetaSubEntity.STRING_PROPERTY );
```

--------------------------------

### Programmatically Create an Aspect Model

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-model-creation.adoc

Demonstrates the use of SammBuilder to programmatically create an Aspect Model, including aspects, properties, traits, and characteristics.

```java
AspectModel model = SammBuilder.model("MyAspectModel");

Aspect vehicleAspect = model.aspect("Vehicle");
vehicleAspect.property("VIN", xsd.string());
vehicleAspect.property("Model", xsd.string());

Aspect engineAspect = model.aspect("Engine");
engineAspect.property("Cylinders", xsd.integer());
engineAspect.property("Displacement", xsd.doublePrecision());

vehicleAspect.add(engineAspect);

Trait engineTrait = engineAspect.trait("EngineTrait");
engineTrait.characteristic("Turbocharged", xsd.booleanType());

model.add(vehicleAspect);
model.add(engineAspect);
```

--------------------------------

### Filter Properties using Static Meta Model

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-static-meta-classes.adoc

Demonstrates how to filter properties from an Aspect Model using generated static meta classes, providing compile-time safety instead of string-based filtering.

```java
Movement movement = retrieveMovement();
List<Property> allProperties = getAllProperties();
if (mode != "VERBOSE") {
   allProperties.removeAll( List.of( MetaMovement.SPEED_LIMIT, MetaMovement.SPEED_LIMIT_WARNING ) );
}

for ( Property p : getAllProperties() ) {
   System.out.println( String.format( "- %s: %s", p.getName(), p.getValue( movement ) ) );
}
```

--------------------------------

### Export Aspect Model to Package

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Exports an Aspect Model or a complete namespace to a Namespace Package (.zip). Use the --output option to specify the output file path.

```bash
samm package urn:samm:org.eclipse.example.myns:1.0.0 export --output package.zip
```

```bash
samm package AspectModel.ttl export --output package.zip
```

--------------------------------

### Generate Java Classes with Name Prefix

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Generates Java domain classes for a Static Meta Model with a specified name prefix. Use this when you need to enforce a naming convention for generated classes.

```bash
samm aspect AspectModel.ttl to java -namePrefix "Prefix"
```

--------------------------------

### Imports for Generating HTML Documentation

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-documentation-generation.adoc

Required imports for generating HTML reference documentation for an Aspect model.

```java
import org.eclipse.esmf.sdk.generator.html.HtmlGenerator;
import org.eclipse.esmf.sdk.generator.html.HtmlGenerationConfiguration;
import org.eclipse.esmf.sdk.model.AspectModel;
import java.io.IOException;
import java.io.OutputStream;
import java.util.function.Function;
```

--------------------------------

### Sorting with Property Accessors

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-static-meta-classes.adoc

Demonstrates how to sort lists using properties as key extractors. Since properties implement the Function interface, they can be passed directly to Comparator.comparing().

```java
List<Movement> bySpeedAscending =
    movements.stream()
             .sorted( Comparator.comparing( MetaMovement.SPEED ) )
             .toList();
```

--------------------------------

### Loading Aspect Models

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-aspect-tooling.adoc

This section details how to load Aspect Models using the AspectModelLoader class, which supports loading from InputStreams, Files, or AspectModelUrns. It also covers automatic translation of older meta-model versions to the latest.

```APIDOC
## Loading Aspect Models

To load an AspectModel, you use the `org.eclipse.esmf.aspectmodel.loader.AspectModelLoader` class. An instance of `AspectModelLoader` provides `load()` methods to load an Aspect Model from an InputStream, one or multiple Files, or a number of `AspectModelUrn`.

The `AspectModelLoader` loads Aspect Models based on the most recent version of the Semantic Aspect Meta Model and previous versions: Models based on older meta model versions are automatically translated to models corresponding to the latest meta model version.

The resulting `AspectModel` object contains information about the loaded model elements, their namespaces and the files they were defined in. The `AspectModel` provides the methods `elements()`, `files()` and `namespaces()` as well as the convenience methods `aspects()` (which returns all Aspect elements in the model) and `aspect()`, which returns the single Aspect element if one exists.

### Request Example
```java
// Assuming AspectModelLoader and necessary imports are available
// AspectModelLoader loader = new AspectModelLoader();
// AspectModel model = loader.load(inputStream);
```

### Response
#### Success Response (200)
- **AspectModel** (object) - An object representing the loaded Aspect Model.

#### Response Example
```java
// AspectModel object containing model elements, namespaces, and files.
```
```

--------------------------------

### OpenAPI Info Block Mapping

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

This JSON snippet demonstrates the mapping of Aspect naming and versioning to the 'info' section of an OpenAPI specification. It shows how 'samm:preferredName' and version information are used.

```JSON
{
  "openapi" : "3.0.3",
  "info" : {
    "title" : "TestAspect", // <2> <3>
    "version" : "v1" // <1>
  }
}

```

--------------------------------

### Generate Java Classes with Setters Enabled

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Generates Java domain classes for a Static Meta Model with setters included. Enable this option when you require mutability for the generated domain objects.

```bash
samm aspect AspectModel.ttl to java --enable-setters
```

--------------------------------

### Parameter File Definition (YAML)

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

YAML structure for defining parameters used in OpenAPI generation, corresponding to the resource path definition.

```yaml
resourceId:
  name: resourceId
  in: path
  description: An example resource Id.
  required: true
  schema:
    type: string
```

--------------------------------

### Git Version Tag Syntax

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/CONTRIBUTING.md

Specifies the syntax for Git version tags used in the ESMF SDK. This format includes the version number (e.g., vX.Y.Z) and an optional pre-release identifier, facilitating clear identification of releases and pre-release candidates.

```Git
vX.Y.Z-[pre-release-identifier]
```

--------------------------------

### Configure GitHub Maven Repository

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-aspect-tooling.adoc

Adds the GitHub Packages repository to your Maven pom.xml to enable access to milestone builds of the ESMF SDK.

```xml
<repositories>
  <repository>
    <id>github</id>
    <name>ESMF SDK</name>
    <url>https://maven.pkg.github.com/eclipse-esmf/esmf-sdk</url>
    <releases><enabled>true</enabled></releases>
    <snapshots><enabled>true</enabled></snapshots>
  </repository>
</repositories>
```

--------------------------------

### Understanding Model Resolution

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-aspect-tooling.adoc

Explains the concept of resolution strategies used by AspectModelLoader when models contain references or when loading by URN. Various provided strategies like FileSystemStrategy, ClassPathStrategy, and GitHubStrategy are detailed.

```APIDOC
## Understanding Model Resolution

When loading Aspect Models that may contain references to other model elements or when resolving elements by URN, the `AspectModelLoader` utilizes _resolution strategies_. A resolution strategy is a function that accepts a model element identifier (URN) and returns the content of the file containing that definition.

### Provided Resolution Strategies:
- **FileSystemStrategy**: Resolves elements from files in the file system.
- **ClassPathStrategy**: Resolves model elements from resources in the Java class path.
- **FromLoadedFileStrategy**: Resolves elements from an already loaded `AspectModelFile`.
- **EitherStrategy**: Chains two or more `ResolutionStrategy` instances.
- **ExternalResolverStrategy**: Delegates resolution to an external command.
- **GitHubStrategy**: Resolves model elements from GitHub repositories.

Custom resolution strategies can be implemented by adhering to the `ResolutionStrategy` interface.

### Request Example (Resolving by URN with Custom Strategy)
```java
// Assuming AspectModelLoader, custom ResolutionStrategy, and necessary imports are available
// ResolutionStrategy customStrategy = new MyCustomResolutionStrategy();
// AspectModelLoader loader = new AspectModelLoader(customStrategy);
// AspectModel model = loader.load("urn:example:model:element");
```

### Response
#### Success Response (200)
- **AspectModel** (object) - An object representing the loaded Aspect Model, with elements resolved via the provided strategies.

#### Response Example
```java
// AspectModel object with resolved elements.
```
```

--------------------------------

### Imports for Generating Sample Apache Parquet Payload

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/java-documentation-generation.adoc

Required imports for generating a sample Apache Parquet payload from an Aspect model.

```java
import org.eclipse.esmf.sdk.generator.parquet.ParquetPayloadGenerator;
import org.eclipse.esmf.sdk.model.AspectModel;
import java.io.IOException;
import java.io.OutputStream;
import java.util.function.Function;
```

--------------------------------

### SAMM CLI Models Directory Structure

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Illustrates the required directory structure for SAMM CLI to resolve model element references across multiple files. This structure organizes models by namespace and version.

```text
_models root_
└── com.mycompany.myproduct
    ├── 1.0.0
    │   ├── MyAspect.ttl
    │   ├── MyEntity.ttl
    │   └── myProperty.ttl
    └── 1.1.0
        └── MyAspect.ttl
```

--------------------------------

### Generate SQL Script from Aspect Model

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/maven-plugin.adoc

Configure the Maven plugin to generate an SQL table creation script from an Aspect Model. Specify the root directory for models, which models to include, and the output directory for the generated script.

```xml
<build>
  <plugins>
    <plugin>
      <artifactId>esmf-aspect-model-maven-plugin</artifactId>
      <executions>
        <execution>
          <id>generate-sql</id>
          <goals>
            <goal>generateSql</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <modelsRootDirectory>$\{path-to-models-root}</modelsRootDirectory>
        <includes>
          <include>$\{urn-of-aspect-model-to-be-included}</include>
        </includes>
        <outputDirectory>$\{directory-for-generated-source-files}</outputDirectory>
      </configuration>
    </plugin>
  </plugins>
</build>
```

--------------------------------

### AsyncAPI Specification Mapping for Naming and Versioning

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

JSON structure representing the AsyncAPI specification generated from the Aspect Model, showing mapping for title, version, and description.

```JSON
{
  "asyncapi" : "3.1.0",
  "info" : {
    "title" : "My Movement Aspect MQTT API", // <2>
    "version" : "v1", // <1>
    "description" : "Aspect for movement information" // <3>
  }
}
```

--------------------------------

### Generate OpenAPI Specification

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Converts an Aspect model to an OpenAPI specification. Use the -l option to specify the language.

```bash
samm aspect AspectModel.ttl to openapi -l de
```

--------------------------------

### Pretty-print Aspect Model

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Pretty-prints an Aspect Model to standard output or a specified file.

```bash
samm aspect AspectModel.ttl prettyprint
```

```bash
samm aspect AspectModel.ttl prettyprint -o c:\\Results\\PrettyPrinted.ttl
```

```bash
samm aspect AspectModel.ttl prettyprint -w
```

--------------------------------

### Generate Java Classes with Fluent Setters

Source: https://github.com/eclipse-esmf/esmf-sdk/blob/main/documentation/developer-guide/modules/tooling-guide/pages/samm-cli.adoc

Generates Java domain classes with fluent setters, allowing for method chaining. This option requires setters to be enabled.

```bash
samm aspect AspectModel.ttl to java --enable-setters --setter-style "FLUENT"
```