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

[handrews]

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.

[handrews]

See also:

• Callbacks runtime expressions in multipart bodies OpenAPI-Specification#2146

For some additional challenges regarding selectors and multipart formats.