From ee6bf586723b509a239dbf44de45acd664dd4ef8 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Sat, 20 Aug 2022 14:38:41 -0700 Subject: [PATCH 1/6] Definition of yaml-ld namespace documents, and updates to the spec to refer and use it. For #55. For #13. --- README.md | 2 + ns/v1.haml | 87 +++++++++++++++++++++++ ns/v1.jsonld | 34 +++++++++ spec/index.html | 180 +++++++++++++++++++++++++++++++----------------- 4 files changed, 238 insertions(+), 65 deletions(-) create mode 100644 ns/v1.haml create mode 100644 ns/v1.jsonld diff --git a/README.md b/README.md index 0fc6609..099f4b3 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ as developed by the [JSON for Linking Data Community Group](https://www.w3.org/c The Use Cases and Requirements document can also be read [read directly](https://json-ld.github.io/yaml-ld/UCR/). +The YAML-LD Namespace contains a [convenience context](https://www.w3.org/ns/yaml-ld/v1) which can also be [red directly](https://json-ld.github.io/yaml-ld/ns/v1.html). + ## Disclaimer UNDER THE EXCLUSIVE LICENSE, THIS DOCUMENT AND ALL DOCUMENTS, TESTS AND SOFTWARE THAT LINK THIS STATEMENT ARE PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. diff --git a/ns/v1.haml b/ns/v1.haml new file mode 100644 index 0000000..1b6530f --- /dev/null +++ b/ns/v1.haml @@ -0,0 +1,87 @@ + + + +The JSON-LD Vocabulary + + + + +

The YAML-LD Convenience Context

+

W3C

+

+Alternate versions of the vocabulary definition exist in +JSON-LD. +

+
+
Published:
+
+
+
+

Introduction

+

+This document, and the associated documents in alternative formats, defines the YAML-LD Convenience Context. +This context defines terms that can be used in place of JSON-LD keywords +to simplify serialization of documents in YAML-LD, within the limitations +of using aliases of keywords in JSON-LD algorithms. +

+ +
+

Context Definition

+
+ +
+ + diff --git a/ns/v1.jsonld b/ns/v1.jsonld new file mode 100644 index 0000000..f96e12c --- /dev/null +++ b/ns/v1.jsonld @@ -0,0 +1,34 @@ +{ + "@context": { + "$always": "@always", + "$base": "@base", + "$container": "@container", + "$direction": "@direction", + "$embed": "@embed", + "$explicit": "@explicit", + "$graph": "@graph", + "$id": "@id", + "$import": "@import", + "$included": "@included", + "$index": "@index", + "$json": "@json", + "$language": "@language", + "$list": "@list", + "$nest": "@nest", + "$never": "@never", + "$none": "@none", + "$null": "@null", + "$omitDefault": "@omitDefault", + "$once": "@once", + "$prefix": "@prefix", + "$propagate": "@propagate", + "$protected": "@protected", + "$requireAll": "@requireAll", + "$reverse": "@reverse", + "$set": "@set", + "$type": "@type", + "$value": "@value", + "$version": "@version", + "$vocab": "@vocab" + } +} diff --git a/spec/index.html b/spec/index.html index c14de66..d1e55a3 100644 --- a/spec/index.html +++ b/spec/index.html @@ -263,7 +263,7 @@

Introduction

- [[JSON-LD]] is a JSON-based format to serialize Linked Data. + [[JSON-LD11]] is a JSON-based format to serialize Linked Data. In recent years, [[YAML]] has emerged as a more concise format to represent information that had previously been serialized as [[JSON]], including API specifications, data schemas, and Linked Data. @@ -313,14 +313,16 @@

Terminology

conforming to the [[JSON]] grammar.

- The term JSON-LD document is imported from [[JSON-LD]]. + The term JSON-LD document is imported from [[JSON-LD11]].

The term - internal representation - is imported from [[JSON-LD-API]]. + internal representation + is imported from [[JSON-LD11-API]]. + The term documentLoader + is imported from [[JSON-LD11-API]]

The terms @@ -408,23 +410,21 @@

Namespace Prefixes

A YAML-LD document complies with this specification if it follows the normative statements from this specification and - can be interpreted as [[JSON-LD]] after transformation into the internal representation. + can be interpreted as [[JSON-LD11]] after transformation into the internal representation. For convenience, normative statements for documents are often phrased as statements on the properties of the document.

A YAML-LD document complies with the YAML-LD-JSON profile of this specification if it follows the normative statements from this specification and can be transformed into a JSON-LD representation, then back to a conforming YAML-LD document, without loss of semantic information. -

- - +

Basic Concepts

- To ease writing and collaborating on [[JSON-LD]] documents, it is becoming common practice + To ease writing and collaborating on [[JSON-LD11]] documents, it is becoming common practice to serialize them as [[YAML]]. This requires a registered media type, not only to enable content negotiation of linked data documents in YAML, but also to define the expected behavior of @@ -515,12 +515,91 @@

Basic Concepts

FIXME.

+ +
+

Convenience Context

+

As JSON-LD keywords cannot be represented in YAML without being quoted, + publishers may find it useful to declare term aliases for these + keywords.

+ +

+ For convenience, a convenience context is available + at `https://www.w3.org/ns/yaml-ld/v1`, which pre-defines these aliases: +

+ + 
+        
+
+ +

The convenience context contains an alias to every JSON-LD keyword which the JSON-LD 1.1 + specification permits aliasing — which means all the keywords except @context. The reserved `@` character is + replaced by `$`, which is not reserved and therefore does not require quoting. Consider + + reformatted using the convenience context:

+ +

This allows YAML-LD to be created with minimal use of map quoted keys (Note that the `@context` keyword cannot be aliased):

+ + 
+      
+
+
-
+

Core Requirements

-
+

Encoding

@@ -528,7 +607,7 @@

Encoding

-
+

Comments

Comments in YAML-LD documents are treated as white space. @@ -538,7 +617,7 @@

Comments

-
+

Anchors and aliases

Since anchor names are a serialization detail, such anchors @@ -623,7 +702,7 @@

Anchors and aliases

-
+

Streams

@@ -663,6 +742,17 @@

Streams

+
+

Pre-loaded Contexts

+

In order to reduce the demand for loading static documents, + implementations SHOULD maintain a locally cached version of the following + documents the be satisfied by the default documentLoader.

+ +
    +
  • `https://www.w3.org/ns/yaml-ld/v1`
    • +
+
+

Conversion to the Internal Representation

@@ -1174,15 +1264,15 @@

Best Practices

- Follow JSON-LD best practices + Follow JSON-LD best practices …in order to achieve a greater level of reusability, performance, and human friendliness among YAML-LD aware - systems. The [[json-ld-bp]] document is as relevant to YAML-LD as it is to [[JSON-LD]]. + systems. The [[json-ld-bp]] document is as relevant to YAML-LD as it is to [[JSON-LD11]].

- Do not force users to author contexts + Do not force users to author contexts Instead, provide pre-built contexts that the user can reference by URL for a majority of common use cases.

@@ -1190,25 +1280,25 @@

Best Practices

YAML-LD is intended to simplify the authoring of Linked Data for a wide range of domain experts; its target audience is not comprised solely of IT professionals. [[YAML]] is chosen as a medium to minimize syntactic noise, - and to keep the authored documents concise and clear. [[JSON-LD]] (and hence YAML-LD) Context comprises a special + and to keep the authored documents concise and clear. [[JSON-LD11]] (and hence YAML-LD) Context comprises a special language of its own. A requirement to author such a context would make the domain expert's job much harder — which we, as system architects and developers, should try to avoid.

- Use a default context + Use a default context

If most, or all, of a user's documents are based on one particular context, try to make it the default in order to rescue the user from copy-pasting the same technical incantation from one document to another.
-

For instance, according to [[json-ld-api]], the `expand()` method of a JSON-LD processor accepts an +

For instance, according to [[JSON-LD11-API]], the `expand()` method of a JSON-LD processor accepts an `expandContext` argument which can be used to provide a default system context.

- Alias JSON-LD keywords + Alias JSON-LD keywords If possible, map JSON-LD keywords containing the `@` character to keywords that do not contain it.

@@ -1247,54 +1337,13 @@

Best Practices

- Use YAML-LD Convenience Context + Use YAML-LD Convenience Context

YAML-LD users may use a JSON-LD context provided as part of this specification, henceforth known as the - convenience context, which defines a standardized mapping of every `@`-keyword to a `$`-keyword, except `@context`. + convenience context, which defines a standardized mapping of every `@`-keyword to a `$`-keyword, except `@context`.

- - -

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

Consider reformatted using the convenience context:

@@ -1320,6 +1369,7 @@

Best Practices

The applicability of this context depends on the domain and is left to the architect's best judgement.

+

See for more information.

From 4ae6ec5875119e267efc6d8f45bad3fd4992fbbc Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Sat, 20 Aug 2022 15:10:17 -0700 Subject: [PATCH 2/6] Correct sections. --- spec/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/index.html b/spec/index.html index d1e55a3..f68460e 100644 --- a/spec/index.html +++ b/spec/index.html @@ -729,7 +729,6 @@

Streams

en: Smoke --> -

Each of the individual YAML documents in the stream @@ -740,7 +739,7 @@

Streams

This is inconsistent with the processing description in .

-
+

Pre-loaded Contexts

@@ -752,6 +751,7 @@

Pre-loaded Contexts

  • `https://www.w3.org/ns/yaml-ld/v1`
    • +

    Conversion to the Internal Representation

    From 314b84df664448f948df3224ca27336304b90388 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Mon, 22 Aug 2022 09:59:08 -0700 Subject: [PATCH 3/6] Updates from code review. --- README.md | 6 ++++-- ns/{v1.haml => v1.html} | 0 2 files changed, 4 insertions(+), 2 deletions(-) rename ns/{v1.haml => v1.html} (100%) diff --git a/README.md b/README.md index 099f4b3..47e34f5 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,13 @@ # YAML-LD This repository describes the [YAML][] serialization of [JSON-LD 1.1][] -as developed by the [JSON for Linking Data Community Group](https://www.w3.org/community/json-ld/). The editors’ draft of the Note can also be [read directly](https://json-ld.github.io/yaml-ld/spec/). +as developed by the [JSON for Linking Data Community Group](https://www.w3.org/community/json-ld/). +The editors’ draft of the Note can also be [read directly](https://json-ld.github.io/yaml-ld/spec/). The Use Cases and Requirements document can also be read [read directly](https://json-ld.github.io/yaml-ld/UCR/). -The YAML-LD Namespace contains a [convenience context](https://www.w3.org/ns/yaml-ld/v1) which can also be [red directly](https://json-ld.github.io/yaml-ld/ns/v1.html). +The YAML-LD Namespace contains a [convenience context](https://www.w3.org/ns/yaml-ld/v1) +which can also be [read directly](https://json-ld.github.io/yaml-ld/ns/v1.html). ## Disclaimer diff --git a/ns/v1.haml b/ns/v1.html similarity index 100% rename from ns/v1.haml rename to ns/v1.html From 00eceeebb84cb760436bc85fc5e50eee86efaf4c Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Mon, 22 Aug 2022 10:14:35 -0700 Subject: [PATCH 4/6] Apply suggestions from code review More updates from @TallTed. Co-authored-by: Ted Thibodeau Jr --- spec/index.html | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/spec/index.html b/spec/index.html index f68460e..ac78e52 100644 --- a/spec/index.html +++ b/spec/index.html @@ -523,8 +523,9 @@

    Convenience Context

    keywords.

    - For convenience, a convenience context is available - at `https://www.w3.org/ns/yaml-ld/v1`, which pre-defines these aliases: + To make this easier, a convenience context which pre-defines + these aliases is available at `https://www.w3.org/ns/yaml-ld/v1`, and + partially shown below: 

    @@ -567,7 +568,7 @@ 
    Convenience Context

    The convenience context contains an alias to every JSON-LD keyword which the JSON-LD 1.1 - specification permits aliasing — which means all the keywords except @context. The reserved `@` character is + specification permits to be aliased — which means all the keywords except @context. The reserved `@` character is replaced by `$`, which is not reserved and therefore does not require quoting. Consider reformatted using the convenience context:

    @@ -743,9 +744,9 @@

    Streams

    Pre-loaded Contexts

    -

    In order to reduce the demand for loading static documents, +

    To reduce the demand for loading static documents, implementations SHOULD maintain a locally cached version of the following - documents the be satisfied by the default documentLoader.

    + documents that will be satisfied by the default documentLoader.

    • `https://www.w3.org/ns/yaml-ld/v1`
      • From 76ceeb26a770d522e64b9173158242a11d4a1ea0 Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Mon, 22 Aug 2022 10:43:03 -0700 Subject: [PATCH 5/6] Reword problementic text on the convience context, as suggested by @TallTed. --- ns/v1.html | 2 +- spec/index.html | 17 +++++++++++------ 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/ns/v1.html b/ns/v1.html index 1b6530f..eb359e0 100644 --- a/ns/v1.html +++ b/ns/v1.html @@ -40,7 +40,7 @@

      Introduction

      This document, and the associated documents in alternative formats, defines the YAML-LD Convenience Context. This context defines terms that can be used in place of JSON-LD keywords to simplify serialization of documents in YAML-LD, within the limitations -of using aliases of keywords in JSON-LD algorithms. +on using aliases of keywords in JSON-LD algorithms.

      diff --git a/spec/index.html b/spec/index.html index ac78e52..30ffb47 100644 --- a/spec/index.html +++ b/spec/index.html @@ -567,13 +567,18 @@

      Convenience Context

      --> -

      The convenience context contains an alias to every JSON-LD keyword which the JSON-LD 1.1 - specification permits to be aliased — which means all the keywords except @context. The reserved `@` character is - replaced by `$`, which is not reserved and therefore does not require quoting. Consider - - reformatted using the convenience context:

      +

      The convenience context contains an alias for every JSON-LD keyword + the JSON-LD 1.1 specifications permit to be aliased — + JSON-LD does not allow `@context` to be aliased. + This allows YAML-LD to be created with minimal use of quoted keys. + The YAML-reserved "`@`" character is replaced by "`$`", + which is not reserved and therefore does not require quoting. +

      -

      This allows YAML-LD to be created with minimal use of map quoted keys (Note that the `@context` keyword cannot be aliased):

      +

      + Consider + reformatted using the convenience context: + 

      Date: Tue, 23 Aug 2022 08:49:52 -0700
Subject: [PATCH 6/6] Update spec/index.html

Co-authored-by: Ted Thibodeau Jr 
---
 spec/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec/index.html b/spec/index.html
index 30ffb47..e7284a1 100644
--- a/spec/index.html
+++ b/spec/index.html
@@ -568,7 +568,7 @@ 
      Convenience Context

      The convenience context contains an alias for every JSON-LD keyword - the JSON-LD 1.1 specifications permit to be aliased — + permitted to be aliased by the JSON-LD 1.1 specifications; JSON-LD does not allow `@context` to be aliased. This allows YAML-LD to be created with minimal use of quoted keys. The YAML-reserved "`@`" character is replaced by "`$`",