OAI / OAI/Arazzo-Specification

Criterion Object: regex condition type does not specify a regular expression dialect

Open
#515 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
471
Forks
69
Avg merge
17h 58m
Merged PRs (30d)
19

Description

Summary

The Criterion Object's regex condition type does not specify which regular-expression dialect implementations must use, while the sibling jsonpath and xpath types both pin a standard. This leaves regex matching non-portable across Arazzo runners.

Details

In the Criterion Object (Arazzo 1.0.1 and 1.1.0), the type field allows simple, regex, jsonpath, or xpath. For two of these, the spec pins a standard:

  • jsonpath → RFC 9535 lineage (draft-goessner-dispatch-jsonpath-00), versioned via the Criterion Expression Type Object
  • xpath → XML Path Language 3.1, also versioned

But for regex, the spec says only: "regex - where a regex pattern is applied on the supplied context." No dialect is named (ECMA-262, I-Regexp/RFC 9485, PCRE, XSD, RE2, …), and regex has no entry in the Criterion Expression Type Object, so there is no way to declare which flavor is intended.

Why this matters

Regex dialects differ in ways that change matching results — lookbehind (?<=…), named groups, backreferences, Unicode property escapes \p{…}, and even the meaning of .. A condition such as condition: '(?<=x)y' or '\p{L}+' may pass on one runtime and fail (or error) on another. This is the same class of portability gap the JSONPath working group explicitly set out to solve.

Notably, the two specifications closest to Arazzo made different explicit choices:

  • OpenAPI (Arazzo's sibling under the OAI) pins ECMA-262 for pattern/patternProperties, inherited from JSON Schema Validation Draft 2020-12 §6.3.3 ("SHOULD be a valid regular expression, according to the ECMA-262 regular expression dialect"). OpenAPI also authors its own normative field constraints (e.g. Components key pattern ^[a-zA-Z0-9\.\-_]+$) in ECMA-262 syntax.
  • JSONPath (RFC 9535 — which Arazzo already references for its jsonpath type) pins I-Regexp (RFC 9485), an interoperability-focused subset of XSD regex, for its match()/search() functions.

So Arazzo currently references a spec (RFC 9535) that uses I-Regexp, while its sibling (OpenAPI) uses ECMA-262 — and Arazzo's own regex type commits to neither.

Proposed resolution

Specify a dialect for the regex type. Preferred: ECMA-262, matching OpenAPI/JSON Schema (the sibling specification, and what the most common runners implement via native regex engines). A single clarifying sentence in the regex description would suffice, e.g.: "The condition MUST be a valid regular expression according to the ECMA-262 regular expression dialect."

Alternatively, add a regex entry to the Criterion Expression Type Object with a version field (mirroring jsonpath/xpath) if multiple dialects should be selectable — though for regex a single pinned dialect is likely simpler and sufficient.

Affected versions

Arazzo 1.0.0, 1.0.1, and 1.1.0.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate the Criterion Object and Criterion Expression Type Object definitions in the specification, then read how the existing jsonpath and xpath types identify their standards. Confirm whether a single normative sentence or a versioned regex entry best fits the surrounding structure; done means the regex dialect is explicitly specified for the affected versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.