{"id":40147776,"url":"https://github.com/eclipse-esmf/esmf-sdk","last_synced_at":"2026-02-13T13:21:13.383Z","repository":{"id":37396117,"uuid":"344533579","full_name":"eclipse-esmf/esmf-sdk","owner":"eclipse-esmf","description":"Load Aspect Models and their artifacts as Java code; share components to realize SAMM as code","archived":false,"fork":false,"pushed_at":"2026-01-13T14:07:51.000Z","size":9784,"stargazers_count":30,"open_issues_count":79,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-14T03:10:25.005Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://eclipse-esmf.github.io/esmf-developer-guide/index.html","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eclipse-esmf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-03-04T16:11:36.000Z","updated_at":"2026-01-13T14:07:55.000Z","dependencies_parsed_at":"2023-10-11T15:13:52.819Z","dependency_job_id":"90f3ac36-ac7c-49c4-acf0-8e2307609dba","html_url":"https://github.com/eclipse-esmf/esmf-sdk","commit_stats":null,"previous_names":["openmanufacturingplatform/sds-sdk"],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/eclipse-esmf/esmf-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-esmf%2Fesmf-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-esmf%2Fesmf-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-esmf%2Fesmf-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-esmf%2Fesmf-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eclipse-esmf","download_url":"https://codeload.github.com/eclipse-esmf/esmf-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eclipse-esmf%2Fesmf-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28572578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T14:39:55.009Z","status":"ssl_error","status_checked_at":"2026-01-19T14:39:01.217Z","response_time":67,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-19T15:02:08.328Z","updated_at":"2026-02-13T13:21:13.364Z","avatar_url":"https://github.com/eclipse-esmf.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESMF SDK\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Getting help](#getting-help)\n- [Build and contribute](#build-and-contribute)\n- [SDK Structure](#sdk-structure)\n- [Java Core Components](#java-core-components)\n    - [esmf-aspect-meta-model](#esmf-aspect-meta-model)\n    - [esmf-aspect-static-meta-model](#esmf-aspect-static-meta-model)\n    - [esmf-aspect-model-validator](#esmf-aspect-model-validator)\n- [Version Handling](#version-handling)\n    - [esmf-sdk Versioning](#esmf-sdk-versioning)\n    - [SAMM Java Implementation Packaging](#samm-java-implementation-packaging)\n- [SAMM CLI](#samm-cli)\n- [Artifact Generation facilities](#artifact-generation-facilities)\n    - [POJO Generator](#pojo-generator)\n    - [Static Meta Model Generator](#static-meta-model-generator)\n    - [Aspect Model Diagram Generator](#aspect-model-diagram-generator)\n    - [Aspect Model Documentation Generator](#aspect-model-documentation-generator)\n- [License](#license)\n\n## Introduction\n\nThe ESMF SDK contains artifacts and resources for all parties that intent to use, extend or\nintegrate with the Semantic Aspect Meta Model (SAMM), e.g., solution developers, domain experts or\nOEMs.\n\nAt its core are components which help to work with the Semantic Aspect Meta Model. The SDK comprises\ncomponents to load and validate models generate artifacts such as static classes, documentation,\nDTOs (data transfer objects) and so on.\n\nTo fully leverage SAMM, provided components include language-specific meta model implementations,\ncode generators, validators etc.\n\nThis document provides an overall overview of the SDK, and the concepts applied throughout it.\nDetailed documentation and concepts for each component can be found in the respective subfolders.\n\nThis repository contains a detailed developer documentation written in AsciiDoc.\nThe source files (AsciiDoc) are located [here](documentation/developer-guide) and are built using\n[Antora](https://antora.org/) which generates the documentation as HTML files. A site generated using Antora is self-contained and can be viewed entirely offline via a web browser without setting up a web server.\nTo build the documentation locally, please check out and follow the instructions in [ESMF documentation repository](https://github.com/eclipse-esmf/eclipse-esmf.github.io).\n\n## Getting help\n\nAre you having trouble with ESMF SDK? We want to help!\n\n* Check the [ESMF SDK developer documentation](https://eclipse-esmf.github.io/esmf-developer-guide/index.html)\n* Ask a question in the [ESMF Chat ](https://chat.eclipse.org/#/room/#eclipse-semantic-modeling-framework:matrix.eclipse.org).\n* Check the SAMM [specification](https://eclipse-esmf.github.io/samm-specification/snapshot/index.html)\n* Having issues with the ESMF SDK? Open a [GitHub issue](https://github.com/eclipse-esmf/esmf-sdk/issues).\n\n## Build and contribute\n\nThe top level elements of the SDK structure are all carried out as Maven multimodule projects.\nBuilding the SDK requires Java 25.\n\nTo build the SDK core components, run the following command:\n```bash\nmvn -pl '!org.eclipse.esmf:samm-cli' clean install\n```\n\nTo also build SDK core components and the CLI tool, run the above command, followed by:\n```bash\nmvn -pl org.eclipse.esmf:samm-cli clean verify\n```\n\nWe are always looking forward to your contributions. For more details on how to contribute just take\na look at the [contribution guidelines](CONTRIBUTING.md). Please create an issue first before\nopening a pull request.\n\nTo quickly check if your contribution adheres to the project conventions, you can run `mvn\nspotless:check` and `mvn checkstyle:check`; to automatically apply the project code style to your\nchanges, you can also use `mvn spotless:apply`. For more details, please see our\n[conventions](CONVENTIONS.md.)\n\n## SDK Structure\n\nTo ease navigation through the SDK and its components, the repository employs the following structure:\n\n```\nesmf-sdk\n │\n ├─── core                                      # e.g. meta model implementations etc.\n │     ├─── esmf-aspect-meta-model-interface\n │     ├─── esmf-aspect-meta-model-java\n │     ├─── ...\n ├─── tools                                     # accompanying tools, build system integrations etc.\n │     ├─── samm-cli\n │     └─── ...\n └─── documentation                             # the Antora documentation module for the SDK\n```\n\n## Java Core Components\n\nThe Java core components are those to be consumed by developers that aim to build applications or\ntools dealing with SAMM.\n\n### `esmf-aspect-meta-model`\n\nContains the Java implementation of the SAMM.\n\nAn Aspect Model can be used in (primarily) two ways:\n\n* Dynamically instantiated - this is done by tooling and applications that don't have any a-priori\n  knowledge except for the Aspect Model file/URN and also don't or can't use generated source code\n  artifacts. Any form of Java source code generator will use the meta model this way.\n* Statically generated - the preferred way for applications that are built against known Aspect\n  Models. A static meta model provides full information about Java types, including types\n  (`Entity`s, `Enumeration`s etc.) derived from the Aspect Model itself. Implementation parts\n  specific to the static variant are located in their own component `esmf-aspect-static-meta-model`.\n\n### `esmf-aspect-static-meta-model`\n\nContains the parts of the Java implementation of the SAMM that are specific to the static variant,\ne.g. common base classes of static meta model elements. Consumers of a static meta model can use\nthis component as their main entrance dependency.\n\n### `esmf-aspect-model-validator`\n\nCan be used to validate an Aspect Model against the SAMM definition. This component is mainly of\ninterest for tool developers or as a utility during a modeling phase.\n\nThe model validator is also available through the [SAMM CLI](#samm-cli).\n\n## Version Handling\n\nSAMM and its SDKs evolve over time. While measures are taken to do this in a non-breaking manner,\nsome changes cannot be carried out without the need to define a new, breaking version. Due to this\nfact it is important to understand the versioning concept that is applied to the SAMM, APIs and SDK\ncomponents that are derived from them.\n\nIn case of a prerelease a postfix will be added to the version, such as `-M1`, and it will be\nreleased on Github. The way to access the artifact is described in the [Java Aspect Tooling\nGuide](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/java-aspect-tooling.html#versioning).\n\n### esmf-sdk Versioning\n\nFor the esmf-sdk, semantic versioning (`major.minor.micro`) is applied with the following rules:\n\n* The `major` part designates the supported SAMM major version\n* A breaking change increases the `minor` part\n* Backwards compatible new features, changes to existing features or bugfixes increase the `minor` part\n\nA new SAMM version implies new releases of the SDK components that depend on this SAMM version,\nhowever not the other way round. New releases of SDK components may be released that are built on an\nexisting SAMM version.\n\n### SAMM Java Implementation Packaging\n\nComplex applications might have the need to be implemented against different versions of the SAMM,\nespecially if Aspects should be integrated where there is no control over the underlying meta model\nversion. Thus, Java artifacts for different SAMM versions exist.\n\nVersion information encoded into the package name and/or class name solve any issues concerning\nunique addressability of a class in a concrete version, however any version update forces consumers\nto change the code base if they want to stay on the latest version.\n\nAs this is not very convenient, the following concept is applied:\n\nThe base package for all meta model elements does not carry any version encoding, neither do any\nclasses that represent the latest version of the SAMM. This has the advantage that consumers who\nwant to stay on the latest version and don't need multiple versions of the meta model can simply\nupgrade and don't need to apply any changes to their code base (that is, if the newer version did\nnot introduce any breaking changes).\n\n## Artifact Generation Facilities\n\nOne primary use case of a meta model is to use it as a basis for generated artifacts. Most prominent\nexample is generating domain model classes, however usage is of course by no means restricted to\nthis.\n\nThe ESMF SDK already comes with a set of useful generators. They all accept any Aspect Model given\nas a Turtle (`.ttl`) file. All generators are also available through the [SAMM CLI](#samm-cli).\n\n### POJO Generator\n\nThe POJO generator takes any Aspect Model and generates all Java classes that are necessary to\nrepresent the Aspect. This includes at least a class for the Aspect itself, in most cases however\nmultiple files are generated, e.g. for embedded `Entity`s or `Enumeration`s.\n\n### Static Meta Model Generator\n\nEspecially when the Aspect Models that are worked with are known a priori (which should be the case\nfor most solutions built on the ESMF SDK) using the dynamically instantiated meta model does not\ngive developers the full potential of what's possible. For those use cases a generator can be used\nto generate Java source code representing the meta model in a static form, with meta classes that\nallow direct access to all important information of one or more Aspect Models, notably properties\nand their types.\n\nThe static meta model uses the Java implementation from `esmf-aspect-meta-model` adding further\ndetails that are specific to the static case through the component `esmf-aspect-static-meta-model`.\n\n### Aspect Model Diagram Generator\n\nThe diagram generator takes any Aspect Model and provides a rendering of a diagram representing the\nAspect Model with all its elements.\n\nPossible output formats are `png` and `svg`.\n\n### Aspect Model Documentation Generator\n\nThe documentation generator takes any Aspect Model and provides an HTML document describing the\nAspect Model.\n\nThe resulting document can be seen as a reference documentation as it includes any information that\ncan be derived from the Aspect Model such as the diagram and a list of all properties with\ninformation about their characteristics, data type etc.\n\n### Model migration\n\nAll migrators are in the module `esmf-aspect-meta-model-version-migrator` to execute a model\nmigration. If the internal SDK migrations are not sufficient, it is possible to add custom\nmigrator(s). For this the interface `MigratorFactory` has to be implemented and added to the\nclasspath. The AspectResolver collects this automatically and executes the custom migrator depending\non availability. Important: The implementation of the `MigratorFactory` have to be the package name\nor a subpackage of `org.eclipse.esmf.aspectmodel.versionupdate`\n\n## SAMM CLI\n\nThe [SAMM CLI](tools/samm-cli) provides all generation as well as validation functionality as a CLI\nfor ad-hoc usage outside an IDE, automated build or any project at all. Provided functions are:\n\n* Model validation\n* Model documentation generation\n* Model diagram generation (multiple output formats)\n* Sample JSON payload generation\n* Java class generation\n* Static meta model generation\n\nNew SDK functionality based on the Aspect Meta Model will always be also provided through the SAMM\nCLI. Built binary versions of the SAMM CLI are available as part of the [ESMF SDK releases on\nGitHub](https://github.com/eclipse-esmf/esmf-sdk/releases).\n\n### Running\n\nFor information regarding running the command line tool, the available commands and their\ndescription, please have a look at the\n[documentation](https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/samm-cli.html).\n\n## License\n\nSPDX-License-Identifier: MPL-2.0\n\nThis program and the accompanying materials are made available under the terms of the\n[Mozilla Public License, v. 2.0](LICENSE).\n\nThe [Notice file](NOTICE.md) details contained third party materials.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-esmf%2Fesmf-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feclipse-esmf%2Fesmf-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feclipse-esmf%2Fesmf-sdk/lists"}