The model's locations use their own dot-path syntax: paths.*.*.requestBody.content.*.schema.maxLength, with * standing in for a name the API author chooses and x-* matching specification extensions by prefix.
JSONPath (RFC 9535) is the strongest candidate for alignment: the OpenAPI Overlay Specification uses it for its targets, Spectral rules address documents with it, and most locations map directly ($.paths.*.*.requestBody.content.*.schema.maxLength).
Three known frictions:
- Name-prefix matching:
x-* matches key names by prefix; RFC 9535 has no member-name glob, only filter expressions.
- Model vs. instance: locations address the OpenAPI object model, not a document instance. The
schema segment covers the schema and its sub-schemas at any depth; JSONPath's descendant segment (..) is close but the exact per-keyword semantics need care.
- Actions are not addressable: the
:action suffix of a claim has no JSONPath counterpart either way; alignment concerns only the location half.
Options, not mutually exclusive:
- Keep the native syntax as normative and additionally emit a
jsonpath rendering per claim where the mapping is exact, leaving it absent where it is not.
- Adopt JSONPath as the normative syntax and define this model's two extensions (name-prefix matching, model-level schema coverage) on top.
- Keep the native syntax and publish the mapping rules as prose.
Input welcome, especially from anyone consuming Overlay or Spectral targets who would benefit from one syntax across tools.
The model's locations use their own dot-path syntax:
paths.*.*.requestBody.content.*.schema.maxLength, with*standing in for a name the API author chooses andx-*matching specification extensions by prefix.JSONPath (RFC 9535) is the strongest candidate for alignment: the OpenAPI Overlay Specification uses it for its targets, Spectral rules address documents with it, and most locations map directly (
$.paths.*.*.requestBody.content.*.schema.maxLength).Three known frictions:
x-*matches key names by prefix; RFC 9535 has no member-name glob, only filter expressions.schemasegment covers the schema and its sub-schemas at any depth; JSONPath's descendant segment (..) is close but the exact per-keyword semantics need care.:actionsuffix of a claim has no JSONPath counterpart either way; alignment concerns only the location half.Options, not mutually exclusive:
jsonpathrendering per claim where the mapping is exact, leaving it absent where it is not.Input welcome, especially from anyone consuming Overlay or Spectral targets who would benefit from one syntax across tools.