Add a few examples of jsonschema.validators.validator_for.

1 files changed, 37 insertions, 0 deletions

diff --git a/jsonschema/validators.py b/jsonschema/validators.py
index 66e803e..116f2a6 100644
--- a/jsonschema/validators.py
+++ b/jsonschema/validators.py
@@ -1141,6 +1141,43 @@ def validator_for(schema, default=_UNSET):
 
             If unprovided, the default is to return the latest supported
             draft.
+
+    Examples:
+
+        The :kw:`$schema` JSON Schema keyword will control which validator
+        class is returned:
+
+        >>> schema = {
+        ...     "$schema": "https://json-schema.org/draft/2020-12/schema",
+        ...     "type": "integer",
+        ... }
+        >>> jsonschema.validators.validator_for(schema)
+        <class 'jsonschema.validators.Draft202012Validator'>
+
+
+        Here, a draft 7 schema instead will return the draft 7 validator:
+
+        >>> schema = {
+        ...     "$schema": "http://json-schema.org/draft-07/schema#",
+        ...     "type": "integer",
+        ... }
+        >>> jsonschema.validators.validator_for(schema)
+        <class 'jsonschema.validators.Draft7Validator'>
+
+
+        Schemas with no ``$schema`` keyword will fallback to the default
+        argument:
+
+        >>> schema = {"type": "integer"}
+        >>> jsonschema.validators.validator_for(
+        ...     schema, default=Draft7Validator,
+        ... )
+        <class 'jsonschema.validators.Draft7Validator'>
+
+        or if none is provided, to the latest version supported.
+        Always including the keyword when authoring schemas is highly
+        recommended.
+
     """
 
     DefaultValidator = _LATEST_VERSION if default is _UNSET else default