Spec progress

[gkellogg]

• Flesh out more conversion operations.
• Describe conversion relative to the YAML Representation Graph.
• Stub a definition of the YAML-LD JSON profile.
• Describe the YAML-LD extended profile.
• Stub updated descriptions to the JSOn-LD API

For #75.

---

Preview | Diff

[gkellogg]

Note that some references depend on broken ReSpec xrefs as discussed in https://github.com/w3c/respec/issues/4243.

Apologies for a dump of changes, as I expect my time to become more limited once the RCH and RDF-star working groups get underway.

PR is in progress, but early reviews and change requests to this PR are welcome.

[TallTed]

I actually LOLed at this typo --

Suggestions from @TallTed, who never tires in his errors to make technical specifications more readable.

[gkellogg]

I actually LOLed at this typo --

Suggestions from @TallTed, who never tires in his errors to make technical specifications more readable.

I blame aggressive auto-correct on my Mac. "endeavors" :)

[TallTed]

It's difficult to track the changes in the last commit, |var| changes vs much more potentially significant textual changes. If there are further markup changes that impact the whole doc, I'd appreciate it if those could be made distinctly from textual revision.

[gkellogg]

It's difficult to track the changes in the last commit, |var| changes vs much more potentially significant textual changes. If there are further markup changes that impact the whole doc, I'd appreciate it if those could be made distinctly from textual revision.

Well, this is a work in progress. Given the amount that's being touched, it's impractical to break it up into multiple PRs, which would all then need to be re-based against each other, and would significantly affect that amount of work that can be done.

Probably best to wait until the status changes from "work in progress". Still, it does touch a lot of the document, and I apologize for that. Changes for things like <var>x</var> to |x| impact the difficulty of making these changes, and most of the algorithmic text is introduced in the PR.

[TallTed]

I'm afraid that waiting until this already giant PR (GitHub won't tell me how many lines are touched, though I can easily see that ~550 lines have been added) becomes even bigger means "review the entire document" rather than "review the changes", and that's going to be a big time sink when we get there.

That said, I'm (generally) OK with large PRs (though smaller remain preferable). In this case, doing the |var| changes in one commit, and the other edits from de22b88 in another commit, would have been sufficient for me (and others, I imagine) to more carefully review the textual changes, and less carefully review the |var| changes.

None of which is to say, stop what you're doing. More to ask that maybe this omnibus PR be merged, and another (smaller, hopefully) omnibus begun, sooner than later.

I do understand the pain of addressing near-inevitable conflicts and rebasing PRs that have impacted one another. But it's better than building these docs in a wiki, as we used to do...

[gkellogg]

Again, apologies for touching so much of the document, but I think it is now useful for developers to start implementing something.

I've completed the work I intended for this PR.

[TallTed]

Minor stuff...

[TallTed]

Suggested change

	<a>Node tags</a> including an underscore (`"_"`),
	<a>Node tags</a> including an underscore ("`_`"),

[gkellogg]

I went back and forth on this. The JSON-LD specs use "_" instead of "_" for equivalent quoted characters (e.g., in https://www.w3.org/TR/json-ld11/#the-i18n-namespace) That may make it more readable, if not be as accurate. If we do make the change, it needs to be done comprehensively, so I'll leave this out of this batch.

[TallTed]

Fair enough. There may be some W3-ish style guide or examples that provides guidance, or others in the WG with opinions. I can live with the "_" style if there's general agreement that it's better, though it's not to my taste.

[gkellogg]

There were about four points in the document that use this style for "_", "#", and "%23". To my mind it's easier to see these as it exists easily, given how the spec styles code blocks.

[pchampin]

I sympathize with @TallTed's argument that discussing on big PRs is not ideal, so I am in favour of merging it, and then discussing more specific points, using more targetted PRs.

In particular, I am still uncomfortable with extending the internal representation, but this can be discussed later, on the basis of the changes proposed here.

[pchampin]

this should not be "for each RDF literal", but "for each namespace of datatype(s) used in RDF literals of the input RDF graph", although this phrasing is not very clear either.

Also: how are implementation chose the name of such tags?

[gkellogg]

this should not be "for each RDF literal", but "for each namespace of datatype(s) used in RDF literals of the input RDF graph", although this phrasing is not very clear either.

Well, in terms of iteration, it is for each "RDF literal" with the description of specifically looking at the "datatype IRIs" of those literals left unsaid.

Also: how are implementation chose the name of such tags?

As with most other RDF serialization formats, the choice of namespace prefix to use is up to a given implementation and not something that should be specified. It's perfectly legitimate to not use any %TAG prefixes and have the node tags be full IRIs. I don't think we can say more than this.

[pchampin]

Well, in terms of iteration, it is for each "RDF literal"

Ok, now that you explain it, I understand what you meant. It is however very easy to misread the current phrasing as "there should be 1 TAG declaration per RDF literal". Furthermore...

It's perfectly legitimate to not use any %TAG prefixes and have the node tags be full IRIs.

agreed, and that's why a SHOULD seems to strong for me.

I don't think we can say more than this.

I think we should even say less 😉 i.e. and replace the SHOULD by a MAY. E.g. replacing the end of the sentence with "and MAY use %TAG directives to make the serialization of some RDF literals more concise."

[gkellogg]

I updated language and added an example in 53837c8. See if that helps.

[pchampin]

I reallyy don't see the benefit of losing information at this stage, while the (standard) internal representation is capable of representing RDF literals through value objects...

[gkellogg]

My concern was for round-tripping: how do you distinguish from something specified using a value object (or through context coercion) from something expressed natively? How would you know to express a value object using node tags? Easiest to not do that at all, and allow direct representation within the (expanded) internal representation. At least, this was the conclusion I came to when thinking about it over time.

Being able to represent more native values in the internal representation (also potentially IRIs and blank nodes) better supports the greater expressivity of alternative formats such as YAML and CBOR. And, it's largely transparent to the JSON-LD processing algorithms, other than the to/from RDF bits, so it seems a natural solution.

This was discussed in #17 (comment) on #17, and should be the topic of further discussion.

[gkellogg]

Another problem is that the serialization phase comes after compaction and framing, so trying to interpret what nodes represent value objects and are eligible for being serialized using node tags could require recursively processing the internal definition of the graph as it is done in expansion in order to identify which keys represent @value, @type, and @language, so the process of finding those, and replacing them with a scalar with node tag becomes much more difficult.

Consider the following:

{
  "@context": {
    "@vocab": "http://example.org/",
    "prop": {
      "@context": {
        "xsd": "http://www.w3.org/2001/XMLSchema#",
        "val": "@value",
        "dt": "@type"
      }
    }
  },
  "prop": {
    "val": "2022-08-27",
    "dt": "xsd:date"
  }
}

The use of an expanded internal representation retains the nature of the literal values so that they are more easily resolved into scalars with node tags.

Of course, when serialized to JSON, or using the YAML-LD JSON schema, these get flattened. The text in this PR simply turns them into strings (or numbers of boolean), but we could decide to turn them into value objects as well, which is also a reasonable direction. At that point, re-compacting might be necessary to get an expression suiting the in-scope context.

[TallTed]

Just a couple of minor tweaks above...

[gkellogg]

This was discussed on today's meeting. Not ready to merge yet.

@niklasl suggested an alternative to using RDF literals as part of an extended internal representation would be to simply use YAML node tags on scalars to encode value objects. This could only really work where value objects (containing @value and @type or @language, but not other tags). For example:

{
  "property": {
    "@value": "2022-08-31",
    "@type": "http://www.w3.org/2001/XMLSchema#date"
  }
}

could be serialized as:

---
property: !<http://www.w3.org/2001/XMLSchema%23date>  "2022-08-31"

If we allow some examination of the context, we could also probably handle:

{
  "@context": {
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "property": {
    "@value": "2022-08-31",
    "@type": "xsd:date"
  }
}

That could be considered as an alternative to the suggested algorithms for Converting a YAML scalar (still requiring some extendedYAML flag) and Converting From the Internal Representation, which would use node-tags on scalars for value objects with the extendedYAML flag, and potentially look at the top-level context for terms used in @type IRIs.

[ioggstream]

@gkellogg I suggest to collect all these notes under "interoperability consideration", so that implementers can find them all in the same place.

[ioggstream]

@gkellogg I suggest to say that:

1. ld+yaml can contain multiple documents even in the basic profile;
2. they should be processed in isolation. For further details see https://github.com/ietf-wg-httpapi/mediatypes/blob/main/draft-ietf-httpapi-yaml-mediatypes.md#yaml-streams-int-yaml-streams

This is because aggregating multiple docs in a single stream is a common practice and a useful native YAML feature addressed by editors and libraries.

[gkellogg]

I'm not sure what the implications for the API would be, as it doesn't really provide for separate documents.

I think this is something we come back to later.

[ioggstream]

@gkellogg positive feelings provided that the comments are addressed.

On YAML -> Internal representation processing I just trust you, but I think that we will have time for tuning after releasing of a draft version.

[gkellogg]

Discussed at today's Face to Face and resolved to merge.

Resolution: https://json-ld.org/minutes/2022-09-12/#resolution-1