Add/update some info on why format works the way it does.

Closes: #653

2 files changed, 68 insertions, 0 deletions

diff --git a/docs/faq.rst b/docs/faq.rst
index 4e1d244..e4fba6a 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -3,6 +3,72 @@ Frequently Asked Questions
 ==========================
 
 
+My schema specifies format validation. Why do invalid instances seem valid?
+---------------------------------------------------------------------------
+
+The :validator:`format` validator can be a bit of a stumbling block for new
+users working with JSON Schema.
+
+In a schema such as:
+
+.. code-block:: json
+
+    {"type": "string", "format": "date"}
+
+JSON Schema specifications have historically differentiated between the
+:validator:`format` validator and other validators. In particular, the
+:validator:`format` validator was specified to be *informational* as much
+as it may be used for validation.
+
+In other words, for many use cases, schema authors may wish to use
+values for the :validator:`format` validator but have no expectation
+they be validated alongside other required assertions in a schema.
+
+Of course this does not represent all or even most use cases -- many
+schema authors *do* wish to assert that instances conform fully, even to
+the specific format mentioned.
+
+In drafts prior to ``draft2019-09``, the decision on whether to
+automatically enable :validator:`format` validation was left up to
+validation implementations such as this one.
+
+This library made the choice to leave it off by default, for two reasons:
+
+    * for forward compatibility and implementation complexity reasons
+      -- if :validator:`format` validation were on by default, and a
+      future draft of JSON Schema introduced a hard-to-implement format,
+      either the implementation of that format would block releases of
+      this library until it were implemented, or the behavior surrounding
+      :validator:`format` would need to be even more complex than simply
+      defaulting to be on. It therefore was safer to start with it off,
+      and defend against the expectation that a given format would always
+      automatically work.
+
+    * given that a common use of JSON Schema is for portability across
+      languages (and therefore implementations of JSON Schema), so that
+      users be aware of this point itself regarding :validator:`format`
+      validation, and therefore remember to check any *other*
+      implementations they were using to ensure they too were explicitly
+      enabled for :validator:`format` validation.
+
+As of ``draft2019-09`` however, the opt-out by default behavior
+mentioned here is now *required* for all validators.
+
+Difficult as this may sound for new users, at this point it at least
+means they should expect the same behavior that has always been
+implemented here, across any other implementation they encounter.
+
+.. seealso::
+
+    `validating formats`
+
+        for details on how to enable format validation
+
+    `FormatChecker`
+
+        the object which implements format validation
+
+
 Why doesn't my schema's default property set the default on my instance?
 ------------------------------------------------------------------------
 
diff --git a/docs/validate.rst b/docs/validate.rst
index 8b15962..1b4b75e 100644
--- a/docs/validate.rst
+++ b/docs/validate.rst
@@ -264,6 +264,8 @@ Draft 6 meta-schema, you could use:
     Draft6Validator.check_schema(schema)
 
 
+.. _validating formats:
+
 Validating Formats
 ------------------