Open wsalembi opened 1 year ago
I don't think it is needed:
HttpLink
It is usually only used in the response, not in requests (and the rule only applies to requests). Also, APIs usually use HttpLink in combination with an allOf, so the other properties are known, e.g.
PersonReference:
allOf:
- "$ref": "./common/v1/common-v1.yaml#/definitions/HttpLink"
- type: object
properties:
ssin:
"$ref": "#/definitions/Ssin"
LocalizedString
If a Belgian API deviates from the three declared languages (nl, fr, de), it usually declares its own variant type to be explicit about which languages are provided. E.g. if the server supports "nl", "fr" and "en", using the LocalizedString from openapi-common would lead the client to believe that "de" would be processed by the server but it would be silently ignored, and that "en" isn't supported.
Such a type can still evolve in a backwards-compatible manner. E.g. removal of a language is covered:
In specific situations, where a (known) input parameter is not needed anymore and can be safely ignored:
- either it can stay in the API definition with a deprecation flag and a "not used anymore" description
- or it can be removed from the API definition as long as the server ignores this specific parameter.
If types are meant to be extended then I think there is no issue in configuring that explicitly in the common schemas.
LocalizedString
documents in the schema that additional languages can be added (#nl, fr, de are predefined, but additional languages can be added
). I don't think it is necessary to subclass LocalizedString
into LocalizedStringWithEnglishAdded
to add en
for example.
The same applies to HttpLink
and also Problem
. Problem
is meant to be enriched with additional properties in the specification. For some problem types we want to make it very explicit by subclassing it, but it should not be an obligation.
We require a default /components/responses/ProblemResponse
on each resource, but if that response is triggered we loose all the extra properties because we don't have added a catch-all additionalProperties
map to the generated classes.
I think there are two closely related issues in this discussion: how to best document extensions of types, and how to implement open-world polymorphism. The latter issue is about the loss of extra properties when deserializing a Problem
.
edit: moved rest of the comment to a new discussion in #153
Following https://github.com/belgif/rest-guide/issues/110 and the decision to not accept unknown properties, some objects in openapi-commons must be changed to mark them explicitly extensible