Use tags to distinguish "plain" YAML-LD from "idiomatic" YAML-LD

[pchampin]

By "plain" YAML-LD, I mean "YAML-LD documents that can be interpreted as Linked Data by simply converting them to JSON, then processing them with a standard JSON-LD processor.

By "idiomatic" YAML-LD, I mean "YAML-LD documents that are easier to author, but require some specific processing steps to be interpreted as Linked Data". An example of such additional processing step would be the conversion of $-keywords into standard @-keywords (as discuseed in #3).

Tags are a feature of YAML that has no correspondance in JSON, so their presence mechanically requires additional processing. I suggest that

• YAML-LD documents are considered "plain" if they don't use any local tag (beyond the standard tags used to specify JSON types, of course);
• we define some tag(s) to signal "idiomatic" YAML-LD.

The first proposal I made in that direction is too much error prone. However, I think the general design principle deserves to be explored further.

[pchampin]

A concrete proposal in that direction would be to use a tag at the top-level of any "idiomatic" YAML-LD document, applying to the whole object/array that makes the document. E.g.

!yaml-ld
$context: http://schema.org/
$type: Person
name: Pierre-Antoine Champin

I consider that the extra effort to put the tag is low enough.

[ioggstream]

1. Why should we replace "@" with "$" ?

2. not sure the doc above is correct YAML

[pchampin]

@ioggstream

1. Why should we replace "@" with "$" ?

because @-keywords need to be in quotes, while $-keywords don't → easier to manually author

2. not sure the doc above is correct YAML

I successfully parsed it with ruamel.yaml.

[ioggstream]

because @-keywords need to be in quotes

I think quoting is less problematic than changing parsers :) For example, the following document is both a valid YAML and JSON

{ "$context": "http://foo" }

Processing it differently depending on the media type or the file extension is not very interoperable.

[anatoly-scherbakov]

I am uncertain whether it is beneficial to have two dialects of the same language which might potentially diverge, wreak havoc and feed misunderstanding. However, let us assume we would want that.

If we would agree that the @ → $ replacement is beneficial, then how would you characterize the particular use case where we would like to avoid such a conversion? In particular, what kind of use case is there for a non-idiomatic YAML-LD document which is a plain conversion of a JSON-LD document to YAML?

Which of the two use cases (with conversion versus without conversion) would we see in practice more often?

I feel we might want to keep the most prevalent use case as is and perhaps specially mark the use cases which are not used as often. Thus we would reduce the typing burden and the syntactic noise.

I have added some thoughts about this in #11.

[pchampin]

@anatoly-scherbakov

how would you characterize the particular use case where we would like to avoid such a conversion?

I don't want to avoid it, but I want to ensure that @-keywords are still recognized. I created a UC to explain why: #12.

I am uncertain whether it is beneficial to have two dialects of the same language which might potentially diverge, wreak havoc and feed misunderstanding.

I totally sympathize with this fear, and that's precisely why I defend @-keywords! Let me explain.

A subset of YAML can be seen as sharing the same data model as JSON, therefore both can be seen as "two dialects of the same language" (this is my rationale in #12, by the way). For all YAML-LD document that fall into that subset, I therefore think it much better to ensure that they behave the same as the equivalent JSON-LD document.

YAML-LD document using features that are not supported by JSON give us room for extensibility (in particular, improving the user-experience of authoring YAML-LD from scratch). Tags are such a feature, hence the proposal in this issue.

[anatoly-scherbakov]

Perhaps the introduction of a special $-aware context would resolve this once and for all — and with JSON-LD own means. Except for @context perhaps... but I wouldn't see that as a tragedy.