Specification grammar catalog¶
Classes live in their owning extension's Grammar namespace, for example
Vanderlee\Comprehend\Extensions\Json\Grammar\Rfc8259. Instantiate a class and call
freeze()->parse($input) for its default root. Use rule('name') to import a
component or ref('name') when a low-level Parser is required. Names use
underscores; constructors accept named override maps. These grammars use the
existing recognition session, source spans, CST/AST and explicit commit behavior.
This catalog implements the current specifications from the proposed high, medium and small RFC additions. Historical predecessors are documented as RFC relationships, rather than supplied as aliases with potentially different syntax.
| Class | Default root | Other useful imports and coverage |
|---|---|---|
Rfc5322 |
mailbox |
Modern email address syntax: addr_spec, address, address_list, mailbox_list, group, comment, cfws, quoted_string, msg_id. Also lexical fields/message and individual from, sender, to, subject headers. Obsolete Section 4 forms are not included. |
Rfc6854 |
mailbox |
Updates from and sender to permit group addresses. |
Rfc6532 |
mailbox |
Extends email address/header lexical components with validated UTF-8 scalars. |
Rfc5321 |
mailbox |
SMTP envelope addresses, path, reverse_path, forward_path, command, mail, rcpt, helo, ehlo, reply and reply_line. Header comments and folding are not envelope address syntax. |
Rfc6531 |
mailbox |
SMTPUTF8 local parts and domain labels. IDNA conversion and extension negotiation are separate. |
Rfc3339 |
date_time |
full_date, full_time, partial_time, time_offset, and their components. Gregorian dates are checked, including year zero. Leap-second spelling is accepted without consulting historical announcements. |
Rfc9557 |
date_time_ext |
Time-zone and calendar annotations. Time-zone lookup, offset consistency and critical-annotation handling require application logic. |
Rfc8259 |
json_text |
value, object, array, member, string, number, ws. Duplicate members and number spelling are preserved. String syntax allows escaped unpaired surrogates as in the RFC ABNF; interoperability validation and decoding are separate. |
Rfc6901 |
json_pointer |
reference_token, array_index, uri_fragment; fragment decoding is checked against pointer syntax. Resolving a pointer against a document is separate. |
Rfc9535 |
jsonpath_query |
Segments, selectors, slices, filters and standard functions' argument/result categories. Does not execute queries. Extension functions require application-defined type information. |
Rfc9651 |
sf_list |
sf_item, sf_dictionary, inner_list, parameters, scalar types. Numeric limits and display-string UTF-8 are checked. Duplicate-key interpretation and value construction are separate. |
Rfc1035 |
domain_name |
Escaped DNS text labels, zone_record, zone_file, character_string, ttl, class, type. Known single-line A/AAAA, name, MX, SOA and TXT records have typed data; folded/unknown records retain generic data atoms. Includes $ORIGIN, $INCLUDE syntax and the later $TTL directive. Never reads included files or wire packets. |
Rfc1034 |
domain_name |
Uses companion RFC 1035's text rules. Does not implement DNS resolution algorithms. |
Rfc1123 |
hostname |
ASCII hostname label and total-length limits. Distinct from unrestricted DNS presentation labels. |
Rfc9989 |
dmarc_record |
Extensible DMARC tag syntax, dmarc_request, alignment/PSD values and reporting_uri. Mandatory tags, duplicate-tag policy and DNS discovery are separate validation/evaluation. |
Rfc9990 |
aggregate_report |
XML syntax, feedback root/namespace and ordered top-level sections; report_filename. Full XSD validation, report semantics and compression are not included. |
Rfc9991 |
id_align |
The RFC's new Identity-Alignment field: alignment_value, dmarc_method, identity_alignment_header, auth_failure. The enclosing ARF report is not implemented. |
Rfc2045 |
content_type |
MIME token, parameter, value, mime_version, transfer-encoding names and lexical quoted-printable/Base64 bodies. Does not decode bodies or enforce every MIME line-length constraint. |
Rfc2046 |
content_type |
boundary, multipart_body($boundary). Recognizes multipart framing with the supplied boundary; recursively interpreting part headers/bodies is separate. |
Rfc6376 |
tag_list |
DKIM tag lists, signature, key_record, signature_header. Rejects duplicate tag names. Required-tag/value constraints, algorithms and signature verification are separate. |
Rfc3987 |
IRI |
Extends URI rules with ucschar, iprivate and irelative_ref. URI mapping, normalization and IDNA conversion are separate. |
Rfc6570 |
uri_template |
All four template levels: expression, varspec, varname, pct_encoded. Does not expand variables. |
Rfc8141 |
urn |
nid, nss, resolution/query components and fragments. Namespace registration and namespace-specific semantics are separate. |
Rfc9562 |
uuid |
uuid_urn. Generic UUID spelling, including Nil/Max bit patterns. Does not generate identifiers or validate version-specific meaning. |
Rfc4648 |
base64 |
base16, base32, base32hex, base64url, explicit unpadded Base64 variants. Canonical zero pad bits are checked; no whitespace is inserted or ignored. |
Rfc5646 |
language_tag |
Language/script/region/variant/extension/private-use and grandfathered tag syntax. Duplicate variants and extension singletons are rejected; registry membership and canonicalization are separate. |
SemVer |
version |
SemVer 2.0.0 numeric, prerelease and build identifiers. Does not parse Composer/npm dependency ranges or compare versions. |
Xml |
document |
XML 1.0 Fifth Edition document, element, attribute, reference, comment, CDATA, PI and internal DTD declaration syntax. Checks matching tags, unique attributes, legal characters, document-type root and undeclared entity names where no external subset is present. UTF-8 input only; no external resource loading, entity expansion, DTD validation or namespace processing. |
Yaml |
stream |
YAML 1.2.2 streams, directives, block/flow collections, explicit keys, anchors, aliases, tags and scalar styles. Preserves spelling and indentation; does not resolve scalar types, construct tagged values, bind aliases or compare mapping keys. |
Every RFC class links to its RFC text in the class PHPDoc. Where an update or replacement is present in the library, the PHPDoc also links to that class. Non-RFC classes link to a versioned official specification.
Recognition and interpretation¶
These assets provide composable syntax rules, not network clients or complete protocol implementations. A successful parse establishes the documented grammar coverage. It does not establish mail deliverability, DNS existence, cryptographic validity, XML schema validity, registry membership or successful query evaluation.
Rfc5322::message retains lexical headers and body text; header cardinality and
required fields are not checked by that lexical rule. Import the individual typed
header rules when their value syntax matters. Rfc6854 changes those typed
originator rules without silently changing Rfc5322.
XML parsing never loads external entities or DTDs. YAML parsing never instantiates objects from tags or expands aliases. This keeps recognition pure. Consumers can attach cached semantic projections/validators and explicit commit effects through the normal API.
YAML's indentation parser delegates flow expressions to the typed parser graph,
retains source-bound children, and enters nested blocks through ParseSession.
Depth/work limits therefore apply to block nesting as well as ordinary grammar
recursion. Inputs and output spans remain byte based in both source modes.
Verification¶
SpecificationsTest.php covers accepted/rejected examples in byte and UTF-8
sources. SpecificationLifecycleTest.php covers overrides, frozen snapshots,
nonzero byte offsets, parsing limits, explicit effects and MIME boundaries.
UpstreamSpecificationsTest.php adds acceptance fixtures from:
- YAML Test Suite: 402 inputs, including variant cases.
- HTTP Working Group structured-field tests: 1598 inputs.
- JSONPath compliance suite: 715 selectors, including standard-function typing.
The fixture provenance and licenses pin upstream revisions. These checks cover syntax acceptance and source round trips; they do not test value construction, serialization or query execution. Passing these finite corpora is not a claim of exhaustive specification conformance.
Run php docs/examples/specifications.php for checked imports across the catalog.