YAML Fragment as alias nodes. #41

[ioggstream]

This PR

Arose from discussing with @cabo and @eemeli and supports different fragment identifiers:

• [x] YAML alias nodes starting with *
• [x] JSON Pointers starting with /
• [x] empty fragment identifiers
• [x] JSON pointers can only point to data that is reachable on a path through string-keyed maps and arrays.
• [x] YAML document tree resolution

This mechanism should be easily extensible to jsonpath (which according to the current I-D must start with a $).

[ioggstream]

@cabo WDYT of this text?

[eemeli]

Is there existing prior art using / as a fragment identifier prefix for JSON pointers? I'm a bit concerned that this might be an application/yaml specific thing, rather than common practice.

[ioggstream]

@eemeli iiuc JSON Pointers must start with /.

   The ABNF syntax of a JSON Pointer is:

      json-pointer    = *( "/" reference-token )

pinging @mnot for a check

[cabo]

@eemeli iiuc JSON Pointers must start with /.

... or be empty (* is 0 or more). I think you should make up your mind about empty fragment identifiers and possibly define them as a synonym for an empty JSON pointer (i.e., root value of the JSON tree). See also Section 6 of RFC 6901 , the actual fragment identifier representation.

All non-empty JSON pointers indeed start with a /. So you don't need to add a marker; just pass any fragment identifier starting with a / to the JSON pointer machinery.

The semantics of JSON pointers as defined in Section 4 of RFC 6901 unsurprisingly do not discuss YAML data that are not JSON data. I would simply leave it at that -- JSON pointers can only point to data that is reachable on a path through string-keyed maps and arrays.

We use JSON pointers in SDF. Nobody considered this to be an innovation of any kind, so I'd expect the perception that they are widespread as fragment identifiers to be widespread.

[ioggstream]

About empty fragment identifiers

Are they used in the wild is association with yaml (e.g. in OpenAPI?) cc: @dret could you make a brief investigation on that?

Since the empty `` fragment identifier in JSON Pointer references the whole document, this seems a reasonable general behavior for any document that represent structured data so we could define that separately.

About using JSON-* fragment identifiers with YAML

JSON pointers can only point to data that is reachable on a path through string-keyed maps and arrays.

This needs to be addressed better.

Notes

@cabo @eemeli do you think there's interest for an extension of JSONPath/JSONPointer to better cover the YAML specifications? Sincerely I don't know how to do it, but since there's some interest in the YAML world for defining pathlike alias nodes, maybe a discussion could be useful.

[dret]

On 2022-05-26 12:25, Roberto Polli wrote:

Are they used in the wild is association with yaml (e.g. in OpenAPI?) cc: @dret https://github.com/dret could you make a brief investigation on that?

not sure i can help here. but we could ask @pautasso about this because they have a very rich dataset of OpenAPI files that they can probably use for questions like this.

[ioggstream]

not sure i can help here. but we could ask to... [one of the fantastic friends of Erik]

That's exactly what I meant :P Let's wait for feedback.

[jdesrosiers]

Are they used in the wild is association with yaml (e.g. in OpenAPI?)

Empty fragment identifiers are used in JSON Schema for recursive references. For example, this schema modeling a family tree.

type: object,
properties:
  name: 
    type: string
  children:
    $ref: '#'
required:
  - name

[ioggstream]

@jdesrosiers in this case it is a "full" JSON Pointer, right? Should it resolve to openapi.yaml# or is it processed directly on the parsed JSON document?

[jdesrosiers]

@ioggstream If this schema we part of an OpenAPI document, then yes, the reference would resolve to root of the document. So, in an OpenAPI document, an empty fragment reference never makes sense. You would only do this in a JSON Schema document, which are often written in YAML. In OpenAPI, it would look like this,

components:
  schemas:
    Person:
      type: object,
      properties:
        name: 
          type: string
        children:
          $ref: '#/components/Person'
      required:
        - name

[handrews]

@ioggstream

in this case it is a "full" JSON Pointer, right? Should it resolve to openapi.yaml# or is it processed directly on the parsed JSON document?

Both "" (the empty string) and "/" (a single forward slash) are normal JSON Pointers and fully usable in fragments the same way as any other JSON Pointer.

@eemeli

Is there existing prior art using / as a fragment identifier prefix for JSON pointers? I'm a bit concerned that this might be an application/yaml specific thing, rather than common practice.

JSON Schema has done this since the beginning. A fragment that is empty or starts with a '/' is parsed as a JSON Pointer fragment per RFC 6901. Any other fragment is parsed as a plain name fragment, which (as we follow that linked document's recommendations and use the NCName syntax) cannot start with a /.

[cabo]

On 9. Jun 2022, at 00:29, Henry Andrews @.***> wrote:

Both "" (the empty string) and "/" (a single forward slash) are normal JSON Pointers and fully usable in fragments the same way as any other JSON Pointer.

Yes. And for those who haven’t read RFC 6901 yet, it may be worth to point out that “/“ points to the member in the root JSON object with the name (map key) “”, see https://www.rfc-editor.org/rfc/rfc6901#page-5 for an example.

Grüße, Carsten