Skip to content

feat: opt-in validation modes for the parser - #634

Draft
jeswr wants to merge 3 commits into
rdfjs:mainfrom
jeswr:feat/parser-validation-modes
Draft

feat: opt-in validation modes for the parser#634
jeswr wants to merge 3 commits into
rdfjs:mainfrom
jeswr:feat/parser-validation-modes

Conversation

@jeswr

@jeswr jeswr commented Jul 2, 2026

Copy link
Copy Markdown
Member

Adds an opt-in validate option to N3.Parser, as requested in #622 (comment). Refs #622.

Design: the option covers the validation dimensions that format does not already gate.

  • validate: { terms: true } — well-formedness of the terms the grammar produces: IRIs must be absolute and match RFC 3987's IRI rule (rejecting unresolved relative IRIs, <http://example.org/%ZZ>, …), language tags must be well-formed per BCP 47, literal values of xsd:boolean|integer|decimal|double|float|date|time|dateTime must be in their lexical space, blank-node labels must match the BLANK_NODE_LABEL production (astral-aware), and base directions must be ltr/rtl. Lexical checks only — no registry lookups, no value-space rules — implemented internally (src/Validation.js) to keep N3.js dependency-free. (Blank-node labels and base direction were folded in from Validate blank-node labels and literal base directions in opt-in parser validation (#634) #666/M4+M5 in 004d9b3.)
  • validate: { version: true } — profile enforcement composed with the existing version option: version: '1.1' rejects triple terms, reified triples, annotation syntax, directional language tags, and version declarations; version: '1.2-basic' rejects triple terms and their sugar (per RDF 1.2 Concepts, Basic excludes only triple terms).
  • validate: true enables both.

Deliberately not covered: RDF/JS interface conformance (the parser constructs terms through its factory, so that check would only re-test the factory — it belongs at the factory boundary); N3 validity (already what format: 'text/n3' does); shape-level validation (separate layer, noted in the #622 docs).

Zero cost when off: with validate absent the parser runs identical code — validation is installed as per-instance method overrides in the constructor, so no check was added to the default read path. Measured within noise of main (a control build with the checks stripped was no faster). Validation on is ~40 % slower on a 200 k-triple parse, dominated by the RFC 3987 regex. The only default-path additions are two guards on rare paths that also fix a latent crash: _completeSubjectLiteral previously dereferenced the result of _completeLiteral without the undefined check its object-position counterpart has.

Reviewer notes on the 004d9b3 additions: (1) in N3 mode only the written token.value of a blank-node label is checked (N3 deliberately scopes dot-prefixed internal labels), so a malformed blankNodePrefix is not caught in N3 format specifically — pinned by a regression test; (2) the direction check is defense-in-depth (the built-in lexer only emits ltr/rtl; it bites only for a custom options.lexer); (3) direction validity is enforced in all versions under validate.terms; version-gating of directional tags stays with validate.version.

Full suite green — 6666 tests, 100 % coverage.

cc @jeswr — design-discussion draft; the option shape (validate: true / { terms, version }) and the datatype list are the parts most worth debating.

Closes #666

jeswr and others added 2 commits July 2, 2026 19:56
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ons (rdfjs#666)

Extend `validate: { terms: true }` with the two remaining term dimensions:
- blank node labels are checked against the `BLANK_NODE_LABEL` rule
  (including labels formed with the `blankNodePrefix` option;
  in N3, only the label as written, as scope prefixes use a dot by design)
- the base direction of directional language-tagged strings
  must be `ltr` or `rtl`

Both checks are installed as per-instance overrides in the constructor,
keeping the default (validation-off) read path untouched.
This completes the term dimensions of the opt-in `validate` option.

Refs rdfjs#666

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@jeswr

jeswr commented Jul 6, 2026

Copy link
Copy Markdown
Member Author

Folded the two remaining term dimensions from #666 (M4 blank-node labels, M5 base direction) into validate: { terms: true } in 004d9b3; details and the three reviewer notes now live in the PR description. Suite green — 6666 tests, 100 % coverage. (Prepared with Claude; I'll review before it progresses.)

@jeswr jeswr added ai-generated Authored or prepared by an AI coding agent needs-author-review Awaiting author review; agent has done its part (author removes if follow-ups remain) labels Jul 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-generated Authored or prepared by an AI coding agent needs-author-review Awaiting author review; agent has done its part (author removes if follow-ups remain)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Validate blank-node labels and literal base directions in opt-in parser validation (#634)

1 participant