diff --git a/spec/index.html b/spec/index.html index 2a9cc3e..a2274a0 100644 --- a/spec/index.html +++ b/spec/index.html @@ -1295,23 +1295,35 @@

Motivation

Linked Data in a more expressive way.

+

+ In the cases described above, one of the possible expressive methods is a + specific feature of YAML language. To leverage those methods, we propose an + Extended YAML-LD Profile which will implement all such features. +

+

Specify node @type

-

In RDF, @type translates to one of the following:

+

+ When converting JSON-LD to RDF, @type translates to + one of the following: +

Possible ways to specify this in YAML-LD are the following:

-

…

- -

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

- -

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

- -

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

- -

- The YAML-LD extended profile allows full use of - anchor names and alias nodes subject to - the requirements described above in this section. -

- -

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

- -

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

+
+

+ Two alternative approaches have been proposed to implement the Extended profile: +

-
-

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.

- -
-

A YAML flow sequence:

- 
-        
-
- - -

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

+
+

Extended Internal Representation

-

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

+ This approach implies 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.

-

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

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

-
-

Converting a YAML stream

- -

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

- -

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

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

-
- -
-

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

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

    - +

    + The YAML-LD extended profile allows full use of + anchor names and alias nodes subject to + the requirements described above in this section. +

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

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

-

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

-
+ extended-manifest.html#aa-cycles-1-positive"> + 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. +

-
-

Converting a YAML sequence

-

Both block sequences and flow sequences - are directly aligned with - an array in the 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 + . +

-

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

-
+

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

-
-

Converting a YAML mapping

+

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

-

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

+
+

Converting a YAML stream

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

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

-

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

-
+

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

-
-

Converting a YAML scalar

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

+
-

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

-
+
+

Converting a YAML document

-
-

Converting a YAML alias node

+

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

-

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

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

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

+
-

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

+
+

Converting a YAML sequence

-

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

-
-
+

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

-
-

Conversion to YAML

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

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

+

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

+
-

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

+
+

Converting a YAML mapping

-

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

+

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

-

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

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

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

+
- 
-    
-
+
+

Converting a YAML scalar

-

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

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

+
-
-

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.

+
+

Converting a YAML alias node

-

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.

+

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

-

The following block is one example:

+

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

- 
-      !yaml-ld
-      $context: http://schema.org/
-      $type: Person
-      name: Pierre-Antoine Champin
-
-
+

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

+
+
-

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

+
+

Conversion to YAML

-
-

Converting From the Internal Representation

+

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

- This algorithm describes the steps to convert - each element from the internal representation - into corresponding YAML nodes by recursively - processing each element |n|. + 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.

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

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

-
-

Application Profiles

+

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

-

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

- + 
+      
+
-

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.

+

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

+
+

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.

-

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

+

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.

-
-

YAML-LD JSON Profile

+

The following block is one example:

-

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

+ 
+        !yaml-ld
+        $context: http://schema.org/
+        $type: Person
+        name: Pierre-Antoine Champin
+
+
-

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

+

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

-

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

+
+

Converting From the Internal Representation

-

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

+

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

-

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

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

YAML-LD Extended Profile

+
+

Application Profiles

-

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

+

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

+ -

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

+

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.

-

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

+

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

-

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

+
+

YAML-LD JSON Profile

-

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

+

+ 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 JSON-LD Extended Internal Representation

+

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

- This specification defines - the - JSON-LD extended internal representation - , an extension - of the JSON-LD internal representation. + Keys used in a YAML mapping MUST be strings.

- 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. + Although YAML-LD documents MAY include node anchors, + documents MUST NOT use alias nodes.

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

-

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

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

-
-
-
-
-

The Application Programming Interface

+

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

-

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

+

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

-
-

JsonLdProcessor

+

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

-

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

+

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

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

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

-
-

JsonLdOptions

-

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

+
+

The JSON-LD Extended Internal Representation

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

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

-

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

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

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

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

+

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

+
+
+
-

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 Application Programming Interface

- The {{LoadDocumentCallback}} algorithm in [[JSON-LD11-API]] - is updated as follows: + 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.

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

JsonLdProcessor

-

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

-
+

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

-
-

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"
-        };
-
+
+
{{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. +
+
+
+
+
-
-
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.
-
+
+

JsonLdOptions

+

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

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

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

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

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

+
+ +
+

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"
+          };
+
+ +
+
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.
+
+
+ +
+ +
+

Convert Extended YAML-LD to Basic YAML-LD and back

+ + TODO