Present OpenAPI additionalProperties field

changelogs/client_server/newsfragments/1162.clarification

@@ -0,0 +1 @@
+Use the `additionalProperties` field from the OpenAPI schemas to indicate that some JSON objects permit additional arbitrary key-value pairs.

layouts/partials/json-schema/resolve-additional-types.html

@@ -15,6 +15,7 @@
     * required
     * enum
     * anchor: a string suitable for using as an html anchor for this object (if `anchor_base` was set, and the object has a title)
+    * additionalProperties: either nil, a boolean, or an OpenAPI schema object (https://swagger.io/specification/#schema-object).
 
   Note that the returned array may contain duplicate objects.
 
@@ -101,5 +102,5 @@
   but with (for example) different examples will be considered different.
 */}}
 {{ define "partials/clean-object" }}
-    {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum "anchor" .anchor) }}
+    {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum "anchor" .anchor "additionalProperties" .additionalProperties) }}
 {{ end }}

layouts/partials/openapi/render-object-table.html

@@ -13,11 +13,21 @@
     In some cases (such as response body specifications) this isn't used, and
     instead properties have a `required` boolean attribute. We support this too.
 
+  * `additionalProperties`: one of
+
+    - `false` (no additional properties are permitted);
+    - `true` (additional properties pairs are permitted, with no constraints);
+    - an OpenAPI schema object [1] (additional properties are permitted, but 
+      with constraints on `property_data`); or
+    - `nil` (not specified in schema, use `true` as a default value).
+
+  [1]: https://swagger.io/specification/#schema-object
 */}}
 
 {{ $title := .title }}
 {{ $properties := .properties}}
 {{ $required := .required}}
+{{ $additionalProperties := .additionalProperties }}
 
 {{ if $properties }}
 
@@ -97,6 +107,27 @@
 
     {{ end }}
 
+ {{/* If additionalProperties is true, do nothing.
+      If additionalProperties is nil, treat is as the default (true) and do nothing.
+      If additionalProperties is false, raise a build-time error:
+      "Everything is extensible in Matrix unless otherwise noted".
+      Otherwise, it should be an OpenAPI schema object. Include the description
+      of that schema object, if it exists. */}}
+ {{ if (and (ne $additionalProperties nil) (ne $additionalProperties true)) }}
+  {{ if (and (reflect.IsMap $additionalProperties)) -}}
+   {{ if (index $additionalProperties "description") -}}
+  <tr class="row-additional-properties">
+   <td colspan="3">
+    <em>Notes on additional properties:</em> {{ $additionalProperties.description }}
+   </td>
+  </tr>
+   {{ end }}
+  {{/* TODO: should we handle the case where additional properties are
+             permitted, but must follow an explicit schema? */}}
+  {{ else if (not $additionalProperties) -}}
+   {{ errorf "Unexpected additionalProperties=false for %s" $title }}
+  {{ end }}
+ {{ end }}
 </table>
 
 {{ end }}