3.1. adapter.json - JSON serialization and deserialization

This package contains functionality for serialization and deserialization of BaSyx Python SDK objects into/from JSON.

json_serialization: The module offers a function to write an ObjectStore to a given file and therefore defines the custom JSONEncoder AASToJsonEncoder which handles encoding of all BaSyx Python SDK objects and their attributes by converting them into standard python objects.

json_deserialization: The module implements custom JSONDecoder classes AASFromJsonDecoder and StrictAASFromJsonDecoder, that — when used with Python’s json module — detect AAS objects in the parsed JSON and convert them into the corresponding BaSyx Python SDK object. A function read_aas_json_file() is provided to read all AAS objects within a JSON file and return them as BaSyx Python SDK objectstore.

3.1.1. adapter.json.json_serialization: JSON serialization of AAS objects

Module for serializing Asset Administration Shell objects to the official JSON format

The module provides an custom JSONEncoder classes AASToJsonEncoder and AASToJsonEncoderStripped to be used with the Python standard json module. While the former serializes objects as defined in the specification, the latter serializes stripped objects, excluding some attributes (see https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91). Each class contains a custom default() function which converts BaSyx Python SDK objects to simple python types for an automatic JSON serialization. To simplify the usage of this module, the write_aas_json_file() and object_store_to_json() are provided. The former is used to serialize a given AbstractObjectStore to a file, while the latter serializes the object store to a string and returns it.

The serialization is performed in an iterative approach: The default() function gets called for every object and checks if an object is an BaSyx Python SDK object. In this case, it calls a special function for the respective BaSyx Python SDK class which converts the object (but not the contained objects) into a simple Python dict, which is serializable. Any contained BaSyx Python SDK objects are included into the dict as they are to be converted later on. The special helper function _abstract_classes_to_json() is called by most of the conversion functions to handle all the attributes of abstract base classes.

class basyx.aas.adapter.json.json_serialization.AASToJsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Custom JSON Encoder class to use the json module for serializing Asset Administration Shell data into the official JSON format

The class overrides the default() method to transform BaSyx Python SDK objects into dicts that may be serialized by the standard encode method.

Typical usage:

json_string = json.dumps(data, cls=AASToJsonEncoder)
Variables

stripped – If True, the JSON objects will be serialized in a stripped manner, excluding some attributes. Defaults to False. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91

default(obj: object) → object

The overwritten default method for json.JSONEncoder

Parameters

obj – The object to serialize to json

Returns

The serialized object

class basyx.aas.adapter.json.json_serialization.StrippedAASToJsonEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

AASToJsonEncoder for stripped objects. Used in the HTTP API. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91

basyx.aas.adapter.json.json_serialization.object_store_to_json(data: basyx.aas.model.provider.AbstractObjectStore, stripped: bool = False, encoder: Optional[Type[basyx.aas.adapter.json.json_serialization.AASToJsonEncoder]] = None, **kwargs) → str

Create a json serialization of a set of AAS objects according to ‘Details of the Asset Administration Shell’, chapter 5.5

Parameters

  • data – ObjectStore which contains different objects of the AAS meta model which should be serialized to a JSON file

  • stripped – If true, objects are serialized to stripped json objects. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91 This parameter is ignored if an encoder class is specified.

  • encoder – The encoder class used to encode the JSON objects

  • kwargs – Additional keyword arguments to be passed to json.dumps()

basyx.aas.adapter.json.json_serialization.write_aas_json_file(file: IO, data: basyx.aas.model.provider.AbstractObjectStore, stripped: bool = False, encoder: Optional[Type[basyx.aas.adapter.json.json_serialization.AASToJsonEncoder]] = None, **kwargs) → None

Write a set of AAS objects to an Asset Administration Shell JSON file according to ‘Details of the Asset Administration Shell’, chapter 5.5

Parameters

  • file – A file-like object to write the JSON-serialized data to

  • data – ObjectStore which contains different objects of the AAS meta model which should be serialized to a JSON file

  • stripped – If True, objects are serialized to stripped json objects. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91 This parameter is ignored if an encoder class is specified.

  • encoder – The encoder class used to encode the JSON objects

  • kwargs – Additional keyword arguments to be passed to json.dump()

3.1.2. adapter.json.json_deserialization: JSON deserialization into AAS objects

Module for deserializing Asset Administration Shell data from the official JSON format

The module provides custom JSONDecoder classes AASFromJsonDecoder and StrictAASFromJsonDecoder to be used with the Python standard json module.

Furthermore it provides two classes StrippedAASFromJsonDecoder and StrictStrippedAASFromJsonDecoder for parsing stripped JSON objects, which are used in the http adapter (see https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91). The classes contain a custom object_hook() function to detect encoded AAS objects within the JSON data and convert them to BaSyx Python SDK objects while parsing. Additionally, there’s the read_aas_json_file_into() function, that takes a complete AAS JSON file, reads its contents and stores the objects in the provided AbstractObjectStore. read_aas_json_file() is a wrapper for this function. Instead of storing the objects in a given AbstractObjectStore, it returns a DictObjectStore containing parsed objects.

The deserialization is performed in a bottom-up approach: The object_hook() method gets called for every parsed JSON object (as dict) and checks for existence of the modelType attribute. If it is present, the AAS_CLASS_PARSERS dict defines, which of the constructor methods of the class is to be used for converting the dict into an object. Embedded objects that should have a modelType themselves are expected to be converted already. Other embedded objects are converted using a number of helper constructor methods.

class basyx.aas.adapter.json.json_deserialization.AASFromJsonDecoder(*args, **kwargs)

Custom JSONDecoder class to use the json module for deserializing Asset Administration Shell data from the official JSON format

The class contains a custom object_hook() function to detect encoded AAS objects within the JSON data and convert them to BaSyx Python SDK objects while parsing.

Typical usage:

data = json.loads(json_string, cls=AASFromJsonDecoder)

The object_hook function uses a set of _construct_*() methods, one for each AAS object type to transform the JSON objects in to BaSyx Python SDK objects. These constructor methods are divided into two parts: “Helper Constructor Methods”, that are used to construct AAS object types without a modelType attribute as embedded objects within other AAS objects, and “Direct Constructor Methods” for AAS object types with modelType attribute. The former are called from other constructor methods or utility methods based on the expected type of an attribute, the latter are called directly from the object_hook() function based on the modelType attribute.

This class may be subclassed to override some of the constructor functions, e.g. to construct objects of specialized subclasses of the BaSyx Python SDK object classes instead of these normal classes from the model package. To simplify this tasks, (nearly) all the constructor methods take a parameter object_type defaulting to the normal BaSyx Python SDK object class, that can be overridden in a derived function:



class EnhancedSubmodel(model.Submodel):
    pass

class EnhancedAASDecoder(StrictAASFromJsonDecoder):
    @classmethod
    def _construct_submodel(cls, dct, object_class=EnhancedSubmodel):
        return super()._construct_submodel(dct, object_class=object_class)
Variables

  • failsafe – If True (the default), don’t raise Exceptions for missing attributes and wrong types, but instead skip defective objects and use logger to output warnings. Use StrictAASFromJsonDecoder for a non-failsafe version.

  • stripped – If True, the JSON objects will be parsed in a stripped manner, excluding some attributes. Defaults to False. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91

class basyx.aas.adapter.json.json_deserialization.StrictAASFromJsonDecoder(*args, **kwargs)

A strict version of the AASFromJsonDecoder class for deserializing Asset Administration Shell data from the official JSON format

This version has set failsafe = False, which will lead to Exceptions raised for every missing attribute or wrong object type.

class basyx.aas.adapter.json.json_deserialization.StrictStrippedAASFromJsonDecoder(*args, **kwargs)

Non-failsafe decoder for stripped JSON objects.

class basyx.aas.adapter.json.json_deserialization.StrippedAASFromJsonDecoder(*args, **kwargs)

Decoder for stripped JSON objects. Used in the HTTP adapter.

basyx.aas.adapter.json.json_deserialization.read_aas_json_file(file: IO, **kwargs) → basyx.aas.model.provider.DictObjectStore[basyx.aas.model.base.Identifiable]

A wrapper of read_aas_json_file_into(), that reads all objects in an empty DictObjectStore. This function supports the same keyword arguments as read_aas_json_file_into().

Parameters

  • file – A filename or file-like object to read the JSON-serialized data from

  • kwargs – Keyword arguments passed to read_aas_json_file_into()

Returns

A DictObjectStore containing all AAS objects from the JSON file

basyx.aas.adapter.json.json_deserialization.read_aas_json_file_into(object_store: basyx.aas.model.provider.AbstractObjectStore, file: IO, replace_existing: bool = False, ignore_existing: bool = False, failsafe: bool = True, stripped: bool = False, decoder: Optional[Type[basyx.aas.adapter.json.json_deserialization.AASFromJsonDecoder]] = None) → Set[str]

Read an Asset Administration Shell JSON file according to ‘Details of the Asset Administration Shell’, chapter 5.5 into a given object store.

Parameters

  • object_store – The ObjectStore in which the identifiable objects should be stored

  • file – A file-like object to read the JSON-serialized data from

  • replace_existing – Whether to replace existing objects with the same identifier in the object store or not

  • ignore_existing – Whether to ignore existing objects (e.g. log a message) or raise an error. This parameter is ignored if replace_existing is True.

  • failsafe – If True, the document is parsed in a failsafe way: Missing attributes and elements are logged instead of causing exceptions. Defect objects are skipped. This parameter is ignored if a decoder class is specified.

  • stripped – If True, stripped JSON objects are parsed. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91 This parameter is ignored if a decoder class is specified.

  • decoder – The decoder class used to decode the JSON objects

Returns

A set of Identifiers that were added to object_store