JSON Schema update/refactor/augment, to conform to spec

.gitignore

@@ -12,6 +12,7 @@ htmlcov/
 benchmarks/*.json
 docs/_build/
 docs/.TMP_HISTORY.rst
+docs/.tmp_schema_mappings.rst
 .pytest_cache/
 .vscode/
 _build/

HISTORY.rst

@@ -3,6 +3,12 @@
 History
 -------
 
+v0.16.0 (2018-XX-XX)
+....................
+
+* refactor schema generation to be compatible with JSON Schema and OpenAPI specs, #308 by @tiangolo
+* add ``schema`` to ``schema`` module to generate top-level schemas from base models, #308 by @tiangolo
+
 v0.15.0 (2018-11-18)
 ....................
 * move codebase to use black, #287 by @samuelcolvin

docs/Makefile

@@ -14,6 +14,7 @@ clean:
 
 .PHONY: html
 html: clean
+	./schema_mapping.py
 	mkdir -p $(STATICDIR)
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo

docs/examples/schema1.json

@@ -1,42 +1,48 @@
 {
-  "type": "object",
   "title": "Main",
   "description": "This is the description of the main model",
+  "type": "object",
   "properties": {
     "foo_bar": {
-      "type": "object",
+      "$ref": "#/definitions/FooBar"
+    },
+    "Gender": {
+      "title": "Gender",
+      "enum": [
+        "male",
+        "female",
+        "other",
+        "not_given"
+      ],
+      "type": "string"
+    },
+    "snap": {
+      "title": "The Snap",
+      "default": 42,
+      "description": "this is the value of snap",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "foo_bar"
+  ],
+  "definitions": {
+    "FooBar": {
       "title": "FooBar",
+      "type": "object",
       "properties": {
         "count": {
-          "type": "int",
           "title": "Count",
-          "required": true
+          "type": "integer"
         },
         "size": {
-          "type": "float",
           "title": "Size",
-          "required": false
+          "type": "number"
         }
       },
-      "required": true
-    },
-    "Gender": {
-      "type": "int",
-      "title": "Gender",
-      "required": false,
-      "choices": [
-        [1, "Male"],
-        [2, "Female"],
-        [3, "Other"],
-        [4, "I'd rather not say"]
+      "required": [
+        "count"
       ]
-    },
-    "snap": {
-      "type": "int",
-      "title": "The Snap",
-      "required": false,
-      "default": 42,
-      "description": "this is the value of snap"
     }
   }
 }

docs/examples/schema1.py

@@ -1,15 +1,15 @@
-from enum import IntEnum
+from enum import Enum
 from pydantic import BaseModel, Schema
 
 class FooBar(BaseModel):
     count: int
     size: float = None
 
-class Gender(IntEnum):
-    male = 1
-    female = 2
-    other = 3
-    not_given = 4
+class Gender(str, Enum):
+    male = 'male'
+    female = 'female'
+    other = 'other'
+    not_given = 'not_given'
 
 class MainModel(BaseModel):
     """
@@ -19,12 +19,11 @@ class MainModel(BaseModel):
     gender: Gender = Schema(
         None,
         alias='Gender',
-        choice_names={3: 'Other Gender', 4: "I'd rather not say"}
     )
     snap: int = Schema(
         42,
         title='The Snap',
-        description='this is the value of snap'
+        description='this is the value of snap',
     )
 
     class Config:

docs/examples/schema2.json

@@ -0,0 +1,40 @@
+{
+  "title": "My Schema",
+  "definitions": {
+    "Foo": {
+      "title": "Foo",
+      "type": "object",
+      "properties": {
+        "a": {
+          "title": "A",
+          "type": "string"
+        }
+      }
+    },
+    "Model": {
+      "title": "Model",
+      "type": "object",
+      "properties": {
+        "b": {
+          "$ref": "#/definitions/Foo"
+        }
+      },
+      "required": [
+        "b"
+      ]
+    },
+    "Bar": {
+      "title": "Bar",
+      "type": "object",
+      "properties": {
+        "c": {
+          "title": "C",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "c"
+      ]
+    }
+  }
+}

docs/examples/schema2.py

@@ -0,0 +1,26 @@
+import json
+from pydantic import BaseModel
+from pydantic.schema import schema
+
+
+class Foo(BaseModel):
+    a: str = None
+
+
+class Model(BaseModel):
+    b: Foo
+
+
+class Bar(BaseModel):
+    c: int
+
+
+top_level_schema = schema([Model, Bar], title='My Schema')
+print(json.dumps(top_level_schema, indent=2))
+
+# {
+#   "title": "My Schema",
+#   "definitions": {
+#     "Foo": {
+#       "title": "Foo",
+#       ...

docs/examples/schema3.json

@@ -0,0 +1,29 @@
+{
+  "definitions": {
+    "Foo": {
+      "title": "Foo",
+      "type": "object",
+      "properties": {
+        "a": {
+          "title": "A",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "a"
+      ]
+    },
+    "Model": {
+      "title": "Model",
+      "type": "object",
+      "properties": {
+        "a": {
+          "$ref": "#/components/schemas/Foo"
+        }
+      },
+      "required": [
+        "a"
+      ]
+    }
+  }
+}

docs/examples/schema3.py

@@ -0,0 +1,20 @@
+import json
+from pydantic import BaseModel
+from pydantic.schema import schema
+
+class Foo(BaseModel):
+    a: int
+
+class Model(BaseModel):
+    a: Foo
+
+
+top_level_schema = schema([Model], ref_prefix='#/components/schemas/')  # Default location for OpenAPI
+print(json.dumps(top_level_schema, indent=2))
+
+# {
+#   "definitions": {
+#     "Foo": {
+#       "title": "Foo",
+#       "type": "object",
+#       ...

docs/index.rst

@@ -219,32 +219,39 @@ The ellipsis ``...`` just means "Required" same as annotation only declarations
 Schema Creation
 ...............
 
-*Pydantic* allows auto creation of schemas from models:
+*Pydantic* allows auto creation of JSON Schemas from models:
 
 .. literalinclude:: examples/schema1.py
 
+(This script is complete, it should run "as is")
+
 Outputs:
 
 .. literalinclude:: examples/schema1.json
 
-(This script is complete, it should run "as is")
+The generated schemas are compliant with the specifications:
+`JSON Schema Core <https://json-schema.org/latest/json-schema-core.html>`__,
+`JSON Schema Validation <https://json-schema.org/latest/json-schema-validation.html>`__ and 
+`OpenAPI <https://github.com/OAI/OpenAPI-Specification>`__.
 
-`schema` will return a dict of the schema, while `schema_json` will return a JSON representation of that.
+``BaseModel.schema`` will return a dict of the schema, while ``BaseModel.schema_json`` will return a JSON string
+representation of that.
 
-"submodels" are recursively included in the schema.
+Sub-models used are added to the ``definitions`` JSON attribute and referenced, as per the spec.
 
-The ``description`` for models is taken from the docstring of the class.
+All sub-models (and their sub-models) schemas are put directly in a top-level ``definitions`` JSON key for easy re-use
+and reference.
 
-Enums are shown in the schema as choices, optionally the ``choice_names`` argument can be used
-to provide human friendly descriptions for the choices. If  ``choice_names`` is omitted or misses values,
-descriptions will be generated by calling ``.title()`` on the name of the member.
+"sub-models" with modifications (via the ``Schema`` class) like a custom title, description or default value,
+are recursively included instead of referenced.
+
+The ``description`` for models is taken from the docstring of the class.
 
 Optionally the ``Schema`` class can be used to provide extra information about the field, arguments:
 
 * ``default`` (positional argument), since the ``Schema`` is replacing the field's default, its first
   argument is used to set the default, use ellipsis (``...``) to indicate the field is required
 * ``title`` if omitted ``field_name.title()`` is used
-* ``choice_names`` as described above
 * ``alias`` - the public name of the field.
 * ``**`` any other keyword arguments (eg. ``description``) will be added verbatim to the field's schema
 
@@ -254,6 +261,42 @@ to set all the arguments above except ``default``.
 The schema is generated by default using aliases as keys, it can also be generated using model
 property names not aliases with ``MainModel.schema/schema_json(by_alias=False)``.
 
+Types, custom field types, and constraints (as ``max_length``) are mapped to the corresponding
+`JSON Schema Core <http://json-schema.org/latest/json-schema-core.html#rfc.section.4.3.1>`__ spec format when there's
+an equivalent available, next to `JSON Schema Validation <http://json-schema.org/latest/json-schema-validation.html>`__,
+`OpenAPI Data Types <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types>`__
+(which are based on JSON Schema), or otherwise use the standard ``format`` JSON field to define Pydantic extensions
+for more complex ``string`` sub-types.
+
+The field schema mapping from Python / Pydantic to JSON Schema is done as follows:
+
+.. include:: .tmp_schema_mappings.rst
+
+
+You can also generate a top-level JSON Schema that only includes a list of models and all their related
+submodules in its ``definitions``:
+
+.. literalinclude:: examples/schema2.py
+
+(This script is complete, it should run "as is")
+
+Outputs:
+
+.. literalinclude:: examples/schema2.json
+
+You can customize the generated ``$ref`` JSON location, the definitions will still be in the key ``definitions`` and you can still get them from there, but the references will point to your defined prefix instead of the default.
+
+This is useful if you need to extend or modify JSON Schema default definitions location, e.g. with OpenAPI:
+
+.. literalinclude:: examples/schema3.py
+
+(This script is complete, it should run "as is")
+
+Outputs:
+
+.. literalinclude:: examples/schema3.json
+
+
 Error Handling
 ..............