rfc3987-syntax

Helper functions to parse and validate the syntax of terms defined in RFC 3987 — the IETF standard for Internationalized Resource Identifiers (IRIs).

🎯 Purpose

The goal of rfc3987-syntax is to provide a lightweight, permissively licensed Python module for validating that strings conform to the ABNF grammar defined in RFC 3987. These helpers are:

✅ Strictly aligned with the syntax rules of RFC 3987
✅ Built using a permissive MIT license
✅ Designed for both open source and proprietary use
✅ Powered by Lark, a fast, EBNF-based parser

🧠 Note: This project focuses on syntax validation only. RFC 3987 specifies additional semantic rules (e.g., Unicode normalization, BiDi constraints, percent-encoding requirements) that must be enforced separately.

📄 License, Attribution, and Citation

rfc3987-syntax is licensed under the MIT License, which allows reuse in both open source and commercial software.

This project:

❌ Does not depend on the rfc3987 Python package (GPL-licensed)
✅ Uses lark, licensed under MIT
✅ Implements grammar from RFC 3987, using RFC 3986 where RFC 3987 delegates syntax

⚠️ This project is not affiliated with or endorsed by the authors of RFC 3987 or the rfc3987 Python package.

Please cite this software in accordance with the enclosed CITATION.cff file.

⚠️ Limitations

The grammar and parser enforce only the ABNF syntax defined in RFC 3987. The following are not validated and must be handled separately for full compliance:

✅ Unicode Normalization Form C (NFC)
✅ Bidirectional text (BiDi) constraints (RFC 3987 §4.1)
✅ Port number ranges (must be 0–65535)
✅ Valid IPv6 compression (only one ::, max segments)
✅ Context-aware percent-encoding requirements

ChatGPT 40 was used during the original development process. Errors may exist due to this assistance. Additional review, testing, and bug fixes by human experts is welcome.

📦 Installation

pip install rfc3987-syntax

🛠 Usage

List all supported "terms" (i.e., non-terminals and terminals within ABNF production rules) used to validate the syntax of an IRI according to RFC 3987

from rfc3987_syntax import RFC3987_SYNTAX_TERMS

print("Supported terms:")
for term in RFC3987_SYNTAX_TERMS:
    print(term)

Syntactically validate a string using the general-purpose validator

from rfc3987_syntax import is_valid_syntax

if is_valid_syntax(term='iri', value='http://github.com'):
    print("✓ Valid IRI syntax")

if not is_valid_syntax(term='iri', value='bob'):
    print("✗ Invalid IRI syntax")

if not is_valid_syntax(term='iri_reference', value='bob'):
    print("✓ Valid IRI-reference syntax")

Alternatively, use term-specific helpers to validate RFC 3987 syntax.

from rfc3987_syntax import is_valid_syntax_iri
from rfc3987_syntax import is_valid_syntax_iri_reference

if is_valid_syntax_iri('http://github.com'):
    print("✓ Valid IRI syntax")

if not is_valid_syntax_iri('bob'):
    print("✗ Invalid IRI syntax")
    
if is_valid_syntax_iri_reference('bob'):
    print("✓ Valid IRI-reference syntax")

Get the Lark parse tree for a syntax validation (useful for additional semantic validation)

from rfc3987_syntax import parse

ptree: ParseTree = parse(term="iri", value="http://github.com")

print(ptree)

📚 Sources

This grammar was derived from:

[RFC 3987 – Internationalized Resource Identifiers (IRIs)]
→ Defines IRI syntax and extensions to URI (e.g. Unicode characters, ucschar)
→ https://datatracker.ietf.org/doc/html/rfc3987
[RFC 3986 – Uniform Resource Identifier (URI): Generic Syntax)]
→ Provides reusable components like scheme, authority, ipv4address, etc.
→ https://datatracker.ietf.org/doc/html/rfc3986

📝 When RFC 3986 is listed as the source, it is used in accordance with RFC 3987, which explicitly references it for foundational elements.

Rule-to-Source Mapping

Rule/Component	Source	Notes
`iri`	RFC 3987	Top-level IRI rule
`iri_reference`	RFC 3987	Top-level IRI Reference rule
`absolute_iri`	RFC 3987	Top-level Absolute IRI rule
`scheme`	RFC 3986	Referenced by RFC 3987 §2.2
`ihier_part`	RFC 3987	IRI-specific hierarchy
`irelative_ref`	RFC 3987	IRI-specific relative ref
`irelative_part`	RFC 3987	IRI-specific relative part
`iauthority`	RFC 3986	Standard URI authority
`ipath_abempty`	RFC 3986	Path format variant
`ipath_absolute`	RFC 3986	Absolute path
`ipath_noscheme`	RFC 3986	Path disallowing scheme prefix
`ipath_rootless`	RFC 3986	Used in non-scheme contexts
`iquery`	RFC 3987	Query extension to URI
`ifragment`	RFC 3987	Fragment extension to URI
`ipchar`, `isegment`	RFC 3986	Path characters and segments
`isegment_nz_nc`	RFC 3987	IRI-specific path constraint
`iunreserved`	RFC 3987	Includes `ucschar`
`ucschar`, `iprivate`	RFC 3987	Unicode support
`sub_delims`	RFC 3986	Reserved characters
`ip_literal`	RFC 3986	IPv6 or IPvFuture in `[]`
`ipv6address`	RFC 3986	Expanded forms only
`ipvfuture`	RFC 3986	Forward-compatible
`ipv4address`	RFC 3986	Dotted-decimal IPv4
`ls32`	RFC 3986	Final 32 bits of IPv6
`h16`, `dec_octet`	RFC 3986	Hex and decimal chunks
`port`	RFC 3986	Optional numeric
`pct_encoded`	RFC 3986	Percent encoding (e.g. `%20`)
`alpha`, `digit`, `hexdig`	RFC 3986	Character classes

Dependencies of rfc3987-syntax (2).
Dependency	Optional
lark	false
pytest	true

Package profile

rfc3987-syntax

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description