Definition of yaml-ld namespace documents #77

gkellogg · 2022-08-20T22:00:16Z

… and updates to the spec to…refer and use it.

… refer and use it. For #55. For #13.

gkellogg · 2022-08-20T22:01:56Z

This adds some framing keywords to the previous version discussed in the Best Practice section, and uses a versioned URI based on the yaml-ld namespace. It also defines the namespace documents (html and jsonld).

Once committed, will need @pchampin's aid in putting the files in place along with appropriate .htaccess for content negotiation.

pchampin

LGTM, modulo a typo

README.md

ns/v1.haml

spec/index.html

ioggstream

I do not advise publishing a context which is specific to YAML. Moreover, this overloads the dollar sign, too...

See the rest of the document for further comments.

ioggstream · 2022-08-22T15:47:44Z

spec/index.html

@@ -515,20 +515,99 @@ <h2>Basic Concepts</h2>
    </p>

    <p class="ednote">FIXME.</p>
+
+    <section class="informative" id="convenience-context">
+      <h3>Convenience Context</h3>


@ioggstream — It's unclear what you're saying you don't like. Please elaborate.

Since using a context to provide keyword alternates seemed to be a group consensus (I could be wrong, of course), this seems to be the natural consequence of that decision.

In #11, @anatoly-scherbakov laid out a plan for broad replacement of @-keywords with $-keywords, which would require deeper changes to document loading or core algorithms, and is still fraught with unexpected consequences. I outlined this solution in #11 (comment).

@juusoautiosalo suggested in #11 (comment) to chose a character other than $, and if there is consensus over some specific character, we can of course update this PR to use that, instead.

Of course, the ongoing need to quote "@context" is not solved by this solution, but seems to be a reasonable tradeoff for using an already standard mechanism for aliasing keywords.

On a previous call we'd discussed a "convenience context" but my understanding was that we would simply be providing a context which removed the @ symbol...not "blessing" a new symbol with magic meaning... Also, given that JSON Schema uses the $ prefix heavily, attempting to us that runs us into a namespace collision with them (of sorts) and won't make us any friends.

I could support providing a simple context file that aliases things without the @ prefix (i.e. "base": "@base), but developers will have to be aware (as ever) of what that means for the rest of their document/contents.

ioggstream · 2022-08-22T15:51:07Z

spec/index.html

+
+      <p>The <a>convenience context</a> contains an alias to every JSON-LD keyword which the JSON-LD 1.1
+        specification permits aliasing &mdash; which means all the keywords except <code>@context</code>. The reserved `@` character is
+        replaced by `$`, which is not reserved and therefore does not require quoting. Consider


Another sign that this convenience context does not belong here: @context with @, other keywords with $ and then more words and caveats.

As I argued elsewhere, a heavier-weight mechanism for alternative keywords can usher in unintended consequences; the keyword aliasing mechanism provided already by contexts is the right solution, IMHO.

If the group can't reach consensus, we can simply document the issue and leave it for a future working group to address and provide no alternative to @-keywords.

ioggstream · 2022-08-22T15:52:44Z

spec/index.html

+      '@context':
+      - http://example.org/context.jsonld
+      - https://www.w3.org/ns/yaml-ld/v1
+      $graph:


Does this mean that if I'm offline I cannot even use a JSON-LD processor to understand that $graph is a @graph ?

There is text elsewhere (4.5 Pre-loaded Contexts) that this should be built into the documentLoader, so it is always available. It's a SHOULD, but perhaps should be a MUST.

Note that, this is the default documentLoader, which can still be updated when invoking the API and it would be up to those implementations to continue to pre-load the context.

this should be built into the documentLoader, so it is always available

This documentLoader is specific to YAML-LD or applies to JSON-LD too?

In the JSON- LD API, it is described here: https://www.w3.org/TR/json-ld11-api/#remote-document-and-context-retrieval. The option to set it is documentLoader. It is the general way that documents are retrieved and interpreted.

ioggstream · 2022-08-22T15:55:14Z

spec/index.html

@@ -661,6 +739,18 @@ <h2>Streams</h2>
    <p class="ednote">
      This is inconsistent with the processing description in <a href="#convert-stream" class="sectionRef"></a>.
    </p>
+    </section>
+
+  <section id="pre-loaded-contexts">


Are those considerations specific to YAML? If not, I'd put there in another document. If yes, I think we are making things more complex than they should.

There is general advice in the JSON-LD Best Practices document about caching contexts, and this falls under that guidance. This spec more strongly suggests that this particular context be implemented in the document loader. We can't update the core JSON-LD API spec for this right now.

If placed in a separate document (also non-normative, at this point), we'd need to add language here that implementations MUST adhere to those requirements, and we can't go back in time to require that JSON-LD processors adhere to the same requirements.

We can't update the core JSON-LD API spec for this right now.

Can't we schedule an update of that document (or just update the draft version, if any?)

This spec more strongly suggests that this particular context be implemented in the document loader

So we need this only to support the convenience context?

Issues surrounding accessing remote context continues to be a hot topic in JSON-LD (driven by schema.org) and should have a fair amount of discussion at TPAC, probably in the later portion of our F2F time.

@TallTed

More updates from @TallTed. Co-authored-by: Ted Thibodeau Jr <[email protected]>

gkellogg · 2022-08-22T17:23:23Z

I do not advise publishing a context which is specific to YAML.

The context is in the YAML-LD namespace, but of course, it could be used with any JSON-LD processor. Is there a more appropriate namespace to publish this? We did discuss https://json-ld.org/contexts/, but that does not have the same guarantees of permanent availability as the W3C namespace. Note that Verifiable Credientials (which is a Working Group, and the rules are different) uses a dated URL https://www.w3.org/2018/credentials/v1.

Moreover, this overloads the dollar sign, too...

??? It does not overload the dollar sign, just defines terms that begin with the dollar sign. This seemed to be the group consensus, other than some use of non-ascii characters instead.

If there's still controversy on using the $keywords, we'll hold of merging and discuss on the next call.

See the rest of the document for further comments.

TallTed · 2022-08-22T17:34:56Z

[@gkellogg] We did discuss https://json-ld.org/contexts/, but that does not have the same guarantees of permanent availability as the W3C namespace

https://json-ld.org/contexts/ could potentially be used as the "actual" home of the documents, with w3id.org holding the permalinks through whatever aliases make sense, as the latter can be re-redirected if the "actual" home needs to change for whatever reason ...

…allTed

…allTed.

spec/index.html

ioggstream · 2022-08-23T14:06:30Z

I do not advise publishing a context which is specific to YAML.
The context is in the YAML-LD namespace,

I just meant that I expected YAML-LD to be interchangeable with JSON-LD without the need of bearing specific knowledge around.

If there's still controversy on using the $keywords, we'll hold of merging and discuss on the next call.

I am really sorry for appearing so assertive on this point, but I did not imagine the impacts of all this stuff were so wide as to affect implementations too.

Thank you all for your patience,
R.

TallTed · 2022-08-23T14:18:47Z

Re: #77 (comment)

I should also note that w3.org URIs are preferred over w3id.org URIs in many WG-related scenarios, and while administration of w3.org redirects requires going through additional bureaucracy and lacks the simplicity of w3id.org updates via git, a functionally equivalent permalink-redirect arrangement should be possible.

pchampin · 2022-08-23T14:57:17Z

@ioggstream

I just meant that I expected YAML-LD to be interchangeable with JSON-LD without the need of bearing specific knowledge around.

and that's why, in my view, this "convenience context" is the right way to go. It simply relies on a standard JSON-LD mechanism.

Start with the following YAML-LD:

"@context": http://www.w3.org/ns/yaml-ld/v1
$id: http://champin.net/#pa
$type: http://schema.org/Person

Convert it to JSON(-LD)

{
  "@context": "http://www.w3.org/ns/yaml-ld/v1",
  "$id": "http://champin.net/#pa",
  "$type": "http://schema.org/Person"
}

which then expands to

{
  "@id": "http://champin.net/#pa",
  "@type": "http://schema.org/Person"
}

and converts to

<http://champin.net/#pa> a <http://schema.org/Person>.

As @gkellogg pointed out above, it could even be used in other JSON-LD documents where using $ instead of @ would be considered desirable. Conversely, its use would not be required by YAML-LD, and YAML-LD processors would still recognize good old @ keywords.

Co-authored-by: Ted Thibodeau Jr <[email protected]>

gkellogg · 2022-08-31T20:33:57Z

On today's meeting we resolved to postpone this and include something similar in a Best Practices document.

turn PR yaml-ld#77 to draft, and consider move this to Best Practices

There was further discussion about using a simpler bare-word Connivence Context, such as https://github.com/json-ld/convenience-context which we might host at https://json-ld.org/contexts/.

Definition of yaml-ld namespace documents, and updates to the spec to…

ee6bf58

… refer and use it. For #55. For #13.

gkellogg added the spec Issue on specification label Aug 20, 2022

gkellogg requested review from pchampin, ioggstream and anatoly-scherbakov August 20, 2022 22:00

Correct sections.

4ae6ec5

pchampin approved these changes Aug 22, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

TallTed requested changes Aug 22, 2022

View reviewed changes

ioggstream requested changes Aug 22, 2022

View reviewed changes

ioggstream reviewed Aug 22, 2022

View reviewed changes

gkellogg and others added 2 commits August 22, 2022 09:59

Updates from code review.

314b84d

Apply suggestions from code review

00eceee

More updates from @TallTed. Co-authored-by: Ted Thibodeau Jr <[email protected]>

gkellogg added the needs discussion label Aug 22, 2022

Reword problementic text on the convience context, as suggested by @T…

76ceeb2

…allTed.

TallTed reviewed Aug 22, 2022

View reviewed changes

spec/index.html Outdated Show resolved Hide resolved

Update spec/index.html

c95ef08

Co-authored-by: Ted Thibodeau Jr <[email protected]>

anatoly-scherbakov approved these changes Aug 26, 2022

View reviewed changes

gkellogg marked this pull request as draft August 31, 2022 20:36

gkellogg closed this Jul 21, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Definition of yaml-ld namespace documents #77

Definition of yaml-ld namespace documents #77

gkellogg commented Aug 20, 2022 •

edited by pr-preview bot

Loading

gkellogg commented Aug 20, 2022

pchampin left a comment

ioggstream left a comment

ioggstream Aug 22, 2022

TallTed Aug 22, 2022

gkellogg Aug 22, 2022

BigBlueHat Aug 31, 2022

ioggstream Aug 22, 2022

gkellogg Aug 22, 2022

ioggstream Aug 22, 2022

gkellogg Aug 22, 2022

ioggstream Aug 23, 2022

gkellogg Aug 23, 2022

ioggstream Aug 22, 2022

gkellogg Aug 22, 2022

ioggstream Aug 23, 2022

gkellogg Aug 23, 2022

gkellogg commented Aug 22, 2022

TallTed commented Aug 22, 2022

ioggstream commented Aug 23, 2022

TallTed commented Aug 23, 2022

pchampin commented Aug 23, 2022

gkellogg commented Aug 31, 2022

Definition of yaml-ld namespace documents #77

Definition of yaml-ld namespace documents #77

Conversation

gkellogg commented Aug 20, 2022 • edited by pr-preview bot Loading

gkellogg commented Aug 20, 2022

pchampin left a comment

Choose a reason for hiding this comment

ioggstream left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gkellogg commented Aug 22, 2022

TallTed commented Aug 22, 2022

ioggstream commented Aug 23, 2022

TallTed commented Aug 23, 2022

pchampin commented Aug 23, 2022

gkellogg commented Aug 31, 2022

gkellogg commented Aug 20, 2022 •

edited by pr-preview bot

Loading