1 files changed, 91 insertions, 0 deletions
diff --git a/docs/creating.rst b/docs/creating.rst
new file mode 100644
index 0000000..6c42162
--- /dev/null
+++ b/docs/creating.rst
@@ -0,0 +1,91 @@
+.. _creating-validators:
+
+================================
+Creating or Extending Validators
+================================
+
+.. currentmodule:: jsonschema.validators
+
+.. autofunction:: create
+
+    Create a new validator.
+
+    :argument dict meta_schema: the meta schema for the new validator
+
+    :argument dict validators: a mapping from validator names to functions that
+        validate the given name. Each function should take 4 arguments: a
+        validator instance, the value of the current validator property in the
+        instance being validated, the instance, and the schema.
+
+    :argument str version: an identifier for the version that this validator
+        will validate. If provided, the returned validator class will have its
+        ``__name__`` set to include the version, and also will have
+        :func:`validates` automatically called for the given version.
+
+    :argument dict default_types: a default mapping to use for instances of the
+        validator when mapping between JSON types to Python types. The default
+        for this argument is probably fine. Instances of the returned validator
+        can still have their types customized on a per-instance basis.
+
+    :returns: an :class:`jsonschema.IValidator`
+
+
+.. autofunction:: extend
+
+    Create a new validator that extends an existing validator.
+
+    :argument jsonschema.IValidator validator: an existing validator
+
+    :argument dict validators: a set of new validators to add to the new
+        validator.
+
+        .. note::
+
+            Any validators with the same name as an existing one will
+            (silently) replace the old validator entirely.
+
+            If you wish to extend an old validator, call it directly in the
+            replacing validator function by retrieving it using
+            ``OldValidator.VALIDATORS["the validator"]``.
+
+    :argument str version: a version for the new validator
+
+    :returns: an :class:`jsonschema.IValidator`
+
+    .. note:: Meta Schemas
+
+        The new validator will just keep the old validator's meta schema.
+
+        If you wish to change or extend the meta schema in the new validator,
+        modify ``META_SCHEMA`` directly on the returned class.
+
+        The meta schema on the new validator will not be a copy, so you'll
+        probably want to copy it before modifying it to not affect the old
+        validator.
+
+
+.. autofunction:: validator_for
+
+    Retrieve the validator appropriate for validating the given schema.
+
+    Uses the :validator:`$schema` property that should be present in the given
+    schema to look up the appropriate validator.
+
+    :argument schema: the schema to look at
+    :argument default: the default to return if the appropriate validator
+        cannot be determined. If unprovided, the default will be to just return
+        :class:`Draft4Validator`
+
+
+.. autofunction:: validates
+
+
+Creating Validation Errors
+--------------------------
+
+Any validating function that validates against a subschema should call
+:meth:`ValidatorMixin.descend`, rather than :meth:`ValidatorMixin.iter_errors`.
+If it recurses into the instance, or schema, it should pass one or both of the
+``path`` or ``schema_path`` arguments to :meth:`ValidatorMixin.descend` in
+order to properly maintain where in the instance or schema respsectively the
+error occurred.