Skip to content

Commit 7940734

Browse files
ArokyaMatthewArokyaMatthew
committed
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
1 parent b9ef3a4 commit 7940734

1 file changed

Lines changed: 186 additions & 47 deletions

File tree

‎README.md‎

Lines changed: 186 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,205 @@
11
# Eclipse BaSyx Python SDK
22

3-
The Eclipse BaSyx Python project focuses on providing a Python implementation of the Asset Administration Shell (AAS)
4-
for Industry 4.0 Systems.
3+
[![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)
4+
[![PyPI Version](https://img.shields.io/pypi/v/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/)
5+
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/basyx-python-sdk)](https://anaconda.org/conda-forge/basyx-python-sdk)
6+
[![PyPI Downloads](https://img.shields.io/pypi/dm/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/)
7+
[![Python Version](https://img.shields.io/pypi/pyversions/basyx-python-sdk)](https://pypi.org/project/basyx-python-sdk/)
8+
[![License](https://img.shields.io/github/license/eclipse-basyx/basyx-python-sdk)](LICENSE)
9+
10+
The Eclipse BaSyx Python SDK is a Python implementation of the
11+
[Asset Administration Shell (AAS)](https://industrialdigitaltwin.org/en/content-hub/aasspecifications)
12+
for Industry 4.0 systems. It lets you model, serialize, validate, store, and serve AAS data
13+
entirely in Python.
14+
15+
The project is part of the [Eclipse BaSyx](https://www.eclipse.org/basyx/) middleware
16+
framework, developed under the umbrella of the Eclipse Foundation.
17+
18+
## Specification Compliance
19+
20+
> [!NOTE]
21+
> The SDK version number is independent of the supported AAS specification versions.
22+
23+
These are the AAS specifications implemented by the
24+
[current release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest),
25+
which can also be found on [PyPI](https://pypi.org/project/basyx-python-sdk/) and
26+
[conda-forge](https://anaconda.org/conda-forge/basyx-python-sdk):
27+
28+
| Specification | Version |
29+
|---|---|
30+
| 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) |
31+
| 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) |
32+
| 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) |
33+
| 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) |
34+
| 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) |
35+
36+
For older specification support, consult the [prior releases](https://github.com/eclipse-basyx/basyx-python-sdk/releases) —
37+
each release has a similar table in its notes.
38+
39+
---
540

6-
**Please note that the SDK version number is independent of the supported AAS versions!**
41+
## Table of Contents
742

8-
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/):
43+
- [Project Overview](#project-overview)
44+
- [Repository Structure](#repository-structure)
45+
- [Tutorials](#tutorials)
46+
- [Documentation](#documentation)
47+
- [FAQ](#faq)
48+
- [Release Schedule](#release-schedule)
49+
- [Contributing](#contributing)
50+
- [License](#license)
951

10-
| Specification | Version |
11-
|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
12-
| 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) |
13-
| 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) |
14-
| 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) |
15-
| 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) |
16-
| 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) |
17-
18-
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).
19-
Each of them has a similar table at the top of the release notes.
20-
21-
## Features
22-
This repository is structured into separate packages.
23-
The `sdk` directory provides the AAS metamodel as Python objects and fundamental functionalities to handle AAS.
24-
The `server` implements a specification-compliant Docker HTTP server for AASs.
25-
The `compliance_tool` is to be determined.
26-
27-
* [SDK](./sdk/README.md):
28-
* Modelling of AASs as Python objects
29-
* Reading and writing of AASX package files
30-
* (De-)serialization of AAS objects into/from JSON and XML
31-
* 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)).
32-
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.
33-
* Storing of AAS objects in CouchDB, Backend infrastructure for easy expansion
34-
* Compliance checking of AAS XML and JSON files
35-
* [Server](./server/README.md): Docker Image of a specification compliant HTTP Server implementing the interfaces:
36-
* Asset Administration Shell Repository
37-
* Submodel Repository
38-
* [Compliance Tool](./compliance_tool/README.md): A command-line tool for checking compliance of JSON and XML files
39-
to the specification of the AAS
52+
---
4053

41-
## License
54+
## Project Overview
4255

43-
The BaSyx Python SDK project is licensed under the terms of the MIT License.
56+
This mono-repository contains three self-contained Python packages that cover different
57+
aspects of working with Asset Administration Shells:
4458

45-
SPDX-License-Identifier: MIT
59+
| Package | Purpose |
60+
|---------|---------|
61+
| **[SDK](./sdk)** | Core library — AAS metamodel, serialization, storage |
62+
| **[Server](./server)** | Spec-compliant AAS HTTP/REST server (Docker) |
63+
| **[Compliance Tool](./compliance_tool)** | CLI checker for AAS file compliance |
64+
65+
### SDK
66+
67+
The SDK (`basyx-python-sdk` on PyPI / conda-forge) is the core of this project. It provides:
68+
69+
- **AAS Metamodel** — full Python object model of the AAS metamodel (Part 1)
70+
- **Serialization** — read and write AAS data as JSON, XML, or AASX package files
71+
- **Backend Storage** — persist AAS objects in CouchDB or as local JSON files, with an
72+
extensible backend interface
73+
- **Experimental RDF Support** — serialization to RDF is available on the
74+
[Experimental/Adapter/RDF](https://github.com/eclipse-basyx/basyx-python-sdk/tree/Experimental/Adapter/RDF/basyx/aas/adapter/rdf)
75+
branch (see [#308](https://github.com/eclipse-basyx/basyx-python-sdk/pull/308) for context)
76+
77+
### Server
78+
79+
A Docker image that exposes a specification-compliant HTTP/REST API (AAS Part 2), currently
80+
implementing the following service interfaces:
81+
82+
- Asset Administration Shell Repository
83+
- Submodel Repository
84+
- AAS Registry
85+
- AAS Discovery
86+
87+
It can serve AAS data from AASX, JSON, or XML files, optionally with persistent
88+
storage via the Local-File Backend.
89+
90+
### Compliance Tool
91+
92+
A command-line utility for checking whether AAS JSON, XML, or AASX files conform to the
93+
official schema. Useful for CI pipelines, data validation, and interoperability testing.
94+
95+
---
96+
97+
## Repository Structure
98+
99+
```
100+
basyx-python-sdk/
101+
├── sdk/ # Core Python SDK (basyx-python-sdk on PyPI)
102+
│ ├── basyx/aas/
103+
│ │ ├── model/ # AAS metamodel as Python classes
104+
│ │ ├── adapter/ # JSON, XML, AASX serialization adapters
105+
│ │ ├── backend/ # CouchDB, local-file storage backends
106+
│ │ ├── util/ # Utility functions (traversal, identification)
107+
│ │ └── examples/ # Tutorials and example data
108+
│ ├── docs/ # Sphinx documentation source
109+
│ └── pyproject.toml
110+
├── server/ # AAS HTTP/REST server (Docker)
111+
│ ├── app/ # Server application code
112+
│ ├── docker/ # Dockerfiles and entrypoint scripts
113+
│ ├── example_configurations/
114+
│ └── pyproject.toml
115+
├── compliance_tool/ # CLI compliance checker
116+
│ ├── aas_compliance_tool/
117+
│ └── pyproject.toml
118+
├── .github/workflows/ # CI/CD pipeline definitions
119+
├── CONTRIBUTING.md
120+
├── LICENSE # MIT License
121+
└── NOTICE
122+
```
123+
124+
---
125+
126+
## Tutorials
127+
128+
The SDK ships with step-by-step tutorials in `sdk/basyx/aas/examples/`:
46129

47-
For more information, especially considering the licenses of included third-party works, please consult the `NOTICE`
48-
file.
130+
| Tutorial | What You Will Learn |
131+
|---|---|
132+
| [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 |
133+
| [Navigate Submodels](./sdk/basyx/aas/examples/tutorial_navigate_aas.py) | Traverse AAS Submodels using IdShorts and IdShortPaths |
134+
| [Object Storage](./sdk/basyx/aas/examples/tutorial_storage.py) | Manage many AAS objects with ObjectStores and resolve references |
135+
| [Serialization & Deserialization](./sdk/basyx/aas/examples/tutorial_serialization_deserialization.py) | Read and write AAS data as JSON and XML |
136+
| [AASX Packages](./sdk/basyx/aas/examples/tutorial_aasx.py) | Export AAS shells with related objects and auxiliary files to AASX packages |
137+
| [CouchDB Backend](./sdk/basyx/aas/examples/tutorial_backend_couchdb.py) | Store and retrieve AAS objects in a CouchDB document database |
138+
139+
---
140+
141+
## Documentation
142+
143+
Full API documentation is hosted on Read the Docs:
144+
145+
**[basyx-python-sdk.readthedocs.io](https://basyx-python-sdk.readthedocs.io)**
146+
147+
---
148+
149+
## FAQ
150+
151+
**I can't read a JSON/XML/AASX file from another tool with this SDK. What should I do?**
152+
153+
The SDK enforces strict compliance with the AAS specification. Files produced by other tools
154+
may not fully conform. To diagnose the issue:
155+
156+
1. Check that the file targets the same AAS specification version supported by this SDK
157+
(see the [Specification Compliance](#specification-compliance) table above).
158+
2. Run the [Compliance Tool](./compliance_tool/README.md) on the file to identify any
159+
schema violations.
160+
3. If the file is spec-compliant and the SDK still rejects it, please
161+
[open an issue](https://github.com/eclipse-basyx/basyx-python-sdk/issues/new) with the
162+
error message and, if possible, a minimal example file.
163+
164+
**Can I run the server without Docker?**
165+
166+
Yes, for debugging purposes. See the
167+
[Server README](./server/README.md#running-without-docker-debugging-only) for instructions.
168+
This mode is not suitable for production.
169+
170+
---
49171

50172
## Release Schedule
51173

52-
The Eclipse BaSyx-Python SDK Team evaluates bi-monthly the newly added commits to the main branch towards the need
53-
of releasing a new version.
54-
If decided the changes warrant a release, it is initiated, using semantic versioning for the new release number.
55-
If the changes do not warrant a release, the decision is postponed to the next meeting.
174+
The Eclipse BaSyx Python SDK team meets bi-monthly to evaluate whether the changes accumulated
175+
on the `develop` branch warrant a new release. If so, `develop` is merged into `main` and a
176+
new version is published to
177+
[PyPI](https://pypi.org/project/basyx-python-sdk/) and
178+
[conda-forge](https://anaconda.org/conda-forge/basyx-python-sdk)
179+
using [semantic versioning](https://semver.org/). If not, the decision is deferred to the
180+
next meeting. Security fixes may be released at any time.
56181

57-
Additionally, security fixes may be released at any point.
182+
---
58183

59184
## Contributing
60185

61-
For contributing with issues and code, please see our [Contribution Guideline](./CONTRIBUTING.md).
186+
We welcome contributions of all kinds — bug reports, feature requests, documentation
187+
improvements, and code. Please read our [Contribution Guideline](./CONTRIBUTING.md) before
188+
getting started.
62189

63190
### Eclipse Contributor Agreement
64191

65-
To contribute code to this project you need to sign the [Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php).
66-
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
192+
To contribute code, you must sign the
193+
[Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php).
194+
Create an Eclipse account with the same email address you use for Git commits, then submit
195+
the form at: https://accounts.eclipse.org/user/eca
196+
197+
---
198+
199+
## License
200+
201+
This project is licensed under the terms of the **MIT License**.
202+
203+
SPDX-License-Identifier: MIT
204+
205+
For details on third-party dependencies and their licenses, see the [NOTICE](./NOTICE) file.

0 commit comments

Comments
 (0)