The Eclipse BaSyx Python SDK is a Python implementation of the Asset Administration Shell (AAS) 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 middleware framework, developed under the umbrella of the Eclipse Foundation.
Note
The SDK version number is independent of the supported AAS specification versions.
These are the AAS specifications implemented by the current release, which can also be found on PyPI and conda-forge:
| Specification | Version |
|---|---|
| Part 1: Metamodel | v3.0.1 (01001-3-0-1) |
| Schemata (JSONSchema, XSD) | v3.0.8 (IDTA-01001-3-0-1_schemasV3.0.8) |
| Part 2: API | v3.0 (01002-3-0) |
| Part 3a: Data Specification IEC 61360 | v3.0 (01003-a-3-0) |
| Part 5: Package File Format (AASX) | v3.0 (01005-3-0) |
For older specification support, consult the prior releases — each release has a similar table in its notes.
This mono-repository contains three self-contained Python packages that cover different aspects of working with Asset Administration Shells:
| Package | Purpose |
|---|---|
| SDK | Core library — AAS metamodel, serialization, storage |
| Server | Spec-compliant AAS HTTP/REST server (Docker) |
| Compliance Tool | CLI checker for AAS file compliance |
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 branch (see #308 for context)
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.
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.
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 (install from PyPI or conda-forge, quick code example, tutorials)
- Server — Running the Server (Docker build & run, environment variables, persistence options)
- Compliance Tool — Using the Compliance Tool (install, command-line usage)
The SDK ships with step-by-step tutorials in sdk/basyx/aas/examples/:
| Tutorial | What You Will Learn |
|---|---|
| Create a Simple AAS | Build an Asset Administration Shell with an Asset and a Submodel from scratch |
| Navigate Submodels | Traverse AAS Submodels using IdShorts and IdShortPaths |
| Object Storage | Manage many AAS objects with ObjectStores and resolve references |
| Serialization & Deserialization | Read and write AAS data as JSON and XML |
| AASX Packages | Export AAS shells with related objects and auxiliary files to AASX packages |
| CouchDB Backend | Store and retrieve AAS objects in a CouchDB document database |
Ready-to-use Docker Compose configurations can be found in server/example_configurations/:
| Configuration | Description |
|---|---|
| Repository Standalone | Standalone AAS and Submodel repository server |
| Registry Standalone | Standalone AAS and Submodel registry service |
| Discovery Standalone | Standalone AAS discovery service |
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:
- Check that the file targets the same AAS specification version supported by this SDK (see the Specification Compliance table above).
- Run the Compliance Tool on the file to identify any schema violations.
- If the file is spec-compliant and the SDK still rejects it, please open an issue 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 for instructions. This mode is not suitable for production.
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 and
conda-forge
using semantic versioning. If not, the decision is deferred to the
next meeting. Security fixes may be released at any time.
We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, and code. Please read our Contribution Guideline before getting started.
To contribute code, you must sign the Eclipse Contributor Agreement (ECA). 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
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 file.