AAS Editor

AAS Editor#

As a BaSyx AAS Web UI user
I want to create and edit Asset Administration Shells, Submodels, and SubmodelElements
so that I can build and maintain my digital twin infrastructure.

Feature Overview#

The AAS Editor provides comprehensive editing capabilities for creating, modifying, and managing Asset Administration Shells (AAS), Submodels, and SubmodelElements directly within the Web UI. It offers form-based editing with validation, import/export functionality, and support for a wide range of SubmodelElement types.

The editor is designed to be user-friendly while ensuring data integrity through validation against the AAS metamodel specification. All changes are made through intuitive forms, with helpful hints and real-time validation to prevent invalid data entry.

See also

For technical details on the AAS metamodel and its requirements, refer to the AAS Metamodel Specification.

Accessing the Editor#

The BaSyx AAS Web UI provides two editor pages accessible from the main menu:

  • AAS Editor: For working with Asset Administration Shells in an AAS-centric view

  • SM Editor (Submodel Editor): For working directly with Submodels in a submodel-centric view

Accessing the AAS Editor

AAS Editor menu entry in the main navigation#

Note

The editor functionality can be disabled by setting the environment variable ALLOW_EDITING=false. This is useful for read-only deployments or when editing should be restricted.

See also

For information on configuring environment variables, see the Docker Configuration page.

Creating Asset Administration Shells#

To create a new Asset Administration Shell:

  1. Navigate to the AAS Editor page from the main menu

  2. In the AAS List sidebar, click the three-dot menu icon in the header

  3. Select Create AAS from the context menu

  4. Fill in the required fields in the creation form:

    • ID: Automatically prefilled with a generated ID (can be modified)

    • idShort: The short identifier for the AAS

    • Asset Information: Details about the physical or logical asset

    • Administrative Information (optional): Version, revision, creator details

Create AAS Form

Form for creating a new Asset Administration Shell#

  1. Click Save to create the AAS

Hint

Look for the question mark (?) buttons next to input fields for helpful hints about what each field represents and how to fill it correctly.

Editing Existing AAS#

To edit an existing Asset Administration Shell:

  1. In the AAS List, locate the AAS you want to edit

  2. Click the three-dot menu icon next to the AAS

  3. Select Edit AAS from the context menu

  4. Modify the fields as needed in the edit form

  5. Click Save to apply your changes, or Cancel to discard them

Edit AAS Context Menu

Context menu for editing an existing AAS#

Creating and Managing Submodels#

Adding a New Submodel to an AAS#

To add a Submodel to an existing AAS:

  1. Select the AAS from the AAS List

  2. In the AAS Treeview header, click the three-dot menu icon

  3. Select Add Submodel from the context menu

  4. Fill in the required fields:

    • ID: Automatically generated (can be customized)

    • idShort: Short identifier for the Submodel

    • semanticId: The semantic identifier defining the Submodel’s meaning and structure

    • Description (optional): Human-readable description of the Submodel

Add Submodel Form

Form for adding a new Submodel to an AAS#

  1. Click Save to add the Submodel to the AAS

Editing a Submodel#

To edit an existing Submodel:

  1. In the AAS Treeview, locate the Submodel you want to edit

  2. Click the three-dot menu icon next to the Submodel name

  3. Select Edit Submodel from the context menu

  4. Modify the fields in the edit form

  5. Click Save to apply changes

Deleting a Submodel#

To delete a Submodel:

  1. In the AAS Treeview, click the three-dot menu icon next to the Submodel

  2. Select Delete Submodel from the context menu

  3. Confirm the deletion in the dialog that appears

Warning

Deleting a Submodel will also delete all SubmodelElements contained within it. This action cannot be undone.

Adding and Editing SubmodelElements#

The AAS Editor supports creating and editing the following SubmodelElement types:

  • Property

  • MultiLanguageProperty

  • Range

  • File

  • Blob

  • SubmodelElementCollection

  • SubmodelElementList

Adding a SubmodelElement#

To add a SubmodelElement to a Submodel or SubmodelElementCollection/List:

  1. In the AAS Treeview, locate the parent element (Submodel, Collection, or List)

  2. Click the three-dot menu icon next to the parent element

  3. Select Add SubmodelElement from the context menu

  4. Choose the type of SubmodelElement you want to create from the list

  5. Fill in the required fields based on the element type (see details below)

  6. Click Save to add the element

Add SubmodelElement Menu

Context menu for adding SubmodelElements#

Property#

Properties are used to store single values of a specific data type.

Required Fields:

  • idShort: Short identifier

  • valueType: Select from available AAS-supported value types (string, int, boolean, etc.)

Optional Fields:

  • value: The actual value of the property

  • semanticId: Semantic identifier

  • displayName: Localized display names

  • description: Localized human-readable description

Property Edit Form

Form for editing a Property SubmodelElement#

Hint

The UI automatically validates that the entered value matches the selected valueType. For example, if you select “int” as the valueType, you cannot enter letters in the value field.

MultiLanguageProperty#

MultiLanguageProperties store text values in multiple languages.

Required Fields:

  • idShort: Short identifier

Optional Fields:

  • value: Language-tagged text entries (can add as many languages as needed)

  • semanticId: Semantic identifier

  • displayName: Localized display names

  • description: Localized human-readable description

Adding Language Entries:

  1. In the value section, click Add

  2. Select or enter the language code (e.g., “en”, “de”, “fr”)

  3. Enter the text for that language

  4. Repeat to add more languages

MultiLanguageProperty Form

Form for editing a MultiLanguageProperty with multiple languages#

Range#

Range SubmodelElements define a value range with minimum and maximum values.

Required Fields:

  • idShort: Short identifier

  • valueType: Data type for the range values

Optional Fields:

  • min: Minimum value

  • max: Maximum value

  • semanticId: Semantic identifier

  • displayName: Localized display names

  • description: Localized human-readable description

Range Form

Form for editing a Range SubmodelElement#

File#

File SubmodelElements reference external files.

Required Fields:

  • idShort: Short identifier

Optional Fields:

  • contentType: MIME type of the file (e.g., “application/pdf”, “image/png”)

  • value: File path or URL

  • semanticId: Semantic identifier

  • displayName: Localized display names

  • description: Localized human-readable description

Uploading Files: Users can upload files directly through the form. The file will be stored and the path will be automatically set.

File Upload Form

Form for uploading and editing a File SubmodelElement#

Note

Not all file types have dedicated preview capabilities. Some files may only show their path in the Element Details view.

Blob#

Blob SubmodelElements store binary data directly within the AAS.

Required Fields:

  • idShort: Short identifier

Optional Fields:

  • contentType: MIME type of the blob content

  • value: Base64-encoded binary data (or upload a file)

  • semanticId: Semantic identifier

  • displayName: Localized display names

  • description: Localized human-readable description

Uploading Blob Content: Users can upload files directly, which will be automatically encoded and stored as blob data.

Blob Upload Form

Form for uploading and editing a Blob SubmodelElement#

SubmodelElementCollection#

SubmodelElementCollections group related SubmodelElements together.

Required Fields:

  • idShort: Short identifier

Optional Fields:

  • semanticId: Semantic identifier

  • displayName: Localized display names

  • description: Localized human-readable description

Adding Elements to a Collection: After creating the collection, you can add child SubmodelElements by:

  1. Clicking the three-dot menu icon next to the collection in the treeview

  2. Selecting Add SubmodelElement

  3. Creating the child element as described above

SubmodelElementCollection Form

Form for editing a SubmodelElementCollection#

SubmodelElementList#

SubmodelElementLists are ordered collections of SubmodelElements of the same type.

Required Fields:

  • idShort: Short identifier

  • typeValueListElement: The type of SubmodelElements that can be added to this list

Optional Fields:

  • orderRelevant: Boolean indicating if the order of elements matters

  • semanticId: Semantic identifier

  • displayName: Localized display names

  • description: Localized human-readable description

Adding Elements to a List: Similar to collections, use the context menu on the list element to add child SubmodelElements. All child elements must be of the type specified in typeValueListElement. Children of SubmodelElementLists are not required to have an idShort.

SubmodelElementList Form

Form for editing a SubmodelElementList#

Editing SubmodelElements#

To edit any existing SubmodelElement:

  1. In the AAS Treeview, locate the SubmodelElement

  2. Click the three-dot menu icon next to the element

  3. Select Edit [ElementType] (e.g., “Edit Property”, “Edit File”)

  4. Modify the fields in the form

  5. Click Save to apply changes

Deleting SubmodelElements#

To delete a SubmodelElement:

  1. Click the three-dot menu icon next to the element in the treeview

  2. Select Delete [ElementType]

  3. Confirm the deletion

Importing and Exporting#

Importing AAS Environments#

The AAS Editor supports importing complete AAS environments from files:

Supported Formats:

  • AASX (AAS Package)

  • JSON (AAS Environment)

  • XML (AAS Environment)

Import Process:

  1. Navigate to the AAS Editor page

  2. Click the Import button in the toolbar

  3. Select the file to import (can contain multiple AAS)

  4. The imported AAS will be added to your infrastructure

Context menu for importing AAS

Context menu for importing AAS environments#

Import AAS Dialog

Dialog for importing AAS environments from files#

Importing Submodel Templates#

You can import Submodel templates as JSON:

  1. Navigate to the Submodel where you want to add elements

  2. Click the Import from JSON option in the context menu

  3. Paste or upload the JSON containing the Submodel template

  4. The template structure will be added to your Submodel

Exporting AAS#

To export an Asset Administration Shell:

  1. In the AAS List, click the download icon next to the AAS you want to export

  2. Select the Submodel(s) to include in the export

  3. The file will be downloaded to your device

Export AAS

Exporting an AAS as an AASX file#

Copy and Paste Functionality#

The editor provides clipboard functionality for Submodels and SubmodelElements:

Copy to Clipboard:

  1. Right-click on a Submodel or SubmodelElement in the treeview

  2. Select Copy [Element] as JSON to copy to the system clipboard, or

  3. Select Copy [Element] to copy to the application’s internal clipboard

Paste from Clipboard:

  1. Navigate to where you want to paste the element

  2. Right-click and select Paste from JSON (for system clipboard) or Paste [Element] (for internal clipboard)

  3. The element will be inserted at the selected location

Hint

Using the internal clipboard allows you to easily duplicate elements within the same AAS or copy them to different AAS without leaving the Web UI.

Validation and Error Handling#

The AAS Editor includes comprehensive validation to ensure data integrity:

Real-Time Validation#

  • Required Fields: Input fields for required attributes show an error state if left empty

  • Data Types: Value inputs are validated against their specified valueType (e.g., you cannot enter text in an integer field)

  • Save Button: The Save button is disabled when the form contains validation errors

Error States#

When validation fails, the affected input field:

  • Displays a red border or error indicator

  • Shows a descriptive error message below the field

  • Prevents saving until the error is resolved

Validation Error

Example of a validation error in the edit form#

Helpful Hints#

Throughout the editor forms, you’ll find question mark (?) buttons that provide:

  • Descriptions of what each field represents

  • Examples of valid values

  • Links to relevant sections of the AAS specification

Best Practices and Tips#

Starting with an Empty Setup#

When building an AAS infrastructure from scratch, follow this order:

  1. Create the AAS first with basic information

  2. Add Submodels to the AAS with appropriate semanticIds

  3. Add SubmodelElements to each Submodel to populate the structure

  4. Test and validate by viewing the AAS in the standard viewer

Working with Registries and Repositories#

Important

When using separate registries and repositories in your AAS infrastructure, they must be kept in sync to avoid unexpected behavior.

BaSyx handles this automatically through the automatic registry integration feature. If you’re using a different infrastructure, ensure that:

  • Creating an AAS in the repository also registers it in the registry

  • Deleting an AAS removes it from both repository and registry

  • Updates to AAS metadata are reflected in the registry

File Handling#

  • Not all file types have dedicated preview capabilities in the Element Details view

  • For files without preview support, only the file path is displayed

  • Always specify the correct contentType (MIME type) for files and blobs

  • Consider file size when using Blobs versus Files (Blobs store data directly in the AAS)

Semantic IDs#

  • Use standardized semantic IDs from IDTA Submodel Templates when possible

  • Consistent use of semantic IDs enables automatic plugin-based visualizations

  • Document custom semantic IDs if you create domain-specific Submodels

Known Limitations#

The current version of the AAS Editor has the following limitations:

Unsupported SubmodelElement Types#

The following SubmodelElement types are not yet supported in the editor:

  • ReferenceElement

  • AnnotatedRelationshipElement

  • RelationshipElement

  • Entity

  • Capability

  • BasicEventElement

Note

While these elements cannot be created or edited through the Web UI, they can still be viewed if present in imported AAS.

Unsupported Attributes#

Some AAS attributes are not yet supported in the editor, including:

  • SupplementalSemanticIds

  • Some advanced metadata attributes

Feature Requests#

If you need support for specific SubmodelElement types or attributes, please:

  • Check the BaSyx GitHub repository for existing feature requests

  • Open a new issue to request the feature

  • Consider contributing to the project if you have development experience

Permissions and Access Control#

Editor access can be controlled in several ways:

Environment Variable Control#

The editor pages can be completely disabled by setting:

ALLOW_EDITING=false

This is useful for:

  • Read-only production deployments

  • Demo or presentation environments

  • Restricting editing to specific deployments

Backend-Level Permissions#

When RBAC (Role-Based Access Control) or ABAC (Attribute-Based Access Control) is configured on the backend:

  • The Web UI respects backend permissions

  • Users without edit permissions will see errors when attempting to save changes

  • Some operations may be restricted based on user roles

See also

For information on configuring access control, see the Security feature page.

Troubleshooting#

Cannot Save Changes#

If you cannot save your changes:

  1. Check all input fields for red error indicators

  2. Ensure all required fields are filled in

  3. Verify that value types match the entered data

  4. Check the browser console for any error messages

Changes Not Appearing After Save#

If changes don’t appear after saving:

  1. Verify that you’re connected to the correct infrastructure

  2. Check if registries and repositories are in sync

  3. Try refreshing the page to reload data from the backend

  4. Check for error notifications in the Web UI

Import Fails#

If importing an AAS environment fails:

  1. Verify the file format is supported (AASX, JSON, or XML)

  2. Ensure the file contains valid AAS data according to the V3 metamodel

  3. Check file size limits on your backend infrastructure

  4. Review error messages for specific validation issues