From 3a1405552b84b36a7d45cabb2d31bbb7a8cf156b Mon Sep 17 00:00:00 2001 From: ArokyaMatthew Date: Fri, 1 May 2026 11:10:53 +0530 Subject: [PATCH] README: Modernise top-level README.md The top-level README was sparse compared to other Eclipse BaSyx repositories. This commit rewrites it with structured sections, status badges, specification compliance table (moved to the top), updated server description (Registry and Discovery APIs), tutorials, FAQ, and corrected release schedule reflecting the develop workflow. Changes based on review feedback: - Removed 'Details' column from package overview table - Removed 'Compliance Checking' from SDK features (now a separate package) - Updated server interfaces to include Registry and Discovery APIs - Moved specification compliance to the top of the file - Removed 'Getting Started' section (duplicates sub-package READMEs) - Trimmed FAQ to genuinely asked questions - Updated release schedule to reflect develop-to-main workflow Fixes #475 --- README.md | 221 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 174 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 9894d320..293c9f6e 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,193 @@ # Eclipse BaSyx Python SDK -The Eclipse BaSyx Python project focuses on providing a Python implementation of the Asset Administration Shell (AAS) -for Industry 4.0 Systems. +[![CI](https://github.com/eclipse-basyx/basyx-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/eclipse-basyx/basyx-python-sdk/actions/workflows/ci.yml) +[![PyPI Version](https://img.shields.io/pypi/v/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/) +[![Conda Version](https://img.shields.io/conda/vn/conda-forge/basyx-python-sdk)](https://anaconda.org/conda-forge/basyx-python-sdk) +[![PyPI Downloads](https://img.shields.io/pypi/dm/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/) +[![Python Version](https://img.shields.io/pypi/pyversions/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/) +[![License](https://img.shields.io/github/license/eclipse-basyx/basyx-python-sdk)](LICENSE) + +The Eclipse BaSyx Python SDK is a Python implementation of the +[Asset Administration Shell (AAS)](https://industrialdigitaltwin.org/en/content-hub/aasspecifications) +for Industry 4.0 systems. It lets you model, serialize, validate, store, and serve AAS data +entirely in Python. + +The project is part of the [Eclipse BaSyx](https://www.eclipse.org/basyx/) middleware +framework, developed under the umbrella of the Eclipse Foundation. + +## Specification Compliance + +> [!NOTE] +> The SDK version number is independent of the supported AAS specification versions. + +These are the AAS specifications implemented by the +[current release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest), +which can also be found on [PyPI](https://pypi.org/project/basyx-python-sdk/) and +[conda-forge](https://anaconda.org/conda-forge/basyx-python-sdk): + +| Specification | Version | +|---|---| +| Part 1: Metamodel | [v3.0.1 (01001-3-0-1)](https://industrialdigitaltwin.org/wp-content/uploads/2024/06/IDTA-01001-3-0-1_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf) | +| Schemata (JSONSchema, XSD) | [v3.0.8 (IDTA-01001-3-0-1_schemasV3.0.8)](https://github.com/admin-shell-io/aas-specs/releases/tag/IDTA-01001-3-0-1_schemasV3.0.8) | +| Part 2: API | [v3.0 (01002-3-0)](https://industrialdigitaltwin.org/en/wp-content/uploads/sites/2/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf) | +| Part 3a: Data Specification IEC 61360 | [v3.0 (01003-a-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01003-a-3-0_SpecificationAssetAdministrationShell_Part3a_DataSpecification_IEC61360.pdf) | +| Part 5: Package File Format (AASX) | [v3.0 (01005-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01005-3-0_SpecificationAssetAdministrationShell_Part5_AASXPackageFileFormat.pdf) | -**Please note that the SDK version number is independent of the supported AAS versions!** +For older specification support, consult the [prior releases](https://github.com/eclipse-basyx/basyx-python-sdk/releases) — +each release has a similar table in its notes. -These are the implemented AAS specifications of the [current SDK release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest), which can be also found on [PyPI](https://pypi.org/project/basyx-python-sdk/): +--- -| Specification | Version | -|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Part 1: Metamodel | [v3.0.1 (01001-3-0-1)](https://industrialdigitaltwin.org/wp-content/uploads/2024/06/IDTA-01001-3-0-1_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf) | -| Schemata (JSONSchema, XSD) | [v3.0.8 (IDTA-01001-3-0-1_schemasV3.0.8)](https://github.com/admin-shell-io/aas-specs/releases/tag/IDTA-01001-3-0-1_schemasV3.0.8) | -| Part 2: API | [v3.0 (01002-3-0)](https://industrialdigitaltwin.org/en/wp-content/uploads/sites/2/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf) | -| Part 3a: Data Specification IEC 61360 | [v3.0 (01003-a-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01003-a-3-0_SpecificationAssetAdministrationShell_Part3a_DataSpecification_IEC61360.pdf) | -| Part 5: Package File Format (AASX) | [v3.0 (01005-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01005-3-0_SpecificationAssetAdministrationShell_Part5_AASXPackageFileFormat.pdf) | - -If you need support to an older version of the specifications, please refer to our [prior releases](https://github.com/eclipse-basyx/basyx-python-sdk/releases). -Each of them has a similar table at the top of the release notes. - -## Features -This repository is structured into separate packages. -The `sdk` directory provides the AAS metamodel as Python objects and fundamental functionalities to handle AAS. -The `server` implements a specification-compliant Docker HTTP server for AASs. -The `compliance_tool` is to be determined. - -* [SDK](./sdk/README.md): - * Modelling of AASs as Python objects - * Reading and writing of AASX package files - * (De-)serialization of AAS objects into/from JSON and XML - * Experimental serialization to RDF (see branch [Experimental/Adapter/RDF](https://github.com/eclipse-basyx/basyx-python-sdk/tree/Experimental/Adapter/RDF/basyx/aas/adapter/rdf)). - Please refer to discussion of PR [#308](https://github.com/eclipse-basyx/basyx-python-sdk/pull/308) for the reasoning behind keeping this feature experimental. - * Storing of AAS objects in CouchDB, Backend infrastructure for easy expansion - * Compliance checking of AAS XML and JSON files -* [Server](./server/README.md): Docker Image of a specification compliant HTTP Server implementing the interfaces: - * Asset Administration Shell Repository - * Submodel Repository -* [Compliance Tool](./compliance_tool/README.md): A command-line tool for checking compliance of JSON and XML files - to the specification of the AAS +## Table of Contents -## License +- [Project Overview](#project-overview) +- [Getting Started](#getting-started) +- [Examples and Tutorials](#examples-and-tutorials) +- [FAQ](#faq) +- [Release Schedule](#release-schedule) +- [Contributing](#contributing) +- [License](#license) -The BaSyx Python SDK project is licensed under the terms of the MIT License. +--- -SPDX-License-Identifier: MIT +## Project Overview + +This mono-repository contains three self-contained Python packages that cover different +aspects of working with Asset Administration Shells: + +| Package | Purpose | +|---------|---------| +| **[SDK](./sdk)** | Core library — AAS metamodel, serialization, storage | +| **[Server](./server)** | Spec-compliant AAS HTTP/REST server (Docker) | +| **[Compliance Tool](./compliance_tool)** | CLI checker for AAS file compliance | + +### SDK + +The SDK (`basyx-python-sdk` on PyPI / conda-forge) is the core of this project. It provides: + +- **AAS Metamodel** — full Python object model of the AAS metamodel (Part 1) +- **Serialization** — read and write AAS data as JSON, XML, or AASX package files +- **Backend Storage** — persist AAS objects in CouchDB or as local JSON files, with an + extensible backend interface +- **Experimental RDF Support** — serialization to RDF is available on the + [Experimental/Adapter/RDF](https://github.com/eclipse-basyx/basyx-python-sdk/tree/Experimental/Adapter/RDF/basyx/aas/adapter/rdf) + branch (see [#308](https://github.com/eclipse-basyx/basyx-python-sdk/pull/308) for context) + +### Server + +A Docker image that exposes a specification-compliant HTTP/REST API (AAS Part 2), currently +implementing the following service interfaces: + +- Asset Administration Shell Repository +- Submodel Repository +- AAS Registry +- AAS Discovery + +It can serve AAS data from AASX, JSON, or XML files, optionally with persistent +storage via the Local-File Backend. + +### Compliance Tool + +A command-line utility for checking whether AAS JSON, XML, or AASX files conform to the +official schema. Useful for CI pipelines, data validation, and interoperability testing. + +--- + +## Getting Started + +Each package in this repository can be set up independently. Refer to the package-level +READMEs for detailed installation instructions, usage examples, and configuration options: + +- **SDK** — [Getting Started with the SDK](./sdk/README.md#getting-started) (install from + PyPI or conda-forge, quick code example, tutorials) +- **Server** — [Running the Server](./server/README.md#running) (Docker build & run, + environment variables, persistence options) +- **Compliance Tool** — [Using the Compliance Tool](./compliance_tool/README.md) + (install, command-line usage) + +--- + +## Examples and Tutorials -For more information, especially considering the licenses of included third-party works, please consult the `NOTICE` -file. +### SDK Tutorials + +The SDK ships with step-by-step tutorials in `sdk/basyx/aas/examples/`: + +| Tutorial | What You Will Learn | +|---|---| +| [Create a Simple AAS](./sdk/basyx/aas/examples/tutorial_create_simple_aas.py) | Build an Asset Administration Shell with an Asset and a Submodel from scratch | +| [Navigate Submodels](./sdk/basyx/aas/examples/tutorial_navigate_aas.py) | Traverse AAS Submodels using IdShorts and IdShortPaths | +| [Object Storage](./sdk/basyx/aas/examples/tutorial_storage.py) | Manage many AAS objects with ObjectStores and resolve references | +| [Serialization & Deserialization](./sdk/basyx/aas/examples/tutorial_serialization_deserialization.py) | Read and write AAS data as JSON and XML | +| [AASX Packages](./sdk/basyx/aas/examples/tutorial_aasx.py) | Export AAS shells with related objects and auxiliary files to AASX packages | +| [CouchDB Backend](./sdk/basyx/aas/examples/tutorial_backend_couchdb.py) | Store and retrieve AAS objects in a CouchDB document database | + +### Server Example Configurations + +Ready-to-use Docker Compose configurations can be found in `server/example_configurations/`: + +| Configuration | Description | +|---|---| +| [Repository Standalone](./server/example_configurations/repository_standalone) | Standalone AAS and Submodel repository server | +| [Registry Standalone](./server/example_configurations/registry_standalone) | Standalone AAS and Submodel registry service | +| [Discovery Standalone](./server/example_configurations/discovery_standalone) | Standalone AAS discovery service | + +--- + +## FAQ + +**I can't read a JSON/XML/AASX file from another tool with this SDK. What should I do?** + +The SDK enforces strict compliance with the AAS specification. Files produced by other tools +may not fully conform. To diagnose the issue: + +1. Check that the file targets the same AAS specification version supported by this SDK + (see the [Specification Compliance](#specification-compliance) table above). +2. Run the [Compliance Tool](./compliance_tool/README.md) on the file to identify any + schema violations. +3. If the file is spec-compliant and the SDK still rejects it, please + [open an issue](https://github.com/eclipse-basyx/basyx-python-sdk/issues/new) with the + error message and, if possible, a minimal example file. + +**Can I run the server without Docker?** + +Yes, for debugging purposes. See the +[Server README](./server/README.md#running-without-docker-debugging-only) for instructions. +This mode is not suitable for production. + +--- ## Release Schedule -The Eclipse BaSyx-Python SDK Team evaluates bi-monthly the newly added commits to the main branch towards the need -of releasing a new version. -If decided the changes warrant a release, it is initiated, using semantic versioning for the new release number. -If the changes do not warrant a release, the decision is postponed to the next meeting. +The Eclipse BaSyx Python SDK team meets bi-monthly to evaluate whether the changes accumulated +on the `develop` branch warrant a new release. If so, `develop` is merged into `main` and a +new version is published to +[PyPI](https://pypi.org/project/basyx-python-sdk/) and +[conda-forge](https://anaconda.org/conda-forge/basyx-python-sdk) +using [semantic versioning](https://semver.org/). If not, the decision is deferred to the +next meeting. Security fixes may be released at any time. -Additionally, security fixes may be released at any point. +--- ## Contributing -For contributing with issues and code, please see our [Contribution Guideline](./CONTRIBUTING.md). +We welcome contributions of all kinds — bug reports, feature requests, documentation +improvements, and code. Please read our [Contribution Guideline](./CONTRIBUTING.md) before +getting started. ### Eclipse Contributor Agreement -To contribute code to this project you need to sign the [Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php). -This is done by creating an Eclipse account for your git e-mail address and then submitting the following form: https://accounts.eclipse.org/user/eca +To contribute code, you must sign the +[Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php). +Create an Eclipse account with the same email address you use for Git commits, then submit +the form at: https://accounts.eclipse.org/user/eca + +--- + +## License + +This project is licensed under the terms of the **MIT License**. + +SPDX-License-Identifier: MIT + +For details on third-party dependencies and their licenses, see the [NOTICE](./NOTICE) file.