From 120883ee07c33c8fca30fbbed692bccbe489bb56 Mon Sep 17 00:00:00 2001 From: Anatoly Scherbakov Date: Sat, 18 Mar 2023 23:38:18 +0400 Subject: [PATCH] =?UTF-8?q?#88=20All=20mentions=20of=20Extended=20Profile?= =?UTF-8?q?=20=E2=86=92=20separate=20section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- spec/index.html | 2479 ++++++++++++++++++++++++----------------------- 1 file changed, 1249 insertions(+), 1230 deletions(-) diff --git a/spec/index.html b/spec/index.html index 80cf934..dc799d5 100644 --- a/spec/index.html +++ b/spec/index.html @@ -307,18 +307,6 @@

Introduction

such that any YAML-LD document can be represented in JSON-LD.

-

- To take better advantage of the broader expressivity of YAML, - this document also defines a means of extending the - JSON-LD internal representation to allow a more complete expression - of native data types within YAML-LD, and allows use of the complete - [[[JSON-LD11-API]]] [[JSON-LD11-API]] - - Application Programming Interface - - to manipulate extended YAML-LD documents. -

-

How to read this document

@@ -531,16 +519,6 @@

Namespace Prefixes

without loss of semantic information.

-

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

-
@@ -636,22 +614,6 @@

Basic Concepts

Core Requirements

-

- As [[YAML]] has well-defined representation requirements, - all YAML-LD streams MUST form a - - well-formed stream - - and use alias node defined by a previous node - with a corresponding anchor; - otherwise, a - loading-document-failed - error has been detected and processing is aborted. -

-

Encoding

@@ -700,19 +662,6 @@

Anchors and aliases

When interpreting the document as JSON-LD, alias nodes MUST be resolved by value to their target nodes.

-

- When processing using the YAML-LD JSON profile, - documents MUST NOT contain alias nodes; - otherwise, a - profile-error - error has been detected and processing is aborted. - The YAML-LD extended profile allows full use of - anchor names and alias nodes subject to - the requirements described above in this section. -

The YAML-LD document in the following example @@ -825,1327 +774,1397 @@

Streams

-
-

Conversion to the Internal Representation

- -

YAML-LD processing is defined by converting YAML to the - internal representation and using [[[JSON-LD11-API]]] - to process on that representation, - after which the representation is converted back to YAML. - As information specific to a given YAML document structure is lost - in this transformation, much of the specifics of that - original representation are therefore lost in that conversion, - limiting the ability to fully round-trip a YAML-LD document back - to an equivalent representation. - Consequently, round-tripping in this context is limited to preservation of the semantic - representation of a document, - rather than a specific syntactic representation.

- -

- If the {{JsonLdOptions/extendedYAML}} API flag is `true`, the processing result - will be in the extended internal representation. -

- - - -

The conversion process represented here is compatible with - the description of - "Composing the Representation Graph" from the - 3.1.2 Load section of [[YAML]]. - The steps described below for converting to the - internal representation operate upon that - . -

+
+

Interoperability Considerations

-

When operating using the YAML-LD JSON profile, - it is intended that the common feature provided by most - YAML libraries of transforming YAML directly to JSON - satisfies the requirements for parsing a YAML-LD file. +

+ For general interoperability considerations on the serialization of + JSON documents in [[YAML]], see YAML + and the Interoperability consideration of application/yaml [[I-D.ietf-httpapi-yaml-mediatypes]].

- -

- As a developer, - I want to be able to convert JSON-LD documents to YAML-LD by simply serializing the document using any standard YAML library, - So that the resulting YAML is valid YAML-LD, resolving to the same graph as the original JSON-LD. +

+ The YAML-LD format and the media type registration are not restricted to a specific + version of YAML, + but implementers that want to use YAML-LD with YAML versions + other than 1.2.2 need to be aware that the considerations and analysis provided + here, including interoperability and security considerations, are based + on the YAML 1.2.2 specification.

+
-
-

Converting a YAML stream

- -

A YAML stream is composed of zero or more YAML documents.

+
+

IANA Considerations

-

- YAML streams may correspond more directly to - [[[RFC7464]]], which are not presently part of the - JSON-LD representation model. - The description here more closely aligns with how JSON-LD - interprets HTML Scripts. -

+

This section has been submitted to the Internet Engineering Steering + Group (IESG) for review, approval, and registration with IANA.

+

+ This section describes the information required to register the above media type according to [[RFC6838]] +

-
    -
  1. Set |stream content| to an empty array.
    2. -
  2. If the stream is empty, - set |stream content| to an empty array.
    3. -
  3. Otherwise, if the stream contains a single YAML document, - set |stream content| the result of - .
    4. -
  4. Otherwise: for each |document| in the stream: -
      -
    1. Set |doc| to the result of for |document|.
      2. -
    2. If |doc| is an array, - merge it to the end of |stream content|.
      3. -
    3. Otherwise, append |doc| to |stream content|
      4. -
    -
    - This step is inconsistent with other statements about processing each - document separately, resulting in some other stream of JSON-LD output - (i.e., something like NDJSOND-LD). - Also, presumably an empty stream would result in either - an empty NDJSON-LD document, or an empty [[JSON-LD]] document. -
    -
    5. -
  5. The conversion result is |stream content|.
    6. -
- -

- Any error reported in a recursive processing step MUST result - in the failure of this processing step.

+
+

application/ld+yaml

+
+
Type name:
+
application
+
Subtype name:
+
ld+yaml
+
Required parameters:
+
N/A
+
Optional parameters:
+
+
+
profile
+
+

A non-empty list of space-separated URIs identifying specific + constraints or conventions that apply to a YAML-LD document according to [[RFC6906]]. + A profile does not change the semantics of the resource representation + when processed without profile knowledge, so that clients both with + and without knowledge of a profiled resource can safely use the same + representation. The profile parameter MAY be used by + clients to express their preferences in the content negotiation process. + If the profile parameter is given, a server SHOULD return a document that + honors the profiles in the list which it recognizes, + and MUST ignore the profiles in the list which it does not recognize. + It is RECOMMENDED that profile URIs are dereferenceable and provide + useful documentation at that URI. For more information and background + please refer to [[RFC6906]].

+

This specification allows the use of the `profile` parameters listed in + and additionally defines the following: +

+
+
http://www.w3.org/ns/json-ld#extended
+
To request or specify extended YAML-LD document form. +
+ This is a placeholder for specifying something like an + extended YAML-LD document form + making use of YAML-specific features. +
+
+

+ When used as a media type parameter [[RFC4288]] + in an HTTP Accept header field [[RFC9110]], + the value of the profile parameter MUST be enclosed in quotes (") if it contains + special characters such as whitespace, which is required when multiple profile URIs are combined.

+

When processing the "profile" media type parameter, it is important to + note that its value contains one or more URIs and not IRIs. In some cases + it might therefore be necessary to convert between IRIs and URIs as specified in + section 3 Relationship between IRIs and URIs + of [[RFC3987]].

+
+
+
+
Encoding considerations:
+
See YAML media type.
+
Security considerations:
+
See .
+
Interoperability considerations:
+
See .
+
Published specification:
+
http://www.w3.org/TR/yaml-ld
+
Applications that use this media type:
+
Any programming environment that requires the exchange of + directed graphs. Implementations of YAML-LD have been created for + FIXME. +
+
Additional information:
+
+
+
Magic number(s):
+
See application/yaml
+
File extension(s):
+
.yamlld
+
Macintosh file type code(s):
+
TEXT
+
+
+
Person & email address to contact for further information:
+
Philippe Le Hégaret <plh@w3.org>
+
Intended usage:
+
Common
+
Restrictions on usage:
+
N/A
+
Author(s):
+
Roberto Polli, Gregg Kellogg
+
Change controller:
+
W3C
+
-
-

Converting a YAML document

- -

From the YAML grammar, - a YAML document MAY be preceded by a - Document Prefix - and/or a set of - directives - followed by a - YAML bare document, - which is composed of a single node. +

+

Fragment identifiers

+

Fragment identifiers used with application/ld+yaml + are treated as in RDF syntaxes, as per + RDF 1.1 Concepts and Abstract Syntax + [[RDF11-CONCEPTS]] + and do not follow the process defined for application/yaml.

-
    -
  1. Create an empty |named nodes| map - which will be used to associate each alias node - with the node - having the corresponding node anchor.
    2. -
  2. - Set |document content| to the result - of processing the node associated with the - YAML bare document, - using the appropriate conversion step defined in this section. - If that node is not one of the following, a - loading-document-failed - error has been detected and processing is aborted. - - - -
    - A node may be of another type, but this is incompatilbe - with JSON-LD, where the top-most node must be either an - array or map. -
    -
    3. -
  3. The conversion result is |document content|.
    4. -
+ +
Perhaps more on fragment identifiers from Issue 13
-

- Any error reported in a recursive processing step MUST result - in the failure of this processing step.

- -
-

Converting a YAML sequence

- -

Both block sequences and flow sequences - are directly aligned with - an array in the internal representation.

- -
    -
  1. Set |sequence content| to an empty array.
    2. -
  2. If the sequence has a - node anchor, - add a reference from the anchor name to the - sequence - in the |named nodes| map.
    3. -
  3. For each node |n| in the - sequence, - append the result of processing |n| - to |sequence content| - using the appropriate conversion step. -
    4. -
  4. The conversion result is |sequence content|.
    5. -
- -

- Any error reported in a recursive processing step MUST result - in the failure of this processing step.

+
+

Examples

+

FIXME

+
-
-

Converting a YAML mapping

- -

Both block mappings and flow mappings - are directly aligned with - a map in the internal representation.

- -
    -
  1. Set |mapping content| to an empty map.
    2. -
  2. Otherwise, if the mapping has a - node anchor, - add a reference from the anchor name to - the mapping - in the |named nodes| map.
    3. -
  3. For each |entry| in the mapping - composed of a key/value pair: -
      -
    1. Set |key| and |value| - to the result of processing |entry| - using the appropriate conversion step.
      2. -
    2. - If |key| is not a string, - a mapping-key-error - error has been detected and processing MUST be aborted.
      3. -
    3. Add a new entry to - |mapping content| using - |key| and |value|.
      4. -
    -
    4. -
  4. The conversion result is |mapping content|.
    5. -
+
+

REMOVE THIS SECTION BEFORE PUBLICATION.

-

- Any error reported in a recursive processing step MUST result - in the failure of this processing step.

-
+

FAQ

-
-

Converting a YAML scalar

+ #### Why does YAML-LD not preserve comments? +
+ According to [[YAML]], information that does not reflect + into the representation graph (e.g., comments, directives, mapping keys order, + anchor names, ...) must not be used to convey application level information. + Moreover + [[JSON]] (and hence [[JSON-LD11]]) does not support comments, + and other Linked Data serialization formats + that support comments (such as [[?TURTLE]]) + do not provide a means to preserve them + when processing and serializing the document + in other formats. + The proposed behavior is thus consistent with + other implementations. -
    -
  1. If the {{JsonLdOptions/extendedYAML}} flag is `true`, - and node |n| - has a node tag |t|, - |n| is mapped as follows: -
      -
    1. - If |t| resolves with a prefix of `tag:yaml.org.2002:`, - the conversion result is mapped through the - YAML Core Schema. -
      2. -
    2. - Otherwise, if |t| resolves with a prefix of `https://www.w3.org/ns/i18n#`, - and the suffix does not contain - an underscore (`"_"`), - the conversion result is a language-tagged string - with value taken from |n|, - and a language tag taken from the suffix of |t|. -
      - Node tags including an underscore (`"_"`), - such as `i18n:ar-eg_rtl` describe a combination - of language and text direction. - See - The `i18n` Namespace - - in [[JSON-LD11]]. -
      -
      3. -
    3. - Otherwise, the conversion result is an - RDF literal with value taken from |n| - and datatype IRI taken from |t|. -
      4. -
    -
    2. -
  2. - Otherwise, the conversion result is mapped through the - YAML Core Schema.
    3. -
- -

- Implementations may retain the - representation as an YAML Integer, - or YAML Floating Point, - but a JSON-LD processor must treat them uniformly - as a number, although the specific type of number - value SHOULD be retained for round-tripping. -

-
+ While YAML-LD could define a specific predicate for comments, + that is insufficient because, for example, + the order of keywords is not preserved in JSON, so the + comments could be displaced. + This specification does not provide a means for preserving + [[YAML]] comments after a JSON serialization. -
-

Converting a YAML alias node

+ 
+      
+
-

- If an alias node is encountered when processing the - YAML representation graph - and the {{JsonLdOptions/extendedYAML}} flag is `false`, - the YAML-LD JSON profile has been selected. - A profile-error - error has been detected and processing MUST be aborted. -

+ Transforming the above entry into a JSON-LD document + results in: -

- If a cycle is detected, - a processing error MUST be returned, - and processing aborted. -

-
-
- -
-

Conversion to YAML

- -

The conversion process from the internal representation - involves turning that representation back into a YAML - representation graph - and relies on the description of - "Serializing the Representation Graph" from the - 3.1.1 Dump section of [[YAML]] - for the final serialization. -

+ 
+      
+
+ -

- As the internal representation is rooted by either - an array or a map, - the process of transforming the internal representation - to YAML begins by preparing an empty representation graph - which will be rooted with either a - YAML mapping or YAML sequence. -

+ #### Why does YAML-LD not extend the JSON-LD data model ? +
+ [[JSON]] only represents simple trees while [[YAML]] can support + rooted, directed graphs with references and cycles. -

- Although outside of the scope of this specification, - processors MAY use - YAML directives, including TAG directives, and - Document markers, - as appropriate for best results. - Specifically, if the {{JsonLdOptions/extendedYAML}} API flag is `true`, - the document SHOULD use the `%YAML` directive with - version set to at least `1.2`. - To improve readability and reduce document size, - the document MAY use a `%TAG` directive appropriate for - RDF literals contained within the representation. -

+ The above structures cannot be preserved when serializing + to JSON-LD and - with respect to cycles - the serialization + will fail. -

- The use of `%TAG` directives in YAML-LD is similar to the use - of the `PREFIX` directive in [[?Turtle]] - or the general use of terms as prefixes to create - Compact IRIs in [[JSON-LD11]]: - they not change the meaning of the encoded scalars. -

+ Programming languages such as Java and Python already support + YAML representation graphs, but these implementations may behave + differently. + In the following example, `&value` references the value + of the keyword `value`. 
-    
+         data-content-type="application/ld+yaml"
+         title="YAML-LD with references">
+
-

- Although allowed within the YAML Grammar, some current YAML parsers - do not allow the use of `"#"` within a tag URI. Substituting - the `"%23"` escape is a workaround for this problem, that will - hopefully become unnecessary as implementations are updated. -

+ Processing this entry in Python, I get the following + structure that preserve the references to + mutable objects (e.g., the `temperature` dict) + but not to scalars (e.g., the `value` keyword). -
-

A concrete proposal in that direction would be to use a tag at the - top-level of any "idiomatic" YAML-LD document, applying to the whole - object/array that makes the document.

+ 
+      
+
-

It might also include a version - to identify the specification that it relates to, allowing - for version announcement that could be used for future-proofing.

+ Since all these implementations pre-date this + specification, some more interoperable choices include the following: -

The following block is one example:

+ * forbidding cycles in YAML-LD documents + * considering all references in YAML-LD as static, + i.e., a shorthand way to repeat specific patterns - 
-      !yaml-ld
-      $context: http://schema.org/
-      $type: Person
-      name: Pierre-Antoine Champin
-
+
+
+

Best Practices

-

See for an example of serializing the extended internal representation.

+

Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two + useful thoughts.

-
-

Converting From the Internal Representation

+
+

+ 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-LD11]]. +

+
-

- This algorithm describes the steps to convert - each element from the internal representation - into corresponding YAML nodes by recursively - processing each element |n|. -

+
+

+ Do not force users to author contexts -

    -
  1. - If |n| is an array, - the conversion result is a YAML sequence - with child nodes of the sequence taken by converting - each value of |n| using this algorithm. -
    2. -
  2. - Otherwise, if |n| is an map, - the conversion result is a YAML mapping - with keys and values taken by converting each - key/value pair of |n| using this algorithm. -
    3. -
  3. - Otherwise, if |n| is an RDF literal: -
      -
    1. - If the datatype IRI - of |n| is `xsd:string`, - the conversion is a YAML scalar - with the value taken from that value of |n|. -
      2. -
    2. Otherwise, if |n| is a language-tagged string, - the conversion is a YAML scalar - with the value taken from that value of |n| - and a node tag constructed by appending - that language tag to - `https://www.w3.org/ns/i18n#`. -
      3. -
    3. - Otherwise, the conversion is a YAML scalar - with the value taken from that value of |n| - and a node tag taken from the - datatype IRI of |n|. -
      4. -
    -
    4. -
  4. - Otherwise, if |n| is a number, - the conversion result is a YAML scalar - with the value taken from |n|. -
    5. -
  5. - Otherwise, if |n| is a boolean, - the conversion result is a YAML scalar - with the value either `true` or `false` - based on the value of |n|. -
    6. -
  6. - Otherwise, if |n| is null, - the conversion result is a YAML scalar - with the value `null`. -
    7. -
  7. - Otherwise, conversion result is a YAML scalar - with the value taken from |n|. -
    8. -
-
-
+ Instead, provide pre-built contexts that the user can reference by URL for a majority of common use cases. +

+ -
-

Application Profiles

+

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

-

This section identifies two application profiles for operating with - YAML-LD:

- +
+

+ Use a default context +

-

Application profiles allow publishers to use YAML-LD - either for maximum interoperability, - or for maximum expressivity. - The YAML-LD JSON profile provides for complete round-tripping - between YAML-LD documents and JSON-LD documents. - The YAML-LD extended profile allows for - fuller use of YAML features to enhance the ability to - represent a larger number of native datatypes - and reduce document redundancy.

+ 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-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 + + If possible, map JSON-LD keywords containing the `@` character to keywords that do not contain it. +

+
+ +

The `@` character is reserved in YAML, and thus requires quoting (or escaping), as in the following + example:

+ + 
+        
+
+ +

The need to quote these keywords has to be learnt, and introduces one more little irregularity to the document + author's life. Further, on most keyboard layouts, typing quotes will require `Shift`, which reduces typing speed, + albeit slightly.

+ +

In order to avoid this, the context might introduce custom mappings for the necessary keywords. For instance, + [[schema-org]] context redefines `@id` as just `id` — which seems to be much more convenient to type, and + no more difficult to remember.

+ +
+

+ 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`. +

+
+ + + +

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:

+ 
+        
+
-

Application profiles can be set using the {{JsonLdProcessor}} - API interface, as well as an HTTP request profile (see ).

+

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

+
-
-

YAML-LD JSON Profile

+
+

Extended YAML-LD Profile

- The YAML-LD JSON profile - is based on the YAML Core Schema, - which interprets only a limited set of node tags. - YAML scalars with node tags outside of the defined range - SHOULD be avoided and MUST be converted to the closest - scalar type from the YAML Core Schema, - if found. - See - for specifics. + To take better advantage of the broader expressivity of YAML, + this document also defines a means of extending the + JSON-LD internal representation to allow a more complete expression + of native data types within YAML-LD, and allows use of the complete + [[[JSON-LD11-API]]] [[JSON-LD11-API]] + + Application Programming Interface + + to manipulate extended YAML-LD documents.

-

- Although YAML supports several additional encodings, - YAML-LD documents in the YAML-LD JSON Profile - MUST NOT use encodings other than UTF-8. +

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

-

- Keys used in a YAML mapping MUST be strings. +

+ As [[YAML]] has well-defined representation requirements, + all YAML-LD streams MUST form a + + well-formed stream + + and use alias node defined by a previous node + with a corresponding anchor; + otherwise, a + loading-document-failed + error has been detected and processing is aborted.

- Although YAML-LD documents MAY include node anchors, - documents MUST NOT use alias nodes. + The YAML-LD extended profile allows full use of + anchor names and alias nodes subject to + the requirements described above in this section.

-

- A YAML stream MUST include only a single YAML document, - as the JSON-LD internal representation only supports - a single document model. -

-
- -
-

YAML-LD Extended Profile

- -

- The YAML-LD extended profile - extends the YAML Core Schema, - allowing node tags to specify RDF literals - by using a JSON-LD extended internal representation capable - of directly representing RDF literals. -

- -

- As with the YAML-LD JSON profile, - YAML-LD documents in the YAML-LD extended profile - MUST NOT use encodings other than UTF-8. -

- -

- As with the YAML-LD JSON profile, - keys used in a YAML mapping MUST be strings. -

- -

- YAML-LD docucments MAY use alias nodes, - as long as dereferencing these aliases does not result in a loop. +

+ If the {{JsonLdOptions/extendedYAML}} API flag is `true`, the processing result + will be in the extended internal representation.

-

- As with the YAML-LD JSON profile, - a YAML stream MUST include only a single YAML document, - as the JSON-LD extended internal representation only supports - a single document model. -

- -

- Consier something like `!id` as a local tag to denote IRIs. +

+ When processing using the YAML-LD JSON profile, + documents MUST NOT contain alias nodes; + otherwise, a + profile-error + error has been detected and processing is aborted.

-
-

The JSON-LD Extended Internal Representation

+
+

Conversion to the Internal Representation

+ +

YAML-LD processing is defined by converting YAML to the + internal representation and using [[[JSON-LD11-API]]] + to process on that representation, + after which the representation is converted back to YAML. + As information specific to a given YAML document structure is lost + in this transformation, much of the specifics of that + original representation are therefore lost in that conversion, + limiting the ability to fully round-trip a YAML-LD document back + to an equivalent representation. + Consequently, round-tripping in this context is limited to preservation of the semantic + representation of a document, + rather than a specific syntactic representation.

+ + + +

The conversion process represented here is compatible with + the description of + "Composing the Representation Graph" from the + 3.1.2 Load section of [[YAML]]. + The steps described below for converting to the + internal representation operate upon that + .

-

- In addition to maps, arrays, and strings, - the internal representation allows native representation - of numbers, boolean values, and nulls. - The extended internal representation allows for native - representation of RDF literals, both - with a datatype IRI, - and language-tagged strings. +

When operating using the YAML-LD JSON profile, + it is intended that the common feature provided by most + YAML libraries of transforming YAML directly to JSON + satisfies the requirements for parsing a YAML-LD file.

-

- When transforming from the extended internal representation - to the internal representation — - for example when serializing to JSON - or to the YAML-LD JSON profile — - implementations MUST transform RDF literals to the closest - native representation of the internal representation: +

+ As a developer, + I want to be able to convert JSON-LD documents to YAML-LD by simply serializing the document using any + standard YAML library, + So that the resulting YAML is valid YAML-LD, resolving to the same graph as the original JSON-LD.

- - -

- An alternative would be to transform such literals to - JSON-LD value objects, - and we may want to provide a means of transforming between - the internal representation - and extended internal representation - using value objects, - but this treatment is consistent with - [[YAML]] Core Schema - Tag Resolution. -

-
-
-
+
+

Converting a YAML stream

-
-

The Application Programming Interface

+

A YAML stream is composed of zero or more YAML documents.

-

- This specification extends the [[[JSON-LD11-API]]] [[JSON-LD11-API]] - - Application Programming Interface - - and the [[[JSON-LD11-FRAMING]]] [[JSON-LD11-FRAMING]] - - Application Programming Interface - - to manage the serialization and deserialization of [[YAML]] - and to enable an option for setting the - YAML-LD extended profile. -

+

+ YAML streams may correspond more directly to + [[[RFC7464]]], which are not presently part of the + JSON-LD representation model. + The description here more closely aligns with how JSON-LD + interprets HTML Scripts. +

-
-

JsonLdProcessor

+
    +
  1. Set |stream content| to an empty array.
    2. +
  2. If the stream is empty, + set |stream content| to an empty array. +
    3. +
  3. Otherwise, if the stream contains a single YAML document, + set |stream content| the result of + . +
    4. +
  4. Otherwise: for each |document| in the stream: +
      +
    1. Set |doc| to the result of for |document|.
      2. +
    2. If |doc| is an array, + merge it to the end of |stream content|. +
      3. +
    3. Otherwise, append |doc| to |stream content|
      4. +
    +
    + This step is inconsistent with other statements about processing each + document separately, resulting in some other stream of JSON-LD output + (i.e., something like NDJSOND-LD). + Also, presumably an empty stream would result in either + an empty NDJSON-LD document, or an empty [[JSON-LD]] document. +
    +
    5. +
  5. The conversion result is |stream content|.
    6. +
-

- The - JSON-LD Processor - interface is the high-level programming structure that developers - use to access the JSON-LD transformation methods. - The updates below is an experimental - extension of the {{JsonLdProcessor}} interface defined in the - JSON-LD 1.1 API [[JSON-LD11-API]] - to serialize output as YAML rather than JSON. -

+

+ Any error reported in a recursive processing step MUST result + in the failure of this processing step.

+
+ +
+

Converting a YAML document

+ +

From the YAML grammar, + a YAML document MAY be preceded by a + Document Prefix + and/or a set of + directives + followed by a + YAML bare document, + which is composed of a single node. +

-
-
{{JsonLdProcessor/compact()}}
-
- Updates step 10 of the {{JsonLdProcessor/compact()}} algorithm - to serialize the the result as YAML rather than JSON - as defined in . -
-
{{JsonLdProcessor/expand()}}
-
- Updates step 9 of the {{JsonLdProcessor/expand()}} algorithm - to serialize the the result as YAML rather than JSON - as defined in . -
-
{{JsonLdProcessor/flatten()}}
-
- Updates step 7 of the {{JsonLdProcessor/flatten()}} algorithm - to serialize the the result as YAML rather than JSON - as defined in . -
-
- Updates step 22 of the - frame() - algorithm to serialize the the result as YAML rather than JSON - as defined in . -
-
{{JsonLdProcessor/fromRdf()}}
-
- Updates step 3 of the {{JsonLdProcessor/fromRdf()}} algorithm - to serialize the the result as YAML rather than JSON - as defined in . -
-
- Updates the - RDF to Object Conversion algorithm - before step 2.6 as follows: -
- Otherwise, if both the {{JsonLdOptions/useNativeTypes}} - and {{JsonLdOptions/extendedYAML}} flags are set - and the - datatype IRI - of |value| is not `xsd:string`:
    -
  1. - If |value| is a language-tagged string - set |converted value| to a new RDF literal - composed of the - lexical form - of |value| and - datatype IRI - composed of `https://www.w3.org/ns/i18n#` followed by - the - language tag - of |value|. +
  2. Create an empty |named nodes| map + which will be used to associate each alias node + with the node + having the corresponding node anchor.
    3. -
  3. - Otherwise, et |converted value| to |value|. +
  4. + Set |document content| to the result + of processing the node associated with the + YAML bare document, + using the appropriate conversion step defined in this section. + If that node is not one of the following, a + loading-document-failed + error has been detected and processing is aborted. + + + +
    + A node may be of another type, but this is incompatilbe + with JSON-LD, where the top-most node must be either an + array or map. +
    5. +
  5. The conversion result is |document content|.
-
-
-
{{JsonLdProcessor/toRdf()}}
-
- Updates the - Object to RDF Conversion algorithm - before step 10 as follows: -
-
    -
  1. - Otherwise, if |value| is an RDF literal, - |value| is left unmodified. - - This will only be the case when processing a value from an - extended internal representation. - -
    2. -
-
-
-
-
-
-

JsonLdOptions

-

The {{JsonLdOptions}} type is used to pass various options to the - {{JsonLdProcessor}} methods.

- - 
-        partial dictionary JsonLdOptions {
-          boolean extendedYAML = false;
-        };
-
+

+ Any error reported in a recursive processing step MUST result + in the failure of this processing step.

+
-

- In addition to those options defined in the - JSON-LD 1.1 API [[JSON-LD11-API]] - and JSON-LD 1.1 Framing [[JSON-LD11-FRAMING]], - this specification defines these additional options: -

+
+

Converting a YAML sequence

-
-
extendedYAML
-
- When used for serializing the internal representation - (or extended internal representation) - into a YAML representation graph: +

Both block sequences and flow sequences + are directly aligned with + an array in the internal representation.

- -
-
- When used for the {{documentLoader}}, - it causes documents of type `application/ld+yaml` - to be parsed into a YAML representation graph - and generates an internal representation - (or extended internal representation): +
  • The conversion result is |sequence content|.
    • + -
    + +
    +

    Converting a YAML mapping

    + +

    Both block mappings and flow mappings + are directly aligned with + a map in the internal representation.

    + +
      +
    1. Set |mapping content| to an empty map.
      2. +
    2. Otherwise, if the mapping has a + node anchor, + add a reference from the anchor name to + the mapping + in the |named nodes| map.
      3. -
    3. - Otherwise, it drops any node tags +
    4. For each |entry| in the mapping + composed of a key/value pair: +
        +
      1. Set |key| and |value| + to the result of processing |entry| + using the appropriate conversion step. +
        2. +
      2. + If |key| is not a string, + a mapping-key-error + error has been detected and processing MUST be aborted. +
        3. +
      3. Add a new entry to + |mapping content| using + |key| and |value|. +
        4. +
      5. - - - -
    +
  • The conversion result is |mapping content|.
    • + -
    -

    Remote Document and Context Retrieval

    +

    + Any error reported in a recursive processing step MUST result + in the failure of this processing step.

    +
    -

    This section describes an update to the - built-in {{LoadDocumentCallback}} - to load YAML streams and documents - into the internal representation, - or into the extended internal representation - if the {{JsonLdOptions/extendedYAML}} API flag is `true`.

    +
    +

    Converting a YAML scalar

    -

    - The {{LoadDocumentCallback}} algorithm in [[JSON-LD11-API]] - is updated as follows: -

    +
      +
    1. If the {{JsonLdOptions/extendedYAML}} flag is `true`, + and node |n| + has a node tag |t|, + |n| is mapped as follows: +
        +
      1. + If |t| resolves with a prefix of `tag:yaml.org.2002:`, + the conversion result is mapped through the + YAML Core Schema. +
        2. +
      2. + Otherwise, if |t| resolves with a prefix of `https://www.w3.org/ns/i18n#`, + and the suffix does not contain + an underscore (`"_"`), + the conversion result is a language-tagged string + with value taken from |n|, + and a language tag taken from the suffix of |t|. +
        + Node tags including an underscore (`"_"`), + such as `i18n:ar-eg_rtl` describe a combination + of language and text direction. + See + The `i18n` Namespace + + in [[JSON-LD11]]. +
        +
        3. +
      3. + Otherwise, the conversion result is an + RDF literal with value taken from |n| + and datatype IRI taken from |t|. +
        4. +
      +
      2. +
    2. + Otherwise, the conversion result is mapped through the + YAML Core Schema. +
      3. +
    -
      -
    • - Step 2 - is updated to prefer - Content-Type `application/ld+yaml`, - followed by `application/yaml`, - followed by the other specified - Content-Types. -
      • -
    • - After step 5, - add the following processing step: - Otherwise, if the retrieved resource's - Content-Type - is either `application/yaml` - or any media type with a `+yaml` suffix as defined in [[RFC6839]] - transform |document| to the internal representation - (or extended internal representation) - as described in . - Additionally, if the {{RemoteDocument/profile}} parameter - includes `http://www.w3.org/ns/json-ld#extended`, set the {{JsonLdOptions/extendedYAML}} option to `true`. -
      • -
    - -

    - These updates are intended to be compatible with other updates - to the {{LoadDocumentCallback}}, such as - Process HTML - as defined in [[JSON-LD11-API]]. -

    -
    +

    + Implementations may retain the + representation as an YAML Integer, + or YAML Floating Point, + but a JSON-LD processor must treat them uniformly + as a number, although the specific type of number + value SHOULD be retained for round-tripping. +

    +
    -
    -

    YamlLdErrorCode

    -

    The YamlLdErrorCode represents the collection of valid YAML-LD error codes, - which extends the {{JsonLdErrorCode}} definitions.

    +
    +

    Converting a YAML alias node

    - 
    -        enum YamlLdErrorCode {
-          "invalid-encoding",
-          "mapping-key-error",
-          "profile-error"
-        };
-
    +

    + The conversion result is the value of the entry + in the |named nodes| map having the node entry. + If none exist, the document is invalid, + and processing MUST end in failure. +

    -
    -
    invalid-encoding
    -
    The character encoding of an input is invalid.
    -
    mapping-key-error
    -
    A YAML mapping key was found that was not a string.
    -
    profile-error
    -
    The parsed YAML document contains features incompatible with the specified profile.
    -
    -
    -
    +

    + If an alias node is encountered when processing the + YAML representation graph + and the {{JsonLdOptions/extendedYAML}} flag is `false`, + the YAML-LD JSON profile has been selected. + A profile-error + error has been detected and processing MUST be aborted. +

    -
    -

    Security Considerations

    +

    + If a cycle is detected, + a processing error MUST be returned, + and processing aborted. +

    +
    +
    -

    See Security considerations in JSON-LD 1.1. - Also, see the YAML media type registration.

    -
    +
    +

    Conversion to YAML

    -
    -

    Interoperability Considerations

    +

    The conversion process from the internal representation + involves turning that representation back into a YAML + representation graph + and relies on the description of + "Serializing the Representation Graph" from the + 3.1.1 Dump section of [[YAML]] + for the final serialization. +

    -

    - For general interoperability considerations on the serialization of - JSON documents in [[YAML]], see YAML - and the Interoperability consideration of application/yaml [[I-D.ietf-httpapi-yaml-mediatypes]]. -

    -

    - The YAML-LD format and the media type registration are not restricted to a specific - version of YAML, - but implementers that want to use YAML-LD with YAML versions - other than 1.2.2 need to be aware that the considerations and analysis provided - here, including interoperability and security considerations, are based - on the YAML 1.2.2 specification. -

    -
    +

    + As the internal representation is rooted by either + an array or a map, + the process of transforming the internal representation + to YAML begins by preparing an empty representation graph + which will be rooted with either a + YAML mapping or YAML sequence. +

    -
    -

    IANA Considerations

    +

    + Although outside of the scope of this specification, + processors MAY use + YAML directives, including TAG directives, and + Document markers, + as appropriate for best results. + Specifically, if the {{JsonLdOptions/extendedYAML}} API flag is `true`, + the document SHOULD use the `%YAML` directive with + version set to at least `1.2`. + To improve readability and reduce document size, + the document MAY use a `%TAG` directive appropriate for + RDF literals contained within the representation. +

    -

    This section has been submitted to the Internet Engineering Steering - Group (IESG) for review, approval, and registration with IANA.

    -

    - This section describes the information required to register the above media type according to [[RFC6838]] -

    +

    + The use of `%TAG` directives in YAML-LD is similar to the use + of the `PREFIX` directive in [[?Turtle]] + or the general use of terms as prefixes to create + Compact IRIs in [[JSON-LD11]]: + they not change the meaning of the encoded scalars. +

    -
    -

    application/ld+yaml

    -
    -
    Type name:
    -
    application
    -
    Subtype name:
    -
    ld+yaml
    -
    Required parameters:
    -
    N/A
    -
    Optional parameters:
    -
    -
    -
    profile
    -
    -

    A non-empty list of space-separated URIs identifying specific - constraints or conventions that apply to a YAML-LD document according to [[RFC6906]]. - A profile does not change the semantics of the resource representation - when processed without profile knowledge, so that clients both with - and without knowledge of a profiled resource can safely use the same - representation. The profile parameter MAY be used by - clients to express their preferences in the content negotiation process. - If the profile parameter is given, a server SHOULD return a document that - honors the profiles in the list which it recognizes, - and MUST ignore the profiles in the list which it does not recognize. - It is RECOMMENDED that profile URIs are dereferenceable and provide - useful documentation at that URI. For more information and background - please refer to [[RFC6906]].

    -

    This specification allows the use of the `profile` parameters listed in - and additionally defines the following: -

    -
    -
    http://www.w3.org/ns/json-ld#extended
    -
    To request or specify extended YAML-LD document form. -
    - This is a placeholder for specifying something like an - extended YAML-LD document form - making use of YAML-specific features. -
    -
    -

    - When used as a media type parameter [[RFC4288]] - in an HTTP Accept header field [[RFC9110]], - the value of the profile parameter MUST be enclosed in quotes (") if it contains - special characters such as whitespace, which is required when multiple profile URIs are combined.

    -

    When processing the "profile" media type parameter, it is important to - note that its value contains one or more URIs and not IRIs. In some cases - it might therefore be necessary to convert between IRIs and URIs as specified in - section 3 Relationship between IRIs and URIs - of [[RFC3987]].

    -
    -
    -
    -
    Encoding considerations:
    -
    See YAML media type.
    -
    Security considerations:
    -
    See .
    -
    Interoperability considerations:
    -
    See .
    -
    Published specification:
    -
    http://www.w3.org/TR/yaml-ld
    -
    Applications that use this media type:
    -
    Any programming environment that requires the exchange of - directed graphs. Implementations of YAML-LD have been created for - FIXME. -
    -
    Additional information:
    -
    -
    -
    Magic number(s):
    -
    See application/yaml
    -
    File extension(s):
    -
    .yamlld
    -
    Macintosh file type code(s):
    -
    TEXT
    -
    -
    -
    Person & email address to contact for further information:
    -
    Philippe Le Hégaret <plh@w3.org>
    -
    Intended usage:
    -
    Common
    -
    Restrictions on usage:
    -
    N/A
    -
    Author(s):
    -
    Roberto Polli, Gregg Kellogg
    -
    Change controller:
    -
    W3C
    -
    -
    + 
    +    
+
    -
    -

    Fragment identifiers

    -

    Fragment identifiers used with application/ld+yaml - are treated as in RDF syntaxes, as per - RDF 1.1 Concepts and Abstract Syntax - [[RDF11-CONCEPTS]] - and do not follow the process defined for application/yaml. -

    +

    + Although allowed within the YAML Grammar, some current YAML parsers + do not allow the use of `"#"` within a tag URI. Substituting + the `"%23"` escape is a workaround for this problem, that will + hopefully become unnecessary as implementations are updated. +

    - -
    Perhaps more on fragment identifiers from Issue 13
    +
    +

    A concrete proposal in that direction would be to use a tag at the + top-level of any "idiomatic" YAML-LD document, applying to the whole + object/array that makes the document.

    -
    -
    -

    Examples

    -

    FIXME

    -
    -
    +

    It might also include a version + to identify the specification that it relates to, allowing + for version announcement that could be used for future-proofing.

    -
    -

    REMOVE THIS SECTION BEFORE PUBLICATION.

    +

    The following block is one example:

    -

    FAQ

    + 
    +      !yaml-ld
+      $context: http://schema.org/
+      $type: Person
+      name: Pierre-Antoine Champin
+
    + - #### Why does YAML-LD not preserve comments? -
    - According to [[YAML]], information that does not reflect - into the representation graph (e.g., comments, directives, mapping keys order, - anchor names, ...) must not be used to convey application level information. - Moreover - [[JSON]] (and hence [[JSON-LD11]]) does not support comments, - and other Linked Data serialization formats - that support comments (such as [[?TURTLE]]) - do not provide a means to preserve them - when processing and serializing the document - in other formats. - The proposed behavior is thus consistent with - other implementations. +

    See for an example + of serializing the extended internal representation.

    - While YAML-LD could define a specific predicate for comments, - that is insufficient because, for example, - the order of keywords is not preserved in JSON, so the - comments could be displaced. - This specification does not provide a means for preserving - [[YAML]] comments after a JSON serialization. +
    +

    Converting From the Internal Representation

    - 
    -      
-
    +
      +
    1. + If |n| is an array, + the conversion result is a YAML sequence + with child nodes of the sequence taken by converting + each value of |n| using this algorithm. +
      2. +
    2. + Otherwise, if |n| is an map, + the conversion result is a YAML mapping + with keys and values taken by converting each + key/value pair of |n| using this algorithm. +
      3. +
    3. + Otherwise, if |n| is an RDF literal: +
        +
      1. + If the datatype IRI + of |n| is `xsd:string`, + the conversion is a YAML scalar + with the value taken from that value of |n|. +
        2. +
      2. Otherwise, if |n| is a language-tagged string, + the conversion is a YAML scalar + with the value taken from that value of |n| + and a node tag constructed by appending + that language tag to + `https://www.w3.org/ns/i18n#`. +
        3. +
      3. + Otherwise, the conversion is a YAML scalar + with the value taken from that value of |n| + and a node tag taken from the + datatype IRI of |n|. +
        4. +
      +
      4. +
    4. + Otherwise, if |n| is a number, + the conversion result is a YAML scalar + with the value taken from |n|. +
      5. +
    5. + Otherwise, if |n| is a boolean, + the conversion result is a YAML scalar + with the value either `true` or `false` + based on the value of |n|. +
      6. +
    6. + Otherwise, if |n| is null, + the conversion result is a YAML scalar + with the value `null`. +
      7. +
    7. + Otherwise, conversion result is a YAML scalar + with the value taken from |n|. +
      8. +
    +
    +
    - Transforming the above entry into a JSON-LD document - results in: +
    +

    Application Profiles

    - 
    -      
-
    - +

    This section identifies two application profiles for operating with + YAML-LD:

    + - #### Why does YAML-LD not extend the JSON-LD data model ? -
    - [[JSON]] only represents simple trees while [[YAML]] can support - rooted, directed graphs with references and cycles. +

    Application profiles allow publishers to use YAML-LD + either for maximum interoperability, + or for maximum expressivity. + The YAML-LD JSON profile provides for complete round-tripping + between YAML-LD documents and JSON-LD documents. + The YAML-LD extended profile allows for + fuller use of YAML features to enhance the ability to + represent a larger number of native datatypes + and reduce document redundancy.

    + + +

    Application profiles can be set using the {{JsonLdProcessor}} + API interface, as well as an HTTP request profile (see ).

    + +
    +

    YAML-LD JSON Profile

    + +

    + The YAML-LD JSON profile + is based on the YAML Core Schema, + which interprets only a limited set of node tags. + YAML scalars with node tags outside of the defined range + SHOULD be avoided and MUST be converted to the closest + scalar type from the YAML Core Schema, + if found. + See + for specifics. +

    - The above structures cannot be preserved when serializing - to JSON-LD and - with respect to cycles - the serialization - will fail. +

    + Although YAML supports several additional encodings, + YAML-LD documents in the YAML-LD JSON Profile + MUST NOT use encodings other than UTF-8. +

    - Programming languages such as Java and Python already support - YAML representation graphs, but these implementations may behave - differently. - In the following example, `&value` references the value - of the keyword `value`. +

    + Keys used in a YAML mapping MUST be strings. +

    - 
    -      
-
    +

    + Although YAML-LD documents MAY include node anchors, + documents MUST NOT use alias nodes. +

    - Processing this entry in Python, I get the following - structure that preserve the references to - mutable objects (e.g., the `temperature` dict) - but not to scalars (e.g., the `value` keyword). +

    + A YAML stream MUST include only a single YAML document, + as the JSON-LD internal representation only supports + a single document model. +

    +
    - 
    -      
-
    +
    +

    YAML-LD Extended Profile

    - Since all these implementations pre-date this - specification, some more interoperable choices include the following: +

    + The YAML-LD extended profile + extends the YAML Core Schema, + allowing node tags to specify RDF literals + by using a JSON-LD extended internal representation capable + of directly representing RDF literals. +

    - * forbidding cycles in YAML-LD documents - * considering all references in YAML-LD as static, - i.e., a shorthand way to repeat specific patterns +

    + As with the YAML-LD JSON profile, + YAML-LD documents in the YAML-LD extended profile + MUST NOT use encodings other than UTF-8. +

    -
    -
    -
    -

    Best Practices

    +

    + As with the YAML-LD JSON profile, + keys used in a YAML mapping MUST be strings. +

    -

    Here, we propose to YAML-LD users a bit of advice which, although optional, might suggest one or two - useful thoughts.

    +

    + YAML-LD docucments MAY use alias nodes, + as long as dereferencing these aliases does not result in a loop. +

    -
    -

    - 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-LD11]]. +

    + As with the YAML-LD JSON profile, + a YAML stream MUST include only a single YAML document, + as the JSON-LD extended internal representation only supports + a single document model.

    -
    -
    -

    - Do not force users to author contexts +

    + Consier something like `!id` as a local tag to denote IRIs. +

    - Instead, provide pre-built contexts that the user can reference by URL for a majority of common use cases. -

    -
    +
    +

    The JSON-LD Extended Internal Representation

    -

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

    +

    + This specification defines + the + JSON-LD extended internal representation + , an extension + of the JSON-LD internal representation. +

    -
    -

    - Use a default context -

    +

    + In addition to maps, arrays, and strings, + the internal representation allows native representation + of numbers, boolean values, and nulls. + The extended internal representation allows for native + representation of RDF literals, both + with a datatype IRI, + and language-tagged strings. +

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

    + When transforming from the extended internal representation + to the internal representation — + for example when serializing to JSON + or to the YAML-LD JSON profile — + implementations MUST transform RDF literals to the closest + native representation of the internal representation: +

    -

    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.

    + + +

    + An alternative would be to transform such literals to + JSON-LD value objects, + and we may want to provide a means of transforming between + the internal representation + and extended internal representation + using value objects, + but this treatment is consistent with + [[YAML]] Core Schema + Tag Resolution. +

    +
    +
    +
    -
    -

    - Alias JSON-LD keywords +

    +

    The Application Programming Interface

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

    + This specification extends the [[[JSON-LD11-API]]] [[JSON-LD11-API]] + + Application Programming Interface + + and the [[[JSON-LD11-FRAMING]]] [[JSON-LD11-FRAMING]] + + Application Programming Interface + + to manage the serialization and deserialization of [[YAML]] + and to enable an option for setting the + YAML-LD extended profile.

    -
    -

    The `@` character is reserved in YAML, and thus requires quoting (or escaping), as in the following - example:

    +
    +

    JsonLdProcessor

    + +

    + The + JSON-LD Processor + interface is the high-level programming structure that developers + use to access the JSON-LD transformation methods. + The updates below is an experimental + extension of the {{JsonLdProcessor}} interface defined in the + JSON-LD 1.1 API [[JSON-LD11-API]] + to serialize output as YAML rather than JSON. +

    - 
    -        
+          
    
+            
    {{JsonLdProcessor/compact()}}
    
+            
    
+              Updates step 10 of the {{JsonLdProcessor/compact()}} algorithm
+              to serialize the the result as YAML rather than JSON
+              as defined in .
+            
    
+            
    {{JsonLdProcessor/expand()}}
    
+            
    
+              Updates step 9 of the {{JsonLdProcessor/expand()}} algorithm
+              to serialize the the result as YAML rather than JSON
+              as defined in .
+            
    
+            
    {{JsonLdProcessor/flatten()}}
    
+            
    
+              Updates step 7 of the {{JsonLdProcessor/flatten()}} algorithm
+              to serialize the the result as YAML rather than JSON
+              as defined in .
+            
    
+            
    
+              Updates step 22 of the
+              frame()
+              algorithm to serialize the the result as YAML rather than JSON
+              as defined in .
+            
    
+            
    {{JsonLdProcessor/fromRdf()}}
    
+            
    
+              Updates step 3 of the {{JsonLdProcessor/fromRdf()}} algorithm
+              to serialize the the result as YAML rather than JSON
+              as defined in .
+            
    
+            
    
+              Updates the
+              RDF to Object Conversion algorithm
+              before step 2.6 as follows:
+              
    
+                Otherwise, if both the {{JsonLdOptions/useNativeTypes}}
+                and {{JsonLdOptions/extendedYAML}} flags are set
+                and the
+                datatype IRI
+                of |value| is not `xsd:string`:
+                
      
+                  
    1. 
+                    If |value| is a language-tagged string
+                    set |converted value| to a new RDF literal
+                    composed of the
+                    lexical form
+                    of |value| and
+                    datatype IRI
+                    composed of `https://www.w3.org/ns/i18n#` followed by
+                    the
+                    language tag
+                    of |value|.
+                  
      2. 
+                  
    2. 
+                    Otherwise, et |converted value| to |value|.
+                  
      3. 
+                
    
+              
    
+            
    
+            
    {{JsonLdProcessor/toRdf()}}
    
+            
    
+              Updates the
+              Object to RDF Conversion algorithm
+              before step 10 as follows:
+              
    
+                
      
+                  
    1. 
+                    Otherwise, if |value| is an RDF literal,
+                    |value| is left unmodified.
+                    
+                  This will only be the case when processing a value from an
+                  extended internal representation.
+                
+                  
      2. 
+                
    
+              
    
+            
    
+          
    
+
    + +
    +

    JsonLdOptions

    +

    The {{JsonLdOptions}} type is used to pass various options to the + {{JsonLdProcessor}} methods.

    + + 
    +        partial dictionary JsonLdOptions {
+          boolean extendedYAML = false;
+        };
    -

    The need to quote these keywords has to be learnt, and introduces one more little irregularity to the document - author's life. Further, on most keyboard layouts, typing quotes will require `Shift`, which reduces typing speed, - albeit slightly.

    +

    + In addition to those options defined in the + JSON-LD 1.1 API [[JSON-LD11-API]] + and JSON-LD 1.1 Framing [[JSON-LD11-FRAMING]], + this specification defines these additional options: +

    -

    In order to avoid this, the context might introduce custom mappings for the necessary keywords. For instance, - [[schema-org]] context redefines `@id` as just `id` — which seems to be much more convenient to type, and - no more difficult to remember.

    +
    +
    extendedYAML
    +
    + When used for serializing the internal representation + (or extended internal representation) + into a YAML representation graph: + + +
    +
    + When used for the {{documentLoader}}, + it causes documents of type `application/ld+yaml` + to be parsed into a YAML representation graph + and generates an internal representation + (or extended internal representation): + + +
    +
    +
    + +
    +

    Remote Document and Context Retrieval

    + +

    This section describes an update to the + built-in {{LoadDocumentCallback}} + to load YAML streams and documents + into the internal representation, + or into the extended internal representation + if the {{JsonLdOptions/extendedYAML}} API flag is `true`.

    + +

    + The {{LoadDocumentCallback}} algorithm in [[JSON-LD11-API]] + is updated as follows: +

    -
    -

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

    -
    +
      +
    • + Step 2 + is updated to prefer + Content-Type `application/ld+yaml`, + followed by `application/yaml`, + followed by the other specified + Content-Types. +
      • +
    • + After step 5, + add the following processing step: + Otherwise, if the retrieved resource's + Content-Type + is either `application/yaml` + or any media type with a `+yaml` suffix as defined in [[RFC6839]] + transform |document| to the internal representation + (or extended internal representation) + as described in . + Additionally, if the {{RemoteDocument/profile}} parameter + includes `http://www.w3.org/ns/json-ld#extended`, set the {{JsonLdOptions/extendedYAML}} option to `true`. +
      • +
    - +

    + These updates are intended to be compatible with other updates + to the {{LoadDocumentCallback}}, such as + Process HTML + as defined in [[JSON-LD11-API]]. +

    +
    -

    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:

    +
    +

    YamlLdErrorCode

    +

    The YamlLdErrorCode represents the collection of valid YAML-LD error codes, + which extends the {{JsonLdErrorCode}} definitions.

    - 
    -        
+          
    +        enum YamlLdErrorCode {
+          "invalid-encoding",
+          "mapping-key-error",
+          "profile-error"
+        };
       
    
 
-      
    The applicability of this context depends on the domain and is left to the architect's best judgement.
    
-
    - +
    +
    invalid-encoding
    +
    The character encoding of an input is invalid.
    +
    mapping-key-error
    +
    A YAML mapping key was found that was not a string.
    +
    profile-error
    +
    The parsed YAML document contains features incompatible with the specified profile.
    +
    +
    +
    - +
    +