RFC 3987 Syntax Validation

1.1.0 verified Tue May 12 auth: no python install: verified quickstart: verified

rfc3987-syntax is a Python library (current version 1.1.0) that provides helper functions to syntactically validate strings according to the ABNF grammar defined in RFC 3987, which specifies Internationalized Resource Identifiers (IRIs). It is lightweight, permissively licensed (MIT), and leverages the Lark parsing library. The project strictly focuses on ABNF syntax validation, explicitly stating that additional semantic rules (like Unicode normalization or BiDi constraints) must be handled separately. With a relatively active release cadence, its latest major update (v1.1.0) introduced support for IRI-reference and absolute-IRI.

pip install rfc3987-syntax

Common errors

error ModuleNotFoundError: No module named 'rfc3987_syntax' ↓

cause The `rfc3987-syntax` library is either not installed in the environment or the import statement uses an incorrect module name (e.g., `rfc3987-syntax` instead of `rfc3987_syntax`).

fix

Install the library using pip install rfc3987-syntax and ensure your import statement is import rfc3987_syntax.

error AttributeError: module 'rfc3987_syntax' has no attribute 'validate_iri' ↓

cause The library does not provide a convenience `validate_iri` (or similar `validate_` prefixed) function; validation is implicitly performed by attempting to parse the input, which raises an exception on failure.

fix

Use rfc3987_syntax.parse_iri() (or other parse_ functions) within a try-except lark.exceptions.UnexpectedInput block to handle invalid input.

import rfc3987_syntax
from lark.exceptions import UnexpectedInput

try:
    rfc3987_syntax.parse_iri("http://example.com/path?query")
    print("IRI is valid")
except UnexpectedInput:
    print("IRI is invalid")

error lark.exceptions.UnexpectedInput: No rule matches the current input, or it is ambiguous. ↓

cause The provided string does not strictly conform to the ABNF grammar for the specified IRI/URI component as defined in RFC 3987.

fix

Review the input string to ensure it adheres precisely to RFC 3987 syntax rules, paying attention to valid characters, structure, and component delimiters for the specific parse_ function used.

error AttributeError: module 'rfc3987_syntax' has no attribute 'parse_iri_reference' ↓

cause The function `parse_iri_reference` (and `parse_absolute_iri`) was introduced in version 1.1.0, and an older version of the library is currently installed.

fix

Upgrade the rfc3987-syntax library to version 1.1.0 or newer using the command pip install --upgrade rfc3987-syntax.

Warnings

gotcha This library *only* performs syntactic validation of RFC 3987 based on ABNF grammar. It does not validate semantic rules such as Unicode Normalization Form C (NFC), Bidirectional text (BiDi) constraints, port number ranges (0-65535), valid IPv6 compression, or context-aware percent-encoding requirements. These must be enforced separately for full compliance. ↓

fix Implement additional logic for semantic validation as required by your application.

gotcha This `rfc3987-syntax` package is a distinct project and is *not* affiliated with the older, GPL-licensed `rfc3987` Python package by Daniel Gerber, which has a different scope. Ensure you are installing `rfc3987-syntax` to avoid licensing conflicts or unexpected API differences. ↓

fix Confirm the correct package name during installation: `pip install rfc3987-syntax`.

breaking Version 1.1.0 introduced explicit support for `IRI-reference` and `absolute-IRI` terms and fixed a bug related to single quote sub-delimiters. While primarily adding functionality, these changes *could* subtly alter validation results for certain inputs that were previously considered invalid or parsed differently in older versions. ↓

fix Review validation logic and expected outcomes when upgrading from versions prior to 1.1.0, especially for inputs involving IRI-references, absolute-IRIs, or single quotes within delimited components.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 4.03s 18.7M

3.10 alpine (musl) - - 5.51s 18.7M

3.10 slim (glibc) wheel 1.5s 2.76s 19M

3.10 slim (glibc) - - 2.81s 19M

3.11 alpine (musl) wheel - 5.09s 20.7M

3.11 alpine (musl) - - 6.20s 20.7M

3.11 slim (glibc) wheel 1.7s 4.78s 21M

3.11 slim (glibc) - - 4.60s 21M

3.12 alpine (musl) wheel - 4.60s 12.5M

3.12 alpine (musl) - - 5.93s 12.5M

3.12 slim (glibc) wheel 1.6s 5.32s 13M

3.12 slim (glibc) - - 5.35s 13M

3.13 alpine (musl) wheel - 4.44s 12.3M

3.13 alpine (musl) - - 5.24s 12.2M

3.13 slim (glibc) wheel 1.7s 4.88s 13M

3.13 slim (glibc) - - 5.36s 13M

3.9 alpine (musl) wheel - 4.19s 18.2M

3.9 alpine (musl) - - 5.04s 18.2M

3.9 slim (glibc) wheel 1.8s 3.46s 19M

3.9 slim (glibc) - - 4.19s 19M

Imports

is_valid_syntax

from rfc3987_syntax import is_valid_syntax

RFC3987_SYNTAX_TERMS

from rfc3987_syntax import RFC3987_SYNTAX_TERMS

Quickstart verified last tested: 2026-04-24

Demonstrates how to list supported validation terms and use the `is_valid_syntax` function to check if a string conforms to a specific RFC 3987 syntax rule, such as 'iri'.

from rfc3987_syntax import is_valid_syntax, RFC3987_SYNTAX_TERMS

# List all supported validation terms
print(f"Supported terms: {RFC3987_SYNTAX_TERMS}\n")

# Validate a string against a specific term
if is_valid_syntax(term='iri', value='http://example.com/path/to/resource?query=param#fragment'):
    print("✓ 'http://example.com/path/to/resource?query=param#fragment' is a valid IRI syntax")
else:
    print("✗ Invalid IRI syntax")

# Example of invalid syntax
if not is_valid_syntax(term='iri', value='not-an-iri-with- space'):
    print("✗ 'not-an-iri-with- space' is invalid IRI syntax as expected")