adapter.json allows for invalid `display_name` to be written

[s-heppner]

According to the specification, Referable.display_name should be of type MultiLanguageNameType, and it is also that way in our SDK.
However, if you simply ignore this and write a string, you are still able to write a JSON file, which in turn then is non-compliant. Here's a minimal example:

from basyx.aas import model
from basyx.aas.adapter.json import json_serialization

submodel_1 = model.Submodel(
    id_="https://example.org/some_submodel",
    submodel_element=[model.Property(
        id_short="some_id_short",
        value_type=model.datatypes.String,
        value="someString",
        display_name="Banana",  # Wrong Type here!
        description=model.MultiLanguageTextType({"en": "An apple"})
    )]
)

if __name__ == '__main__':
    with open("model.json", "w") as file:
        json_serialization.write_aas_json_file(file, model.DictObjectStore([submodel_1]), indent=4)

This results in the following model.json:

{
    "submodels": [
        {
            "modelType": "Submodel",
            "id": "https://example.org/some_submodel",
            "submodelElements": [
                {
                    "idShort": "some_id_short",
                    "displayName": "Banana",
                    "description": [
                        {
                            "language": "en",
                            "text": "An apple"
                        }
                    ],
                    "modelType": "Property",
                    "value": "someString",
                    "valueType": "xs:string"
                }
            ]
        }
    ]
}

We should investigate why this happens, where else this type of issue can arise, and what we should do about it.

[ZANDx1]

This issue also arises with Referable.description where a simple string suffices to generate the JSON.

[ZANDx1]

I would suggest adding a type check for displayName and description and depending on the result, the function would either proceed with teh JSON serialization or abort with an error. Creating a JSON file that does not conform to the specifications could cause future errors or confusion, whereas immediate feedback prevents such scenarios. I also had the idea of automatic normalization but I think the user should be responsible to respect the specifications. How is it handled in other SDKs? @s-heppner , @zrgt

[s-heppner]

Creating a JSON file that does not conform to the specifications could cause future errors or confusion, whereas immediate feedback prevents such scenarios.

You are correct. In any case we should never allow invalid (JSON, XML) files to be written. Therefore, at the very least, it should throw an exception during serialization.
I'm a bit more undecided regarding the immediate feedback part. Python in itself is pretty lax when it comes to typing, which is why I was able to accidentally add the wrong type. On the other hand, we have several spots where we write custom setter functions that do not allow invalid content. It would make sense to check it there, especially for something as fundamental as a wrong type. On yet another hand, the generated aas-core SDK, which we want to use at some point as dependency, uses a verification pattern, where all these types of constraints are split from the actual data structure. Such a pattern makes it easier to write editors, where one might have intermediate states that are not correct. What do you think @zrgt?

I also had the idea of automatic normalization but I think the user should be responsible to respect the specifications.

That's something that a front-end application can do imo, but nothing that a fundamental piece of infrastructure, such as our SDK can just decide for the user, so I'm also against this.

[zrgt]

@s-heppner, @ZANDx1 Of course, a verification pattern would make the SDK much more flexible. But if we wanna use it, we should adress it in a separate Issue.

For this specific issue, I would suggest to respect the style/strategy we used before and introduce a setter funcs for description and display_name, where we do the casting from dict to MultiLanguageNameType/MultiLanguageTextType and indirectly check the types of values.