OpenAPI.NET
OpenAPI.NET copied to clipboard
microsoft
OpenApiSchema.AdditionalProperties = true does not show up in Document
Problem
When OpenApiSchema.AdditionalProperties is set to False, the resulting document shows up as
type: object
additionalProperties: false
But, when it is set to true (the default, I know), additionalProperties is not present in the document, e,g,
type: object
However, this creates an inconsistent document.
Desired Result
type: object
additionalProperties: true
Workaround
The workaround is to set to the AdditionalProperties value to an empty schema object, resulting in
type: object
additionalProperties: {}
additionalProperties is true by default. Is there a reason why you want additionalProperties to be emitted in the output? The challenge we have is knowing when to emit default values. Especially with something like JSON Schema that has so many properties we would end up emitting a lot of redundant properties.
The main reason was because of the documentation of the spec: https://swagger.io/docs/specification/data-models/dictionaries/
The part that says:
Free-Form Objects
If the dictionary values can be of any type (aka free-form object), use additionalProperties: true:
type: object
additionalProperties: true
The spec is telling me I need to include additionalProperties: true. I understand that is the default, according to your team (and I am not really doubting you as I am no expert here), but it just does not appear that way to a consumer of the documentation. Perhaps the documentation of the spec should be adjusted then to mention that it is not actually necessary to include additionalProperties: true. Or, perhaps, there is some other misunderstanding? There just is not a way to tell from my perspective.
@unparalleled-js Just for clarity, that's not the spec. The OpenAPI specification is here https://spec.openapis.org/oas/v3.1.0
I will reach out to the Smartbear team who write the docs you referenced to add that clarification. Thanks for the highlighting this issue.
@darrelmiller: I think I may be seeing a similar issue. In our case, we're converting CSDL with open types to OpenApi.
The schema specifies an open ComplexType with no properties:
<ComplexType Name="exampleType" OpenType="true" />
Converting and serializing the CSDL results in an OpenAPI object without additionalProperties defined:
components:
schemas:
my.namespace..exampleType:
type: object
What I expected to see (although possibly mistakenly) was:
components:
schemas:
my.namespace..exampleType:
type: object
additionalProperties: true
@mlafleur The two schemas you are showing are functionally equivalent. The default value of additionalProperties was not defined well in OpenAPI 2.0 and so some tooling (i.e. AutoREST) assumed the opposite. It is clearly defined in the JSON Schema spec https://json-schema.org/understanding-json-schema/reference/object.html#additional-properties
For tools that assume the wrong default, like AutoREST, we created a visitor that updated the AdditionalProperties with an empty object. https://github.com/microsoftgraph/microsoft-graph-devx-api/blob/253e66392d81e8a0ced205d952aaaa029359f2d6/OpenAPIService/PowershellFormatter.cs#L101