HTTPApiDecoder does not support parsing ConceptDescription objects - Breaking POST/PUT operations #395
Description
Description
The BaSyx Python SDK's HTTPApiDecoder class does not support parsing ConceptDescription objects from HTTP request bodies, which prevents POST and PUT operations on the /concept-descriptions endpoint. This is a critical limitation as ConceptDescription is a fundamental component of the Asset Administration Shell (AAS) v3.0 specification.
Current Behavior
When attempting to POST a ConceptDescription via the HTTP API, the following error occurs:
TypeError: Parsing <class 'basyx.aas.model.concept.ConceptDescription'> is not supported!
Expected Behavior
The HTTPApiDecoder should be able to parse ConceptDescription objects from JSON/XML request bodies, enabling full CRUD operations as specified in the AAS API specification Part 2.
Steps to Reproduce
1. Server Setup
from basyx.aas import model
from basyx.aas.adapter.http import WSGIApp
# Create object store and app
object_store = model.DictObjectStore()
app = WSGIApp(object_store)
# Run server (e.g., with werkzeug)
from werkzeug.serving import run_simple
run_simple('localhost', 8080, app, use_debugger=True, use_reloader=True)2. Client Code That Triggers the Error
from aas_python_http_client import ApiClient, Configuration, ConceptDescriptionRepositoryAPIApi
from basyx.aas import model
# Configure client
configuration = Configuration()
configuration.host = "http://localhost:8080/api/v3.0"
api_client = ApiClient(configuration=configuration)
cd_client = ConceptDescriptionRepositoryAPIApi(api_client=api_client)
# Create and POST a ConceptDescription
cd = model.ConceptDescription("https://acplt.org/TestConceptDescription1")
result = cd_client.post_concept_description(cd) # This fails!3. Actual Error Output
127.0.0.1 - - [23/Jun/2025 14:55:37] "POST /api/v3.0/concept-descriptions HTTP/1.1" 500 -
Traceback (most recent call last):
File "C:\Users\igor\PycharmProjects\basyx-python-sdk\sdk\basyx\aas\adapter\http.py", line 1160, in post_concept_description
concept_description = HTTPApiDecoder.request_body(request, model.ConceptDescription,
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "C:\Users\igor\PycharmProjects\basyx-python-sdk\sdk\basyx\aas\adapter\http.py", line 305, in check_type_supportance
raise TypeError(f"Parsing {type_} is not supported!")
TypeError: Parsing <class 'basyx.aas.model.concept.ConceptDescription'> is not supported!
Root Cause Analysis
The issue is in /basyx/aas/adapter/http.py around line 290. The type_constructables_map dictionary is missing the ConceptDescription entry:
# Current implementation (INCOMPLETE)
type_constructables_map = {
model.AssetAdministrationShell: XMLConstructables.ASSET_ADMINISTRATION_SHELL,
model.AssetInformation: XMLConstructables.ASSET_INFORMATION,
model.ModelReference: XMLConstructables.MODEL_REFERENCE,
model.SpecificAssetId: XMLConstructables.SPECIFIC_ASSET_ID,
model.Qualifier: XMLConstructables.QUALIFIER,
model.Submodel: XMLConstructables.SUBMODEL,
model.SubmodelElement: XMLConstructables.SUBMODEL_ELEMENT,
model.Reference: XMLConstructables.REFERENCE
# MISSING: model.ConceptDescription: XMLConstructables.CONCEPT_DESCRIPTION
}Proposed Solution
1. Add ConceptDescription to type_constructables_map
In /basyx/aas/adapter/http.py, update the type_constructables_map:
type_constructables_map = {
model.AssetAdministrationShell: XMLConstructables.ASSET_ADMINISTRATION_SHELL,
model.AssetInformation: XMLConstructables.ASSET_INFORMATION,
model.ModelReference: XMLConstructables.MODEL_REFERENCE,
model.SpecificAssetId: XMLConstructables.SPECIFIC_ASSET_ID,
model.Qualifier: XMLConstructables.QUALIFIER,
model.Submodel: XMLConstructables.SUBMODEL,
model.SubmodelElement: XMLConstructables.SUBMODEL_ELEMENT,
model.Reference: XMLConstructables.REFERENCE,
model.ConceptDescription: XMLConstructables.CONCEPT_DESCRIPTION # ADD THIS LINE
}2. Ensure XMLConstructables.CONCEPT_DESCRIPTION exists
Verify that XMLConstructables.CONCEPT_DESCRIPTION is defined in the XML adapter. If not, it needs to be added.
3. Verify JSON deserialization support
Ensure the JSON deserializer properly handles ConceptDescription objects. The AASFromJsonDecoder should have the necessary methods to deserialize ConceptDescription from JSON.
Impact
Without this fix:
- ❌ Cannot create ConceptDescriptions via API (POST)
- ❌ Cannot update ConceptDescriptions via API (PUT)
- ❌ API is not fully compliant with AAS v3.0 specification
- ❌ Users must resort to workarounds like direct database manipulation
Operations affected:
| Method | Endpoint | Status | Notes |
|---|---|---|---|
| GET | /concept-descriptions |
✅ Works | No parsing required |
| GET | /concept-descriptions/{cdIdentifier} |
✅ Works | No parsing required |
| POST | /concept-descriptions |
❌ Broken | Requires request body parsing |
| PUT | /concept-descriptions/{cdIdentifier} |
❌ Broken | Requires request body parsing |
| DELETE | /concept-descriptions/{cdIdentifier} |
✅ Works | No parsing required |
Test Case
Here's a test that should pass once this issue is fixed:
def test_post_concept_description():
"""Test creating a ConceptDescription via HTTP API"""
# Setup
object_store = model.DictObjectStore()
app = WSGIApp(object_store)
client = app.test_client()
# Create ConceptDescription data
cd_data = {
"modelType": "ConceptDescription",
"id": "https://example.com/cd/test",
"idShort": "TestConcept",
"category": "PROPERTY",
"embeddedDataSpecifications": [{
"dataSpecification": {
"keys": [{
"type": "GlobalReference",
"value": "http://admin-shell.io/DataSpecificationTemplates/DataSpecificationIEC61360/3/0"
}]
},
"dataSpecificationContent": {
"modelType": "DataSpecificationIec61360",
"preferredName": [{"language": "en", "text": "Test Concept"}],
"dataType": "STRING"
}
}]
}
# POST request
response = client.post(
'/api/v3.0/concept-descriptions',
json=cd_data,
headers={'Content-Type': 'application/json'}
)
# Assertions
assert response.status_code == 201
assert response.json["id"] == "https://example.com/cd/test"
# Verify it was stored
stored_cd = object_store.get(model.ConceptDescription, "https://example.com/cd/test")
assert stored_cd is not None
assert stored_cd.id_short == "TestConcept"Environment
- BaSyx Python SDK Version: 1.0.0 (latest)
- Python Version: 3.10+
- Operating System: Windows/Linux/macOS (all affected)
- Related Components: basyx.aas.adapter.http.HTTPApiDecoder
Additional Context
This issue is blocking full implementation of Digital Product Passport systems that rely on ConceptDescription management via the API. ConceptDescriptions are essential for:
- Defining semantic meaning of properties
- Ensuring interoperability between different AAS implementations
- Compliance with IDTA specifications
- Managing data specifications (IEC 61360, etc.)
References
Checklist
- I have checked that this issue has not already been reported
- I have provided a minimal code example that reproduces the issue
- I have included the full error message and stack trace
- I have suggested a potential solution
- I am using the latest version of BaSyx Python SDK
Thank you for your attention to this issue. ConceptDescription support is crucial for complete AAS v3.0 API compliance. I'm happy to provide additional information or assist with testing the fix.
Temporary Workaround
Until this is fixed, users can work around this limitation by:
- Pre-loading ConceptDescriptions from files during application startup
- Direct object store manipulation (bypassing HTTP API)
- Using only GET/DELETE operations which don't require parsing
However, these workarounds are not ideal for production systems that require dynamic ConceptDescription management.