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 https://github.com/json-ld/yaml-ld/pull/78/commits/de22b886af378f1478f04f762f3e7d16eef01834 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.

[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.

[gkellogg]

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

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