Repository: cwacek/python-jsonschema-objects

Issue:
Request: example for multiple top-level objects in a schema
The readme suggests that multiple objects can be extracted from a schema by `ObjectBuilder.build_classes`, however it's really not clear to me how one can define multiple objects within a single schema in a way where this would work. Can you please give an example of how you see this working?

For example, given a schema that (somehow) contains the definition of two top-level objects, the expectation might be that the result of `ObjectBuilder(schema).build_classes()` is a namespace with classes for both objects. Does this require combination of schemas with the `anyOf` directive?

Or is the intention that there would be a separate schema for each object, and therefore `ObjectBuilder(schema).build_classes()` would need to be called within a loop over all schemas?

Example:

```
schema = {
    "id": "My Schema",
    "properties": {
        "ErrorResponse": {
            "title": "Error Response",
            "type": "object",
            "properties": {
                "message": {"type": "string"},
                "status": {"type": "integer"},
            },
            "required": ["message", "status"],
        },
        "VersionGetResponse": {
            "title": "Version Get Response",
            "type": "object",
            "properties": {
                "local": {"type": "boolean"},
                "version": {"type": "string"},
            },
            "required": ["version"],
        }
    }
}

print(dir(pjs.ObjectBuilder(schema).build_classes()))
# Out: ['ErrorResponse<anonymous>', 'Local', 'Message', 'Status', 'MySchema', 'Version', 'VersionGetResponse<anonymous>']
```
In this case, the two useful classes have `<anonymous>` suffixes which makes them difficult (but not impossible) to use.

Discussion:

Patch:
diff --git a/python_jsonschema_objects/examples/README.md b/python_jsonschema_objects/examples/README.md
index 2136079..700c7b6 100644
--- a/python_jsonschema_objects/examples/README.md
+++ b/python_jsonschema_objects/examples/README.md
@@ -174,6 +174,60 @@ schemas are unique.
 }
 ```
 
+## Generating Multiple Top Level Objects
+
+Sometimes what you really want to do is define a couple
+of different objects in a schema, and then be able to use
+them flexibly.
+
+Any object built as a reference can be obtained from the top
+level namespace. Thus, to obtain multiple top level classes,
+define them separately in a definitions structure, then simply
+make the top level schema refer to each of them as a `oneOf`.
+
+The schema and code example below show how this works.
+
+``` schema
+{
+    "title": "MultipleObjects",
+    "id": "foo",
+    "type": "object",
+    "oneOf":[
+            {"$ref": "#/definitions/ErrorResponse"},
+            {"$ref": "#/definitions/VersionGetResponse"}
+            ],
+    "definitions": {
+        "ErrorResponse": {
+            "title": "Error Response",
+            "id": "Error Response",
+            "type": "object",
+            "properties": {
+                "message": {"type": "string"},
+                "status": {"type": "integer"}
+            },
+            "required": ["message", "status"]
+        },
+        "VersionGetResponse": {
+            "title": "Version Get Response",
+            "type": "object",
+            "properties": {
+                "local": {"type": "boolean"},
+                "version": {"type": "string"}
+            },
+            "required": ["version"]
+        }
+    }
+}
+```
+
+``` python
+>>> builder = pjs.ObjectBuilder('multiple_objects.json')
+>>> classes = builder.build_classes()
+>>> print(dir(classes))
+[u'ErrorResponse', 'Local', 'Message', u'Multipleobjects',
+'Status', 'Version', u'VersionGetResponse']
+```
+
 ## Installation
 
     pip install python_jsonschema_objects


Test patch:
diff --git a/test/test_pytest.py b/test/test_pytest.py
index 867b63f..4e52b6f 100644
--- a/test/test_pytest.py
+++ b/test/test_pytest.py
@@ -64,9 +64,8 @@ def test_build_classes_is_idempotent():
         }
     }
     builder = pjs.ObjectBuilder(schema)
+    x = builder.build_classes()
     builder.build_classes()
-    builder.build_classes()
-
 
 
 def test_underscore_properties():
diff --git a/test/test_regression_87.py b/test/test_regression_87.py
new file mode 100644
index 0000000..523b62f
--- /dev/null
+++ b/test/test_regression_87.py
@@ -0,0 +1,15 @@
+import pytest
+
+import python_jsonschema_objects as pjs
+
+
+def test_multiple_objects_are_defined(markdown_examples):
+    builder = pjs.ObjectBuilder(
+        markdown_examples['MultipleObjects'],
+        resolved=markdown_examples)
+
+    assert builder
+    classes = builder.build_classes()
+    assert 'ErrorResponse' in classes
+    assert 'VersionGetResponse' in classes
+    print(dir(classes))