diff --git a/README.md b/README.md index 0fc6609..47e34f5 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,14 @@ # 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 [read 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.html b/ns/v1.html new file mode 100644 index 0000000..eb359e0 --- /dev/null +++ b/ns/v1.html @@ -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 +on 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..e7284a1 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,97 @@

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.

+ +

+ 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: +

+ + 
+        
+
+ +

The convenience context contains an alias for every JSON-LD keyword + 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 "`$`", + which is not reserved and therefore does not require quoting. +

+ +

+ Consider + reformatted using the convenience context: +

+ + 
+      
+
+
-
+

Core Requirements

-
+

Encoding

@@ -528,7 +613,7 @@

Encoding

-
+

Comments

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

Comments

-
+

Anchors and aliases

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

Anchors and aliases

-
+

Streams

@@ -650,7 +735,6 @@

Streams

en: Smoke --> -

Each of the individual YAML documents in the stream @@ -661,6 +745,18 @@

Streams

This is inconsistent with the processing description in .

+
+ +
+

Pre-loaded Contexts

+

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

+ +
    +
  • `https://www.w3.org/ns/yaml-ld/v1`
    • +
+
@@ -1174,15 +1270,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 +1286,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 +1343,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 +1375,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.