trolie / spec

Transmission Ratings and Operating Limits Information Exchange
https://trolie.energy/
Other
3 stars 2 forks source link

extraneous elements are permitted due to use of `allOf` #162

Open catkins-miso opened 6 days ago

catkins-miso commented 6 days ago

As identified in #158, examples in the spec can have elements that are not specified, and the linter doesn't catch them. This is because we cannot use additionalProperties: false to constrain the message schema as discussed here https://github.com/trolie/spec/issues/158#issuecomment-2342295893

Unfortunately, the idea of using YAML merge, e.g., <<: *merge_token to hack our way out of this situation is not practicable, since most of the allOf uses also employ $ref inclusions, and YAML merge only supports same-file definitions.

It's important to note that the impact here isn't just the examples in the spec, but also the allowable messages in a TROLIE-conformant information exchange. Technically, the spec currently allows any number of spurious properties to be included in a message. Tools like 42crunch explicitly warn about this, but we've necessarily ignored them for these allOf properties.

AFAICT, that leaves us with the options of:

I cannot really evaluate the cost of moving to OpenAPI 3.1.0 without feedback from current and potential implementors, but we originally wanted to provide the broadest support possible for the API client generators, and unfortunately some popular tools do not support it.

catkins-miso commented 6 days ago

FWIW, the impetus for creating this issue was finding another instance of an extraneous element https://github.com/trolie/spec/blob/b83beae9bd6ccc647a2f08a44c81517ef6218e59/docs/example-narratives/examples/forecast-limits-detailed.json#L49