OAI / OAI/Arazzo-Specification

Selectors (JSON Pointer, JSONPath, Runtime Expressions) should operate on the data model, not on serialized data

Open
#458 1 comment 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

In OAS 3.2, we greatly clarified and emphasized the distinction between several forms of data. The most relevant are the data model form, which is used with Schema Objects and other validation pieces like the required field on Parameter Objects, and the serialized form which is what goes over the wire in the HTTP message.

Arazzo should clarify that anything that is trying to address bits of data works with the data model. This cleanly separates different concerns:

  • Because the data model is, by definition, JSON-compatible, JSON-based technologies like JSON Path and JSON Pointer work in an unambiguous way
  • Mappings between various serialization formats and data models are managed through registries. We currently have such a registry for media types, and will likely add one for HTTP headers (currently a source of data modeling frustration) while working on 3.3.

This keeps all of our specs aligned in terms of how they function, and avoids having to make context-specific decisions on how to handle different media types or headers. The registry approach means that this could be expanded to other data modeling problems as they come up, without changing how selectors are used.

The one drawback to this is that serialization cannot be selected, so any information in the serialization format that cannot be captured in the JSON data model (string, number, boolean, null, object, array; note that integer is not distinct in JSON) is lost. But given the range of serialization concerns across different formats, accommodating them all would be infeasible anyway.

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

Start by reviewing the Arazzo selector definitions and how JSON Pointer, JSONPath, and Runtime Expressions are currently described. Done means the specification explicitly states that selectors operate on the JSON-compatible data model rather than serialized data, including the stated serialization limitation.

Written by the indexing model from the issue text.

Assessment

Domain
backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.