[Task] Add Model information to the Openapi Spec

[matgnt]

This is a feature request with low priority.

Is your task related to a problem? Please describe. When I generate the code from the openapi spec, I want some basic model meta information included, e.g. the org name, model name, version, maybe more...

Describe the solution you'd like Probably an enum with that kind of information, like 'XXModel.org' or 'XXModel.version' or 'XXModel.fullName'

Describe alternatives you've considered I'm currently defining those additionally even though, the information would be available from the source of what is used to create the openapi spec.

Thanks for the tools, Matthias Binzer

[atextor]

Hi @matgnt, IMO including meta model information in the generated OpenAPI spec is generally a good idea. However, we would need to clarify exactly how this is included, i.e., which OpenAPI fields are used for this information. Could you give an example for a (minimal) Aspect Model and how you think the generated OpenAPI spec should look for that? The basic metadata info object does not provide many fields that would be useful for this, so I guess we would have to rely on specification extensions.

[matgnt]

Yes, probably a good idea to add the information to the metadata info object. Since I'm not sure if all code generators would use this information and 'how', maybe to following could be an option, too.

Example TTL file: https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.assembly_part_relationship/1.1.1/AssemblyPartRelationship.ttl#L33 (gen folder contains the generated files...)

A potential option could be something like:

components:
  schemas:
    ModelPrefixName:
      type: string
      enum:
      - "urn:bamm:io.catenax.assembly_part_relationship:1.1.1#"
    ModelName:
      type: string
      enum:
      - "AssemblyPartRelationship"
    ModelFullName:
      type: string
      enum:
      - "urn:bamm:io.catenax.assembly_part_relationship:1.1.1#AssemblyPartRelationship"

I think there is no other proper way to add some 'const' information to an openapi spec.

This would generate the enums that could be used. Disadvantage would be, when a version changes, also the enum names would change.

[atextor]

Although I think it's an interesting workaround to use single-valued enums, I don't understand why you would want to create schemas (which are then unused in the actual endpoint descriptoins) for model meta data. Additionally, I see no need to include the information redudant like this (i.e., the Aspect URN and then its split parts).

I propose a specification extension x-samm-aspect-model-urn that would be added to the info object. For the AssemblyPartRelationship model, this would look like this:

---
openapi: 3.0.3
info:
  title: Assembly Part Relationship
  version: v1
  x-samm-aspect-model-urn: "urn:bamm:io.catenax.assembly_part_relationship:1.1.1#AssemblyPartRelationship"
servers:
- url: http://localhost/api/v1
  variables:
    api-version:
      default: v1
paths:
# ...

Of course, including a 1:1 mapping between the API description and the Aspect Model also has a disadvantage; since you mentioned the version change: Not including a direct reference to the Aspect Model in the payload (such as, using JSON-LD for an Aspect payload) is by design: This allows you have one Aspect API to be valid according to multiple versions of the same Aspect Model, as long as the payload structure and value types and restrictions remain the same. For example, you could have a FooAspect 1.0.0 and its corresponding API; when you do non-breaking changes such as updating samm:descriptions or further restricting value ranges in a version 1.1.0, the API could provide 1.1.0-compliant data and still be valid for 1.0.0.

Although adding the specification extension does not alter the Aspect API's payload structure, it could lead to confusion. That being said, I'm not against such an extension. Tools can make use of it if it's present, but since it's an extension, can also ignore it. What do you think?

[matgnt]

Yes, you're right, it is not used in any endpoint here. It is an endpoint generated from another Openapi Spec. E.g. the one from the AAS Registry. I use the string "urn:bamm:io.catenax.assembly_part_relationship:1.1.1#AssemblyPartRelationship" when creating an endpoint of an AAS in the registry. There, you need to provide the semanticId and therefore, currently it is a little bit of manual work :-)

[matbmoser]

In regards of the JSON payload generated:

In my understanding would be good to have a json which can contain a generic node structure including "name", "description", and other attributes. Also would be important to search for this attributes because of this a "ref" for the path to this node in tree.

This would be my proposal:

[matbmoser]

I created a separate issue related to that maybe it could be a solution: https://github.com/eclipse-esmf/esmf-sdk/issues/491

[github-actions[bot]]

Release v2.6.1 addresses this.