### SAMM CLI help commands

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

Examples of using the help command to get information about the CLI and its subcommands.

```shell
samm help
```

```shell
samm help aspect
```

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

```shell
samm help aspect validate
```

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

### Offset-based paging start parameter

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

Offset-based paging parameter 'start' to specify the starting index (0-based).

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

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

### OpenAPI Template File Configuration

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 used with the --template-file option to customize generated specifications, including server variables and custom paths.

```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.
```

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

### Define OpenAPI Parameter in YAML

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

Example of a YAML parameter file used with the --parameter-file option to define path parameters like resourceId.

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

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

### 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

Example of a <server> entry in Maven settings.xml for GitHub model resolution. The <id> must match the githubServerId used in the plugin configuration. The <repository>, <directory>, and <branch> are required; <token> is only needed for private repositories.

```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 console output for Movement Aspect

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

Shows the desired formatted console output for the Movement Aspect, including nested entity properties. This is the target output for the generic printing approach.

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

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

### Filtering with PropertyPredicates on and compareOn

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

These examples show how to use PropertyPredicates with the on, compareOn, and onCollection builders to filter streams of Movement and Components objects. The first filters for moving movements and a speed range; the second filters components whose sub-component OEM contains "ACME".

```java
List<Movement> movements = retrieveMovements();

// find all that are currently moving
List<Movement> currentlyMoving =
    movements.stream()
             .filter( PropertyPredicates.on( MetaMovement.IS_MOVING ).isEqualTo( true ) )
             .toList();

// find all that have a speed within the range 10km/h <= speed <= 30km/h
List<Movement> withinSpeedRange =
    movements.stream()
             .filter( PropertyPredicates.compareOn( MetaMovement.SPEED ).withinClosed( 10.0f, 30.0f ) )
             .toList();
```

```java
List<Components> components = retrieveComponents();

var componentOem = PropertyChain.fromCollection( MetaComponent.SUB_COMPONENTS )
                                .to( MetaSubComponent.OEM );
List<Components> withOemAcme =
    components.stream()
              .filter( PropertyPredicates.onCollection( componentOem ).contains( "ACME" ) )
              .toList();
```

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

### Define a simple property chain with PropertyChain.from().to()

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

Creates a PropertyChain from a property of a Meta Class to a nested property. The example chains MetaMovement.POSITION to MetaSpatialPosition.LATITUDE, resulting in a PropertyChain<Movement, BigDecimal>.

```java
PropertyChain<Movement, BigDecimal> latitude =
    PropertyChain.from( MetaMovement.POSITION )
                 .to( MetaSpatialPosition.LATITUDE );
```

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

### Configure validate goal in Maven build

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

Usage example for the validate goal. The default life cycle phase is 'validate'. Configuration requires either modelsRootDirectory or githubServerIds (or both). The includes property is required and specifies the URNs of Aspect Models to validate.

```xml
<build>
  <plugins>
    <plugin>
      <artifactId>esmf-aspect-model-maven-plugin</artifactId>
      <executions>
        <execution>
          <id>validate-aspect-model</id>
          <goals>
            <goal>validate</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <modelsRootDirectory>${path-to-models-root}</modelsRootDirectory>
        <githubServerIds>
          <githubServerId>test-github-config</githubServerId>
        </githubServerIds>
        <includes>
          <include>${urn-of-aspect-model-to-be-included}</include>
        </includes>
      </configuration>
    </plugin>
  </plugins>
</build>
```

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

### Turtle Example for Optional Property in samm:properties

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

Turtle example showing the correct blank node structure for an optional property in a samm:properties list. Use this when defining optional properties with samm:optional "true"^^xsd:boolean.

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

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

### Load meta model RDF files with MetaModelFile

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

Two code blocks that together show how to load meta model RDF files using the MetaModelFile enumeration from the esmf-aspect-meta-model-java module. The first block contains the imports, the second the actual loading logic. Both are include directives that reference the example file LoadMetaModelRdf.java.

```java
include::example$LoadMetaModelRdf.java[tags=imports]
```

```java
include::example$LoadMetaModelRdf.java[tags=loadMetaModelRdf]
```

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

### Git version tag syntax

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

Git version tag syntax for the ESMF SDK. The pre-release identifier is optional; examples include v1.0.0-RC1 and v1.0.0.

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

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

### Generate API implementation skeleton with generateAspectImplementationStub goal

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

Configure the esmf-aspect-model-maven-plugin to generate an API implementation skeleton from an Aspect Model using the `generateAspectImplementationStub` goal. This goal combines Java domain classes, static meta classes, and OpenAPI specification generation, and runs the OpenAPI generator with custom configuration. The `outputFormat` is set to YAML in this example.

```xml
<build>
  <plugins>
    <plugin>
      <artifactId>esmf-aspect-model-maven-plugin</artifactId>
      <executions>
        <execution>
          <id>generate-openapi-spec</id>
          <goals>
            <goal>generateAspectImplementationStub</goal>
          </goals>
        </execution>
      </executions>
      <configuration>
        <modelsRootDirectory>$\{path-to-models-root}</modelsRootDirectory>
        <includes>
          <include>$\{urn-of-aspect-model-to-be-included}</include>
        </includes>
        <aspectApiBaseUrl>http://example.com</aspectApiBaseUrl>
        <outputDirectory>$\{directory-for-generated-source-files}</outputDirectory>
        <outputFormat>yaml</outputFormat>
      </configuration>
    </plugin>
  </plugins>
</build>
```

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

### Define a deeply nested property chain with .via()

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 chain properties through multiple levels using .via() for intermediate steps. The example chains MetaAspect.ENTITY via MetaEntity.SUB_ENTITY to MetaSubEntity.STRING_PROPERTY, producing a PropertyChain<Aspect, String>.

```java
PropertyChain<Aspect, String> nestedString =
    PropertyChain.from( MetaAspect.ENTITY )
                 .via( MetaEntity.SUB_ENTITY )
                 .to( MetaSubEntity.STRING_PROPERTY );
```

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

### Build SDK core and CLI with Maven

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

Builds the SDK core components without the CLI tool, then builds the CLI tool as well. Requires Java 25 and Maven. Run the first command, then the second to include samm-cli.

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

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

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

### ERR_PATTERN - Pattern Violation Example

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

Example error message for a pattern violation. Use this format when reporting that a value does not match the required regular expression pattern.

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

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

### Replace generated success response for GET operations

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

Template to replace the generated success response for GET operations by defining responses."200" explicitly.

```yaml
paths:
  __DEFAULT_QUERIES_TEMPLATE__:
    get:
      responses:
        "200":
          description: The resource was returned successfully with a custom response.
```

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

### 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

Commands to generate HTML documentation with options for output path, custom CSS, language, and custom resolvers.

```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
```

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

### ERR_INVALID_PROPERTY - Invalid Property Example

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

Example error message for an invalid property in a properties list. Use this format when reporting that an element in samm:properties is not a valid property reference.

```text
ERR_INVALID_PROPERTY: Element ':ToggleResult' in the Entity's ':MyEntity' properties list must be a
property - either directly or via a reference to a property with an attribute
samm:optional "true"^^xsd:boolean and/or samm:payloadName or samm:notInPayload "true"^^xsd:boolean.
```

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

### ERR_TYPE - Data Type Violation Example

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

Example error message for a data type violation. The property :speed on :Vehicle is declared with data type :string, but only :decimal is allowed.

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

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

### ERR_MAX_COUNT - Maximum Count Exceeded Example

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

Example error message for a maximum count violation. The property :description is used 3 times on :Aspect, but the maximum allowed is 1 time.

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

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

### Replace generated error responses for GET operations

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

Template to replace generated error responses for GET operations while keeping the generated success response. It defines custom responses for 400, 404, and 500 status codes.

```yaml
components:
  responses:
    BadRequest:
      description: The request was invalid.
    NotFound:
      description: The resource was not found.
    InternalServerError:
      description: An error occurred while processing the request.

paths:
  __DEFAULT_QUERIES_TEMPLATE__:
    get:
      responses:
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalServerError'
```

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

### License header template (Java comment syntax)

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

Required license header template for all contributed files. Replace {YEAR} and {NAME OF COMPANY X/Y} with the year and company names; add a new Copyright line for each involved company. Adapt the comment syntax for non-Java file types.

```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
 */
```

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

### SAMM CLI aspect validation

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

Example of validating an Aspect Model file using the CLI.

```shell
samm aspect AspectModel.ttl validate
```

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

### AsyncAPI info mapping from Aspect

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

Generated AsyncAPI specification header showing the mapping from the Aspect Model. The title uses the preferred name, version depends on the -sv switch, and description is optional. The MQTT API is defined automatically.

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

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

### Aspect with operation in Turtle

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

Example Aspect with an operation, showing input and output properties with Text characteristics.

```turtle
:AspectWithOperation a samm:Aspect ;
   samm:properties ( ) ;
   samm:operations ( :testOperation ) .

:testOperation a samm:Operation ;
   samm:input ( :input ) ; <1>
   samm:output :output . <2>

:output a samm:Property ;
   samm:characteristic samm-c:Text . <3>

:input a samm:Property ;
   samm:characteristic samm-c:Text . <4>
```

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

### SAMM Aspect with SpeedUpdateEvent

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

Defines a SAMM Aspect with an event 'SpeedUpdateEvent'. This example is used to illustrate how events are mapped to AsyncAPI.

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

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

### 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

Use --enable-setters with --setter-style "FLUENT" to generate fluent-style setters.

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

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

### Aspect definition with properties in Turtle

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

Example Aspect definition in Turtle syntax, showing properties with payload names, optional flags, descriptions, and characteristics.

```turtle
:Test a samm:Aspect; <1>
    samm:properties (
        :prop1 <2>
        [ samm:property :prop2; samm:payloadName "givenName"; ] <3>
        [ samm:property :prop3; samm:optional true; ] ). <4>

:prop1 a samm:Property;
    samm:description "Description of Property1"@en; <5>
    samm:characteristic :Enum. <6>
```

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

### Pretty Print Aspect Model with esmf-aspect-model-maven-plugin

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

Configure the esmf-aspect-model-maven-plugin to run the prettyPrint goal. The default life cycle phase is generate-resources. The prettyPrint goal can substitute the removed migrate goal because it loads and automatically migrates the model to the latest meta model version before pretty-printing.

```xml
<build>
  <plugins>
    <plugin>
      <artifactId>esmf-aspect-model-maven-plugin</artifactId>
      <executions>
        <execution>
          <id>pretty-print-aspect-model</id>
          <goals>
            <goal>prettyPrint</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>
```

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

### SAMM CLI import command

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

Translates a JSON Schema file into an Aspect Model and writes it to the specified output directory.

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

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

### Generate PNG Diagram for Aspect Model

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

Generate a PNG diagram for an Aspect Model using a custom resolver.

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

```bash
samm aspect AspectModel.ttl to png --custom-resolver resolver.jar
```