Openapi-specification: dictionary key descriptions/schema (additionalProperties)

[theoephraim]

I 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...

[theoephraim]

Note - the name/label part has been implemented as a an extension in ReDoc

[hkosova]

@theoephraim

It would be great to be able to specify for these keys:

• ...
• a description (ex: "lowercase 2 letter ISO 639-1 Code")
• schema info ex: { type: "string", pattern: '^[a-z]{2}$' }

This will be possible in OAS 3.1 using patternProperties:

type: object
patternProperties:
  '^[a-z]{2}$':    # <--- key regex
    type: string   # <--- value schema
additionalProperties: false

or propertyNames:

type: object
propertyNames:
  pattern: '^[a-z]{2}$':
  description: lowercase 2 letter ISO 639-1 Code
additionalProperties:
  type: string

[xehpuk]

@hkosova I couldn't find it in the 3.1.0 spec.

[handrews]

@xehpuk the OAS document only lists JSON Schema keywords that it changes, and in 3.1.0, most of them are left unchanged.

You can find both of those keywords in the JSON Schema spec (note that there will be another draft for the final 3.1.0 OAS, based on feedback from 3.1.0-rc0 and other parts of the JSON Schema community, but neither of these keywords are expected to change.

[xehpuk]

@handrews I'm not sure I can follow. What does it mean to "change" a keyword? To treat it differently than the JSON Schema defines? (Not a native speaker, probably missing a subtlety.)

If I understand correctly, patternProperties is not supported in 3.0. Where can I see that it isn't and that it will be in 3.1?

[handrews]

@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:

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2019-09.

For more information about the properties, see JSON Schema Core and JSON Schema Validation.

Unless stated otherwise, the property definitions follow the JSON Schema.

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.

[xehpuk]

@handrews Thank you for the elaborate explanation, makes sense to me now. 🙂