+yaml fragment parsing compatibility

[ioggstream]

Discussion

Currently +yaml SSF delegates fragment identification to the specific media type registrations (e.g. application/openapi+yaml)

IMHO this is the correct approach because we do not want to limit the ability to define fragment identifier for subtypes which already exists but are not registered.

I know that other xxx+json subtypes took a different approach, and they reference the JSON fragment identifier instead. I think that this is not the case for YAML because:

• JSON does not define a fragment identifier, so xxx+json registrars did not have a way to compare JSON behavior with their desired behavior.
• YAML will be registered with its fragment identifier, so xxx+yaml registrars that want to use it can just reference it explicitly.

The most we can do is xxx+yaml SHOULD explain why they are not using the application/yaml fragment identifier

WDYT cc: @cabo @eemeli

[cabo]

The whole idea of an SSS is being able to make use of the base media type if the specific media type is not known. So I don't think that a specific media type design that would assign a different meaning to /...+*...+ would be the right thing to do (BTW, the empty fragment identifier is missing in your list). But they can use the space deliberately left free here, and I would recommend being specific that a=b is the recommended option for that.

[handrews]

I agree with @cabo .

[EDIT: RFC quote removed b/c I misread it. I thought it said SSS MUST use the base media type's fragment identifier, but it says that specific SSS's MUST use the fragment identifiers registered in the suffix's registration, which I gather are not required to include the base media type fragment identifiers for some reason]

And yes, this:

A fragment identifier starting with "/" is to be interpreted as a JSON Pointer {{JSON-POINTER}}

needs to be changed to include the empty string "" as a JSON Pointer.

[eemeli]

I don't think we ought to have such a SHOULD statement, unless the intent with it is to make it clear that a subtype MAY choose to follow the application/yaml fragment handling.

As for how to handle an empty string fragment, is that somehow different for JSON pointers from how a URL without a fragment identifier is handled, or is it the same?

[handrews]

@eemeli empty strings are not a special case, they're normal JSON Pointers (they are included in the RFC examples for both string representation and URI fragment representation.)

An empty string JSON Pointer fragment refers to the entire document, so it is semantically equivalent to not having a fragment.

This means that JSON Pointer fragments are compatible with other fragments that also use the empty string to reference the whole document (and do not otherwise overlap with JSON Pointer syntax). But not with a hypothetical syntax where a document author could assign the empty fragment to some subset of the resource (I'm not aware of any such syntax, but AFAIK there's nothing in RFC3986 that requires the empty fragment to reference the entire resource, and that conversion is not a standard part of URL normalization).

[ioggstream]

To clarify:

• application/yaml defines a way to process fragments. Theoretically an empty fragment foo.yaml# is not considered as a json pointer, but an empty YAML fragment. Practically, it points to the root of the YAML document, so it has "accidentally" the same semantics of a JSON Pointer.

@handrews

And yes, this:

A fragment identifier starting with "/" is to be interpreted as a JSON Pointer {{JSON-POINTER}}
needs to be changed to include the empty string "" as a JSON Pointer.

How application/yaml processes fragment is outside the topic of this issue and needs to be agreed with the YAML community.
IMHO the current solution fits all needs:

• mimics JSON Pointer behavior for empty fragments (is the terminology here correct @cabo?) ;
• prefixed alias nodes with * to avoid conflicts with schema+yaml plain names.

IIUC @cabo proposes that for interoperability application/yaml fragid MUST be applied to all xxx+yaml media types (did I got it right?).

While I think that it would be cool, I am afraid that it could conflict with some xxx+yaml candidate. Some examples:

• if we had ignored that schema+json already defined plain names, such a requirement would have blocked schema+yaml users to rely on plain names;
• schema+yaml should support *alias-node fragments;
• if tomorrow application/yaml support $.json.path fragments (that is a possibility), schema+yaml implementations should support it.

With the current layout, xxx+yaml have more freedom, and application/yaml is free to evolve without breaking existing implementations.

My 2¢, R.

[handrews]

@ioggstream OK let me see if I understand this: application/yaml does NOT support RFC 6901 JSON Pointer fragments, it just supports a syntax that coincidentally mostly looks and behaves like it? That feels confusing, is the rationale for this documented somewhere?

[ioggstream]

@handrews the history:

1. application/yaml fragid is a plain name representing a named anchor
2. to support json pointer and named anchor we decided that:
   • if it starts with / is a json pointer
   • otherwise is a plain name referencing a named anchor
3. to avoid conflicts with oas plain names we decided that
   • if it starts with / is a json pointer
   • if it starts with * is an alias nodes
   • plain names are not supported
   • if it's empty, it points to the root document.

Honestly I think this process was all in the interest of preserving subtypes :)

[cabo]

• if it's empty, it points to the root document.

I think it is worth pointing out that this is also needed for full RFC 6901 JSON pointer support.

[handrews]

@ioggstream I just don't understand why the empty string and starting with "/" are separate cases. As @cabo notes, both are equally part of RFC 6901.

I also don't understand how treating these two parts of RFC 6901 as separate cases, one of which references RFC 6901 and the other of which is defined completely outside of it but happens to align, preserves subtypes. I am assuming that by subtypes you mean further +yaml formats?

[ioggstream]

Since JSON Pointer is a different document, we needed to isolate the impacts of changes in JSON Pointer on YAML fragments.

The current behaviour is acceptable because it is the same for JSON Pointer and alias nodes.
Incidentally, it's the only sensible behaviour independently of RFC 6901.

But we want to be clear that only fragments starting with / are "delegated" to an external spec. If RFC6901 changes, it will only affect fragments starting with /.

About xxx+yaml ( I called them "subtypes" but dunno if that's correct) , the original proposal from YAML community was to only support YAML plain names. In this case, the empty fragment would have still referenced the root node. But a xxx+yaml media type using plain names would have conflicted with application/yaml.

Hth :)
R

[ioggstream]

I think this whole story is worth an FAQ... Thanks for the opportunity to write it down! @handrews

[jdesrosiers]

3. to avoid conflicts with oas plain names we decided that

• if it starts with / is a json pointer
• if it starts with * is an alias nodes
• plain names are not supported
• if it's empty, it points to the root document.

I might be missing something here. I don't think this would be compatible with JSON Schema. If YAML requires that alias nodes start with *, then anyone writing a JSON Schema in YAML would have to define their $anchors with a * prefix, but JSON Schema doesn't allow the * character in anchors. So, there is no way to use alias nodes.

Or is the point that plain-names are left undefined and a media type like application/json-schema+yaml could define them?

[handrews]

@jdesrosiers this:

Or is the point that plain-names are left undefined and a media type like application/json-schema+yaml could define them?

But see also PR #54

[ioggstream]

@jdesrosiers

If YAML requires that alias nodes start with *,
then anyone writing a JSON Schema in YAML would have to define their $anchors with a * prefix

You are not required to reference nodes using alias nodes fragid.
If somebody does externally from json-schema (e.g. a browser), an implementation is expected to resolve it.
A YAML client library, for example could support it.

Or is the point that plain-names are left undefined and a media type like application/json-schema+yaml could define them?

If +yaml and yaml fragments are disentangled, schema+yaml is free to define its plain names. Otherwise there might be future clashes.

In this work, I am trying to balance the views of the YAML, API/Schema and Linked Data communities.

I think that the YAML community should have the lead for defining the application/yaml fragment, since they will evolve the language and the implementations in the next years. This document should build on their work without limiting them.
YAML is so huge respect to the API world, for example is used in configuration files, CI/CD setup, and for kubernetes/openstack deployment files... So I think that YAML plain names should be decided by YAML folks now or in the future.

About xxx+yaml fragids:

• schema+yaml needs its own plain name
• ld+yaml (W3C) needs to be interoperable with the use of fragments in RDF/Lined Data world (that could mean no fragment or plain names, we haven't discuss that yet)
• and we have not engaged with other communities yet

About application/yaml and +yaml fragments, Media Type RFC states that:

• application/yaml and +yaml can have different fragids
• if +yaml has a fragid, all xxx+yaml MUST support that fragid

[jdesrosiers]

@ioggstream I realized that the *-prefix notation relates to a specific YAML feature, not just any named location such like could be defined by a JSON Schema $anchor keyword. Therefore, there is no conflict with JSON Schema, but does technically require a new media type for "schema+yaml" to be defined that recognizes plain name fragments.

[ioggstream]

Yes, schema+yaml should add plain name fragments according to JSON Schema

[ioggstream]

Closed according to the discussion during IETF-114. SSS does not mandate having the same base media type fragid.