Document additionalProperties

README.md

@@ -243,7 +243,7 @@ of the schema (`nil`, `:query`, `:header`, `:path`, `:formData` and `:body`).
 To support truly symmetric web schemas, one needs also to ensure both JSON Serialization and
 deserialization/coercion from JSON.
 
-### Class-based dispatch
+#### Class-based dispatch
 
 ```clojure
 (require '[ring.swagger.json-schema :as json-schema])
@@ -311,6 +311,29 @@ One can also use the options to create more accurate specs (via the `:in` option
   - Nested maps are transformed automatically into flat maps with generated child references
   - Maps can be within valid containers (as only element - heterogeneous schema sequences not supported by the spec)
 
+### Additional Properties, Free-Form Objects
+
+The JSON schema generated for a map is closed (`additionalProperties` is false) unless there are non-keyword map keys, i.e. `s/Keyword` or `s/Str`.
+For example, to create a map of unknown keywords to ints:
+
+```clojure
+(rsjs/schema-object (rsjs/describe {s/Keyword s/Int} "maps keywords to ints"))
+
+; {:type "object"
+;  :description "maps keywords to ints",
+;  :additionalProperties {:format "int64", :type "integer"}}
+```
+
+To create a completely open, [Free-Form](https://swagger.io/docs/specification/data-models/data-types/#free-form) object:
+
+```clojure
+(rsjs/schema-object (rsjs/describe {s/Keyword s/Any} "open map"))
+
+; {:type "object"
+;  :description "open map",
+;  :additionalProperties {}}
+```
+
 ### Missing Schema elements
 
 If Ring-swagger can't transform the Schemas into JSON Schemas, by default a `IllegalArgumentException` will be thrown.

test/ring/swagger/swagger2_test.clj

@@ -308,9 +308,11 @@
   (let [Kikka (s/schema-with-name {:a s/Str s/Str s/Str} 'Kikka)
         Kukka (s/schema-with-name {:a s/Str s/Int Kikka} 'Kukka)
         Kakka (s/schema-with-name {s/Keyword Kukka} 'Kakka)
+        Wakka (s/schema-with-name {:message s/Str s/Keyword s/Any} 'Wakka)
         swagger {:paths {"/kikka" {:post {:parameters {:body Kikka}}}
                          "/kukka" {:post {:parameters {:body Kukka}}}
-                         "/kakka" {:post {:parameters {:body Kakka}}}}}
+                         "/kakka" {:post {:parameters {:body Kakka}
+                                          :responses {100 {:schema Wakka}}}}}}
         spec (swagger2/swagger-json swagger)]
     (validate swagger) => nil
 
@@ -334,7 +336,15 @@
       spec => (has-definition
                 'Kakka
                 {:type "object"
-                 :additionalProperties {:$ref "#/definitions/Kukka"}}))))
+                 :additionalProperties {:$ref "#/definitions/Kukka"}}))
+
+    (fact "open Free-Form object"
+          spec => (has-definition
+                    'Wakka
+                    {:type "object"
+                     :properties {:message {:type "string"}}
+                     :required [:message]
+                     :additionalProperties {}}))))
 
 (fact "extra meta-data to properties"
   (let [Kikka (s/schema-with-name {:a (rsjs/field s/Str {:description "A"})