search

admin-shell-io / aas-specs-api

Repository of the Asset Administration Shell Specification DTA-01002 API
https://admin-shell-io.github.io/aas-specs-antora/index/home/index.html
Creative Commons Attribution 4.0 International
12 stars 5 forks source link

Patch Clarifications #312

Open sebbader-sap opened 2 months ago

sebbader-sap commented 2 months ago

Shall solve the following, similar issues on AAS PATCH:

sebbader-sap commented 2 months ago

Is this available in rendered form?

No, with the current pipeline we have this is not possible. You can view it in a local IDE that has an OpenAPI plugin, though.

sebbader-sap commented 2 months ago
  1. PATCH operations still have level parameter - that does not make sense?

I think you have a point here. We had already an issue on Patch and Level. Please help me to find all occurrences and adjust them.

sebbader-sap commented 2 months ago

PATCH with /$metadata takes type concrete types as input (e.g. Submodel, SubmodelElement). This means one has to send all mandatory fields, i.e., even the ones unchanged. How is that different from classical PUT behavior?

The difference is what we regard as the resource. As the normal representation is the original serialisation, and metadata or value are only projection of it, we decided to use PATCH here.

waltersve commented 2 months ago

From my perspective, PATCH will also work with “/$value” (basically any modification) without compromising any guarantees related to correctness. Of course the validation is enforced in a different way. Given that you have a submodel descriptor referencing a submodel template (a semanticId defining the unique identifier of the model supported by the submodel e.g. urn:samm:io.catenax.battery.battery_pass:6.0.0#BatteryPass) which is for example based on SAMM, the backend has all necessary information to verify the request payload. This can be done using generated artifacts such as JSON Schema, OpenAPI specifications, DTOs with bean annotations related to JSR 380 and the once from Jackson, loading ttl files at runtime and access the semantic information via native interfaces like Java, TypeScript, .. or even generate the database schemas. This approach is also is very efficient for both the submodel (backend) and the API consumer, resulting in smaller request payloads.

mjacoby commented 2 months ago

@waltersve I get what you are saying but this only works under two assumptions

  1. SubmodelTemplates are used
  2. Submodels that are instances of SubmodelTemplates are not allowed to have additional elements not defined in the SMT

The first assumption definitely does not hold in general as it is optional to use SMTs. In fact, SMTs are only a special case and the API must be based on the generic metamodel without any knowledge of any SMTs.

About the section assumption I am not sure if this holds or not. At least I am not aware of any constraint defined in the AAS specification that submodels that use a SubmodelTemplate are not allowed to have properties besides the ones defined in the SubmodelTemplate. If there is such a constraint, please provide a citation. My personal understanding is that SMT specific a set of elements a submodel can/must have but an instance of that SMT is free to contain additional elements.

To summarize, I do not see how PATCH on /$value can work safely besides the very narrow special case you mentioned that might not even be 100% compliant with the specification, i.e., the problem remains unsolved.

sebbader-sap commented 2 months ago

I have also the opinion that the whole behaviour must work even though the server has no knowledge of the used SubmodelTemplates (at the moment it receives the message).