search

flexiblepower / s2-ws-json

A WebSockets and JSON based protocol specification implementing the EN50491-12-2 "S2" standard for home and building energy management
Apache License 2.0
26 stars 2 forks source link

openapi dots are used in schema names #18

Open lfse-slafleur opened 3 months ago

lfse-slafleur commented 3 months ago

Currently in openapi.yml dots are used in the schema name.

Example (from https://github.com/flexiblepower/s2-ws-json/blob/v0.0.2-beta/s2-schemas-in-openapi-format/s2-ws-json-openapi.yml#L798C10-L798C21):

    DDBC.TimerStatus:
      type: object

This causes the $ref to also contain a dot in the name `. An example may be found here: https://github.com/flexiblepower/s2-ws-json/blob/v0.0.2-beta/s2-schemas-in-openapi-format/s2-ws-json-openapi.yml#L1111

        allowed_limit_ranges:
          type: array
          minItems: 2
          maxItems: 100
          items:
            $ref: '#/components/schemas/PEBC.AllowedLimitRange'

Dots are allowed according to the OpenAPI & jsonschema specifications. However, datamodel-codegen (the Python code generator) handles it erronously by assuming it is part of a path and switches over from single file to modular code generation. Issues at datamodel-codegen already exist:

https://github.com/koxudaxi/datamodel-code-generator/issues/1600 https://github.com/koxudaxi/datamodel-code-generator/issues/2039

Dots are not allowed in Python class names (nor in many other languages) so even if any issues are fixed, the result will not match the openapi specification exactly.

Therefor, the proposal is to remove the dot from the schema name (only) so (faulty) generators will not have a hard time and the result is the same across code generators (as some generators may replace a dot with any replacement of their choosing such as -, _ or just remove it). This would leave the dot intact in the message_type field as according to the specification.

lfse-slafleur commented 3 months ago

@wilcowijbrandi What do you think? Would we want to change the openapi.yml according to the proposal or would your preference be to let code generators handle the dot?