Add details about updated memory management scheme to README

README.md

@@ -68,6 +68,46 @@ Validate a document:
 
 Note that Valijson's `SchemaParser` and `Validator` classes expect you to pass in a `RapidJsonAdapter` rather than a `rapidjson::Document`. This is due to the fact that `SchemaParser` and `Validator` are template classes that can be used with any of the JSON parsers supported by Valijson.
 
+## Memory Management ##
+
+Valijson has been designed to safely manage, and eventually free, the memory that is allocated while parsing a schema or validating a document. When working with an externally loaded schema (i.e. one that is populated using the `SchemaParser` class) you can rely on RAII semantics.
+
+Things get more interesting when you build a schema using custom code, as illustrated in the following snippet. This code demonstrates how you would create a schema to verify that the value of a 'description' property (if present) is always a string:
+
+    {
+        // Root schema object that manages memory allocated for
+        // constraints or sub-schemas
+        Schema schema;
+
+        // Allocating memory for a sub-schema returns a const pointer
+        // which allows inspection but not mutation. This memory will be
+        // freed only when the root schema goes out of scope
+        const Subschema *subschema = schema.createSubschema();
+
+        {   // Limited scope, for example purposes
+
+            // Construct a constraint on the stack
+            TypeConstraint typeConstraint;
+            typeConstraint.addNamedType(TypeConstraint::kString);
+
+            // Constraints are added to a sub-schema via the root schema,
+            // which will make a copy of the constraint
+            schema.addConstraintToSubschema(typeConstraint, subschema);
+
+            // Constraint on the stack goes out of scope, but the copy
+            // held by the root schema continues to exist
+        }
+
+        // Include subschema in properties constraint
+        PropertiesConstraint propertiesConstraint;
+        propertiesConstraint.addPropertySubschema("description", subschema);
+
+        // Add the properties constraint
+        schema.addConstraint(propertiesConstraint);
+
+        // Root schema goes out of scope and all allocated memory is freed
+    }
+
 ## Test Suite ##
 
 Valijson's' test suite currently contains several hand-crafted tests and uses the standard [JSON Schema Test Suite](https://github.com/json-schema/JSON-Schema-Test-Suite) to test support for parts of the JSON Schema feature set that have been implemented.