feat: EmailOptions for configuring email format validation

Signed-off-by: Dmitry Dygalo <[email protected]>

Author: Stranger6667

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- `EmailOptions` for configuring `email` format validation. [#903](https://github.com/Stranger6667/jsonschema/pull/903)
+
 ### Fixed
 
 - `multipleOf` validation for large u64 values beyond `i64::MAX` with `arbitrary-precision` feature.

crates/jsonschema-py/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- `EmailOptions` for configuring `email` format validation.
+
 ### Fixed
 
 - `multipleOf` validation for large integers beyond `i64::MAX`.

crates/jsonschema-py/README.md

@@ -405,6 +405,48 @@ The available options:
 
 This configuration is crucial when working with untrusted schemas where attackers might craft malicious regex patterns.
 
+## Email Format Configuration
+
+When validating email addresses using `{"format": "email"}`, you can customize the validation behavior beyond the default JSON Schema spec requirements:
+
+```python
+import jsonschema_rs
+from jsonschema_rs import EmailOptions
+
+# Require a top-level domain (reject "user@localhost")
+validator = jsonschema_rs.validator_for(
+    {"format": "email", "type": "string"},
+    validate_formats=True,
+    email_options=EmailOptions(require_tld=True)
+)
+validator.is_valid("user@localhost")     # False
+validator.is_valid("[email protected]")   # True
+
+# Disallow IP address literals and display names
+validator = jsonschema_rs.validator_for(
+    {"format": "email", "type": "string"},
+    validate_formats=True,
+    email_options=EmailOptions(
+        allow_domain_literal=False,  # Reject "user@[127.0.0.1]"
+        allow_display_text=False     # Reject "Name <[email protected]>"
+    )
+)
+
+# Require minimum domain segments
+validator = jsonschema_rs.validator_for(
+    {"format": "email", "type": "string"},
+    validate_formats=True,
+    email_options=EmailOptions(minimum_sub_domains=3)  # e.g., [email protected]
+)
+```
+
+Available options:
+
+  - `require_tld`: Require a top-level domain (e.g., reject "user@localhost")
+  - `allow_domain_literal`: Allow IP address literals like "user@[127.0.0.1]" (default: True)
+  - `allow_display_text`: Allow display names like "Name <[email protected]>" (default: True)
+  - `minimum_sub_domains`: Minimum number of domain segments required
+
 ## External References
 
 By default, `jsonschema-rs` resolves HTTP references and file references from the local file system. You can implement a custom retriever to handle external references. Here's an example that uses a static map of schemas:

crates/jsonschema-py/python/jsonschema_rs/__init__.py

@@ -11,6 +11,7 @@
     Draft201909Validator,
     Draft202012,
     Draft202012Validator,
+    EmailOptions,
     Evaluation,
     FancyRegexOptions,
     RegexOptions,
@@ -121,6 +122,7 @@ def __hash__(self) -> int:
     "Draft202012Validator",
     "Validator",
     "Registry",
+    "EmailOptions",
     "FancyRegexOptions",
     "RegexOptions",
     "meta",

crates/jsonschema-py/python/jsonschema_rs/__init__.pyi

@@ -61,6 +61,18 @@ class RegexOptions:
     def __init__(self, size_limit: int | None = None, dfa_size_limit: int | None = None) -> None: ...
     def __repr__(self) -> str: ...
 
+class EmailOptions:
+    """Configuration for email format validation."""
+
+    def __init__(
+        self,
+        require_tld: bool = False,
+        allow_domain_literal: bool = True,
+        allow_display_text: bool = True,
+        minimum_sub_domains: int | None = None,
+    ) -> None: ...
+    def __repr__(self) -> str: ...
+
 PatternOptionsType = Union[FancyRegexOptions, RegexOptions]
 
 class RetrieverProtocol(Protocol):
@@ -79,6 +91,7 @@ def is_valid(
     mask: str | None = None,
     base_uri: str | None = None,
     pattern_options: PatternOptionsType | None = None,
+    email_options: EmailOptions | None = None,
 ) -> bool:
     """Check if a JSON instance is valid against a schema.
 
@@ -99,6 +112,7 @@ def validate(
     mask: str | None = None,
     base_uri: str | None = None,
     pattern_options: PatternOptionsType | None = None,
+    email_options: EmailOptions | None = None,
 ) -> None:
     """Validate a JSON instance against a schema.
 
@@ -119,6 +133,7 @@ def iter_errors(
     mask: str | None = None,
     base_uri: str | None = None,
     pattern_options: PatternOptionsType | None = None,
+    email_options: EmailOptions | None = None,
 ) -> Iterator[ValidationError]:
     """Iterate over all validation errors.
 
@@ -137,6 +152,7 @@ def evaluate(
     registry: Registry | None = None,
     base_uri: str | None = None,
     pattern_options: PatternOptionsType | None = None,
+    email_options: EmailOptions | None = None,
 ) -> Evaluation:
     """Evaluate an instance and return structured output.
 
@@ -276,6 +292,7 @@ class Draft4Validator:
         mask: str | None = None,
         base_uri: str | None = None,
         pattern_options: PatternOptionsType | None = None,
+        email_options: EmailOptions | None = None,
     ) -> None: ...
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
@@ -295,6 +312,7 @@ class Draft6Validator:
         mask: str | None = None,
         base_uri: str | None = None,
         pattern_options: PatternOptionsType | None = None,
+        email_options: EmailOptions | None = None,
     ) -> None: ...
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
@@ -314,6 +332,7 @@ class Draft7Validator:
         mask: str | None = None,
         base_uri: str | None = None,
         pattern_options: PatternOptionsType | None = None,
+        email_options: EmailOptions | None = None,
     ) -> None: ...
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
@@ -333,6 +352,7 @@ class Draft201909Validator:
         mask: str | None = None,
         base_uri: str | None = None,
         pattern_options: PatternOptionsType | None = None,
+        email_options: EmailOptions | None = None,
     ) -> None: ...
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
@@ -352,6 +372,7 @@ class Draft202012Validator:
         mask: str | None = None,
         base_uri: str | None = None,
         pattern_options: PatternOptionsType | None = None,
+        email_options: EmailOptions | None = None,
     ) -> None: ...
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
@@ -371,6 +392,7 @@ def validator_for(
     mask: str | None = None,
     base_uri: str | None = None,
     pattern_options: PatternOptionsType | None = None,
+    email_options: EmailOptions | None = None,
 ) -> Validator:
     """Create a validator for the given schema.
 

crates/jsonschema-py/src/email.rs

@@ -0,0 +1,51 @@
+use pyo3::prelude::*;
+
+/// EmailOptions(require_tld=False, allow_domain_literal=True, allow_display_text=True, minimum_sub_domains=None)
+///
+/// Configuration for email format validation.
+///
+/// This allows customization of email format validation behavior beyond the default
+/// JSON Schema spec requirements.
+///
+///     >>> from jsonschema_rs import validator_for, EmailOptions
+///     >>> validator = validator_for(
+///     ...     {"format": "email", "type": "string"},
+///     ...     validate_formats=True,
+///     ...     email_options=EmailOptions(require_tld=True)
+///     ... )
+///     >>> validator.is_valid("user@localhost")
+///     False
+///     >>> validator.is_valid("[email protected]")
+///     True
+///
+/// Parameters:
+///     require_tld: Require a top-level domain (e.g., reject "user@localhost")
+///     allow_domain_literal: Allow IP address literals like "user@[127.0.0.1]"
+///     allow_display_text: Allow display names like "Name <[email protected]>"
+///     minimum_sub_domains: Minimum number of domain segments required
+#[pyclass(module = "jsonschema_rs")]
+pub(crate) struct EmailOptions {
+    pub(crate) require_tld: bool,
+    pub(crate) allow_domain_literal: bool,
+    pub(crate) allow_display_text: bool,
+    pub(crate) minimum_sub_domains: Option<usize>,
+}
+
+#[pymethods]
+impl EmailOptions {
+    #[new]
+    #[pyo3(signature = (require_tld=false, allow_domain_literal=true, allow_display_text=true, minimum_sub_domains=None))]
+    fn new(
+        require_tld: bool,
+        allow_domain_literal: bool,
+        allow_display_text: bool,
+        minimum_sub_domains: Option<usize>,
+    ) -> Self {
+        Self {
+            require_tld,
+            allow_domain_literal,
+            allow_display_text,
+            minimum_sub_domains,
+        }
+    }
+}