dictionary key descriptions/schema (additionalProperties)
See original GitHub issueI didnt see any way to add documentation/info about the keys that can be used when using dictionaries (ie “additionalProperties”)
In the swagger docs example here, it appears the valid keys are all 2 letter ISO language codes. It would be great to be able to specify for these keys:
- a name/label to be used in display rather than something generic like “property name*” (ex: “language code”)
- a description (ex: “lowercase 2 letter ISO 639-1 Code”)
- schema info ex:
{ type: "string", pattern: '^[a-z]{2}$' }
Also as a sidenote, the name “additionalProperties” isn’t super intuitive, but probably somewhat settled to change it now…
Issue Analytics
- State:
- Created 3 years ago
- Reactions:3
- Comments:7 (3 by maintainers)
Top Results From Across the Web
Dictionaries, Hashmaps, Associative Arrays - Swagger
The additionalProperties keyword specifies the type of values in the dictionary. Values can be primitives (strings, numbers or boolean values), arrays or ...
Read more >Why `additionalProperties` is the way to represent Dictionary ...
JSON Schema uses the properties keyword to validate name-value pairs that are known in advance; and uses additionalProperties (or ...
Read more >object — Understanding JSON Schema 2020-12 documentation
In JSON, the “keys” must always be strings. Each of these pairs is conventionally referred to as a “property”. Language-specific info: Python; Ruby....
Read more >Objects - JSON Schema
Objects in JSON are collections of key:value pairs, where the values in these ... is to restrict the structure of the additional properties...
Read more >Schema Types — Atlas App Services - MongoDB
A detailed description of the data that the schema models. ... A dictionary is a collection of dynamic and unique string keys paired...
Read more >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
@xehpuk
In 3.0 and earlier, some keywords in the Schema Object are taken from the JSON Schema specification (a much older draft), and some are specific to OAS. Of the keywords taken from the JSON Schema specification, some mean exactly what they mean in JSON Schema (“unchanged”), while others have restrictions or additional behavior in OAS that is not present in JSON Schema (“changed”).
OAS 3.0 explicitly lists which JSON Schema keywords it uses, and whether they are changed. ‘patternProperties’ is not in the list so it is not supported. ‘propertyNames’ did not exist in that draft of JSON Schema, so it’s not supported either.
In OAS 3.1 all JSON Schema keywords are included unchanged. Therefore they are not explicitly listed in the OpenAPI Specification. So you won’t find ‘propertyNames’ or ‘patternProperties’ in the spec (it just happens that neither are used in any examples either). But you do see:
Which links to where those keywords are defined (the JSON Schema Core link is the same document I linked you to above, except I linked to a specific section).
You can use any of the JSON Schema keywords in the Core and Validation specs (although I strongly recommend ignoring
$recursiveRef
and$recursiveAnchor
as they are rarely needed and too complicated to be used effectively: the next JSON Schema draft, which OAS 3.1 final will reference, will have simpler keywords replacing those two.@theoephraim
This will be possible in OAS 3.1 using
patternProperties
:or
propertyNames
: