From b8ac517bec1c7313610cc560a3ac95a91ea16c1f Mon Sep 17 00:00:00 2001 From: Gregg Kellogg Date: Thu, 24 Oct 2024 09:14:58 -0700 Subject: [PATCH] Add candidate change and insertions relating to previously merged class-3 changes. (#616) * Add candidate change and insertions for #380/#388. * Reorder change details with newest first. * Comment out 2021-01-05 editorial changes to node-map-generation algorithm. * Comment out 2021-02-25 editorial changes to IRI expansion algorithm. * Add Candidate Correction 2 for issue #514. * CANDIDATE CORRECTION 3 for issue 565, PR 566 to "Fix context processing for reverse terms". * CANDIDATE CORRECTION 4 for `extractAllScripts` option to `toRdf()`. --- index.html | 495 +++++++++++++++++++++++++++++------------------------ 1 file changed, 270 insertions(+), 225 deletions(-) diff --git a/index.html b/index.html index 77e59586..f860ab89 100644 --- a/index.html +++ b/index.html @@ -302,16 +302,19 @@ with documents created using [[[JSON-LD10]]] [[JSON-LD10]].

-
+

This document has been developed by the JSON-LD Working Group and was derived from the JSON-LD Community Group's Final Report.

There is a live JSON-LD playground that is capable of demonstrating the features described in this document.

- +

This specification is intended to supersede the [[[JSON-LD10-API]]] [[JSON-LD10-API]] specification.

+

+ This document includes Candidate Corrections to the current + W3C Recommendation dated 16 July 2020.

Set of Documents

@@ -1623,7 +1626,7 @@

Algorithm

  • Otherwise, if the expanded type is neither @id, nor @json, nor @none, - nor @vocab, + nor @vocab, nor an IRI, an invalid type mapping error has been detected and processing is aborted.
    • @@ -1631,6 +1634,11 @@

    Algorithm

  • If value contains the entry @reverse: +
    + Candidate Correction 3 +

    This changes the algorithm for processing a reverse term so that it doesn't return early. + For more information, refer to issue 565.

    +
    1. If value contains @id or @nest, entries, an invalid reverse property @@ -1664,10 +1672,10 @@

      Algorithm

    2. Set the term definition of term in active context to definition and the value associated with defined's entry term to - true.
      3. + true and return.
    • -
  • Otherwise, if value contains the entry @id and its value +
  • Otherwise, ifIf value contains the entry @id and its value does not equal term:
    1. If the @id entry of value @@ -1894,7 +1902,7 @@

      Algorithm

    2. If value contains any entry other than @id, @reverse, @container, - @context, + @context, @direction, @index, @language, @@ -2961,7 +2969,7 @@

      Algorithm

      IRI expanding index key.
    3. Initialize index property values to an array consisting of re-expanded index followed - by the existing values of + by the existing values of the concatenation of expanded index key in item, if any.
    4. Add the key-value pair (expanded index key-index property values) @@ -3068,12 +3076,23 @@

      Algorithm

      nested value expands to @value, an invalid @nest value error has been detected and processing is aborted.
      5. -
    5. Recursively repeat steps - 3, - 8, +
    6. +
      + Candidate Correction 1 +

      This algorithm step omitted two additional steps + which include nesting-key in addition to nested value. + For more information, refer to issue 380.

      +
      + Recursively repeat steps + + 3, + 8, + 13, - and 14 - using nesting-key for active property, and + and 14 using + + nesting-key for active property, and + nested value for element.
      Steps 3 and 8 @@ -3810,7 +3829,7 @@

      Algorithm

    7. Use add value to add compacted item to the item active property entry in nest result using as array.
      8. -
    +
  • Otherwise, container does not include @graph or otherwise does not match one of the previous cases. @@ -3862,9 +3881,15 @@

    Algorithm

    set map key to the value of @index in expanded item, if any.
  • Otherwise, if container includes @index and index key is not @index: +
    + Candidate Correction 2 +

    The value of `@index` on a property map can be a Compact IRI in addition to an IRI. + The Compaction Algorithm is updated to first expand this value before re-compacting it. + For more information, refer to issue 380.

    +
    1. Reinitialize container key by IRI compacting - index key after first IRI expanding it.
      2. + index key after first IRI expanding it.
    2. Set map key to the first value of container key in compacted item, if any.
    3. If there are remaining values in compacted item for container key, use add value to @@ -5837,7 +5862,7 @@

      Algorithm

      from remote document, if available; otherwise to the {{JsonLdOptions/base}} option from options. If set, the {{JsonLdOptions/base}} option from options overrides the base IRI.
      4. -
    4. If the {{JsonLdOptions/expandContext}} option in options is set, +
    5. If the {{JsonLdOptions/expandContext}} option in options is set, update the active context using the Context Processing algorithm, passing the {{JsonLdOptions/expandContext}} as local context and the original base URL from active context as base URL. @@ -6001,6 +6026,13 @@

      Algorithm

      Transforms the given input into an RdfDataset according to the steps in the Deserialize JSON-LD to RDF Algorithm:

      +
      + Candidate Correction 4 +

      This changes the default for extractAllScripts to be `false`, + which is consistent with the wording in Embedding JSON-LD in HTML Documents in [[JSON-LD11]]. + For more information, refer to issue 603.

      +
      +
      1. Create a new {{Promise}} promise and return it. The following steps are then deferred.
        2. @@ -6008,8 +6040,8 @@

        Algorithm

        expand() method using input and options - with {{JsonLdOptions/ordered}} set to false, - and {{JsonLdOptions/extractAllScripts}} defaulting to true. + with {{JsonLdOptions/ordered}} set to false, + and {{JsonLdOptions/extractAllScripts}} defaulting to true.
      2. Create a new RdfDataset dataset.
      3. Create a new map node map.
      4. Invoke the Node Map Generation algorithm, @@ -6544,7 +6576,7 @@

        RemoteDocument

        1. If the extractAllScripts option is not present, or false, the promise is rejected with a JsonLdError whose {{JsonLdError/code}} is set to loading document failed - and processing is terminated.
          2. + and processing is terminated.
        2. Otherwise, the extractAllScripts option is true. Set document to a new empty array. For each JSON-LD script element in input: @@ -6838,187 +6870,57 @@

          JsonLdErrorCode

          relative iri compaction.

    • -

    Changes since 1.0 Recommendation of 16 January 2014

    - -

    Additionally, see .

    -
    +
    +

    Change log

    +

    Note that this change log only identifies substantive changes since [[[JSON-LD10-API]]].

    -

    Changes since JSON-LD Community Group Final Report

    +
    + Substantive changes since Recommendation of 16 July 2020
      -
    • Lists may now have items which are themselves lists.
      • -
    • The Deserialize JSON-LD to RDF Algorithm - has been updated to ensure that only well-formed triples - are emitted; previously, it only ensured that triples containing - relative IRI references were excluded.
      • -
    • The API now adds an {{JsonLdOptions/ordered}} - option, defaulting to false This is used in algorithms to - control iteration of map entry keys. Previously, the - algorithms always required such an order. The instructions for - evaluating test results have been updated accordingly.
      • -
    • The Generate Blank Node Identifier algorithm - has been updated to remove the specifics of how new blank node - identifiers are created.
      • -
    • Values of @type, or an alias of @type, may now have their @container set to @set - to ensure that @type entries are always represented as an array. This - also allows a term to be defined for @type, where the value MUST be a map - with @container set to @set.
      • -
    • Updated the IRI Expansion algorithm so that - if value contains a colon (:), but - prefix is not a term, to only return value - if it has the form of an IRI, otherwise fall through to - the rest of the algorithm.
      • -
    • The use of blank node identifiers to label properties is obsolete, - and may be removed in a future version of JSON-LD, - as is the support for generalized RDF Datasets - and thus the {{JsonLdOptions/produceGeneralizedRdf}} option may be also be removed.
      • -
    • Added API steps to accept text/html as input, - extracting either a specifically targeted script element, - the first found JSON-LD script element, - or all JSON-LD script elements.
      • -
    • Added {{RemoteDocument/contentType}} field to RemoteDocument.
      • -
    • Added support for protected contexts and term definitions.
      • -
    • Because scoped contexts can lead to contexts being reloaded, replace the - recursive context inclusion error with a context overflow error.
      • -
    • Added support for "@type": "@none" in a term definition to prevent value compaction.
      • -
    • Added support for JSON literals.
      • -
    • Term definitions with keys which are of the form of an IRI or a compact IRI MUST NOT - expand to an IRI other than the expansion of the key itself.
      • -
    • Consolidate RemoteDocument processing into the LoadDocumentCallback - including variations on HTML processing.
      • -
    • The IRI Compaction algorithm may generate an error if the result is an - IRI which could be confused with a compact IRI in the - active context.
      • -
    • By default, all contexts are propagated when traversing node objects, other than - type-scoped contexts. This can be controlled using the @propagate - entry in a local context.
      • -
    • A context may contain a @import entry used to reference a remote context - within a context, allowing JSON-LD 1.1 features to be added to contexts originally - authored for JSON-LD 1.0.
      • -
    • The colliding keywords error is not issued for `@type`; - instead, previous values of `@type` are prepended to any new values, when expanding.
      • -
    • A node object may include an included block, - which is used to contain a set of node objects which are treated - exactly as if they were node objects defined in an array including the containing - node object. - This allows the use of the object form of a JSON-LD document when there is more - than one node object being defined, and where those node objects - are not embedded as values of the containing node object.
      • -
    • A relative IRI reference has been added as a possible value for @vocab in - a context. When this is set, vocabulary-relative IRI references, such as the - entries of node objects, are expanded or compacted relative - to the base IRI and the vocabulary mapping using string concatenation.
      • -
    • In the LoadDocumentCallback, if the retrieved content is not any JSON media type - and there is a link header with `rel=alternate` and `type=application/ld+json`, redirect - to that content.
      • -
    • Value objects, and associated context and term definitions have been updated to - support `@direction` for setting the base direction of strings.
      • -
    • It is no longer required that language tags be normalized to lower case, - other than for testing considerations. - Language tags that are not valid according to [[BCP47]] are rejected.
      • -
    • The processing mode is now implicitly `json-ld-1.1`, unless set - explicitly to `json-ld-1.0`.
      • -
    • Improve notation using IRI, IRI reference, and relative IRI reference.
      • -
    • Ignore terms and IRIs that have the form of a keyword (`"@"1*ALPHA`).
      • + + + +
    • 2020-02-23: Added some clarifications to + as described in Candidate Correction 1.
      • + +
    • 2021-05-15: Added additional language to the + Compaction Algorithm + step 12.8.9.6.1 to first expand + container key before compacting it, + as described in Candidate Correction 2.
      • +
    • 2023-06-28: Changed the Create Term Definition + in section 4.2 of the Context Processing Algorithms, to ensure that all + possible features for reverse term definitions are processed. The change + was to remove and return from the end of step 13, and revise step + 14 to begin with Otherwise, + as described in Candidate Correction 3.
      • + + +
    • 2024-07-10: Specify that the value of extractAllScripts + in toRdf() + defaults to `true`, rather than `false`. + This is consistent with wording in + Embedding JSON-LD in HTML Documents [[JSON-LD11]] + for treating script elements as a single document, + as described in Candidate Correction 4.
    -
    -
    -

    Changes since Candidate Release of 12 December 2019

    + + +
    + Changes since Proposed Recommendation Release of 7 May 2020

    All changes are editorial and do not affect the observable behavior of the API nor the expected test results.

      -
    • Add `application/xhtml+xml` as an allowed media type in , - in the note in , - and as a use of the {{LoadDocumentOptions/profile}} API option.
      • -
    • Added add value, IRI expanding, and IRI compacting - macros to reduce boilerplate in algorithmic language.
      • -
    • Improved algorithms in - , - , - , - , - , - , - and . -
      • -
    • When creating an `i18n` datatype or `rdf:CompoundLiteral`, language tags are - normalized to lower case to improve interoperability between implementations.
      • -
    • Moved non-recursive portions algorithms - into the {{JsonLdProcessor}} processing steps.
      • -
    • Fix some {{JsonLdOption}} initializers where defaults are `null`. - Set default value for processingMode to `json-ld-1.1`.
      • -
    • Remove normative text for canonicalizing `rdf:JSON` literals and - reference the `rdf:JSON` datatype of the syntax document - for the conversion of the JSON Literals in .
      • -
    • Updated interfaces in - to use record, - instead of dictionary, - and to allow RemoteDocument to be used - as a direct input, which resolves a {{Promise}} boundary issue.
      • + + +
    -
    -
    -

    Changes since Candidate Release of 05 March 2020

    -

    All changes are editorial and do not affect the observable - behavior of the API nor the expected test results.

    + + +
    + Substantive changes since Candidate Recommendation of 05 March 2020
    • The inverse context is not passed explicitly as a parameter to the Term Selection, @@ -7089,44 +6991,187 @@

      Changes since Candidate Release of 05 March 2020

    • Added to describe the `preserve` keyword, which is only used for framing.
    -
    -
    -

    Changes since Proposed Recommendation Release of 7 May 2020

    + + +
    + Substantive changes since Candidate Recommendation of 12 December 2019
      -
    • Removed remaining "at-risk" notes.
      • -
    • Update bibliographic reference for JCS to [[RFC8785]].
      • -
    • Changed `[Exposed=(Window,Worker)]` to `[Exposed=JsonLd]`, - which is declared as a global interface in order to expose the {{JsonLdProcessor}} interface - for non-browser usage to address review suggestions.
      • +
    • Add `application/xhtml+xml` as an allowed media type in , + in the note in , + and as a use of the {{LoadDocumentOptions/profile}} API option.
      • + +
    • Improved algorithms in + , + , + , + , + , + , + and . +
      • +
    • When creating an `i18n` datatype or `rdf:CompoundLiteral`, language tags are + normalized to lower case to improve interoperability between implementations.
      • +
    • Moved non-recursive portions algorithms + into the {{JsonLdProcessor}} processing steps.
      • +
    • Fix some {{JsonLdOption}} initializers where defaults are `null`. + Set default value for processingMode to `json-ld-1.1`.
      • +
    • Remove normative text for canonicalizing `rdf:JSON` literals and + reference the `rdf:JSON` datatype of the syntax document + for the conversion of the JSON Literals in .
      • +
    • Updated interfaces in + to use record, + instead of dictionary, + and to allow RemoteDocument to be used + as a direct input, which resolves a {{Promise}} boundary issue.
    -
    -
    -

    Changes since Recommendation of 16 July 2020

    + + +
    + Substantive changes since the Community Group Final Report of 07 June 2018
      -
    • Regenerated definition list, which does not attempt to filter out unused definitions.
      • -
    • Changed obsolete use of `void` in WebIDL to `undefined`.
      • -
    • Added some clarifications to the algorithm of .
      • -
    • Added some clarifications to the algorithm of .
      • -
    • Added additional language to the - Compaction Algorithm - step 12.8.9.6.1 to first expand - container key before compacting it.
      • -
    • - Changed the Create Term Definition - in section 4.2 of the Context Processing Algorithms, to ensure that all - possible features for reverse term definitions are processed. The change - was to remove and return from the end of step 13, and revise step - 14 to begin with Otherwise.
      • -
    • Use code point order as a better definition for the more vague "lexicographical order".
      • -
    • Remove spurious paragraph in the description of {{JsonLdOptions/frameExpansion}}
      • -
    • Specify that the value of extractAllScripts - in toRdf() - defaults to `true`, rather than `false`. - This is consistent with wording in - Embedding JSON-LD in HTML Documents [[JSON-LD11]] - for treating script elements as a single document.
      • +
    • Lists may now have items which are themselves lists.
      • +
    • The Deserialize JSON-LD to RDF Algorithm + has been updated to ensure that only well-formed triples + are emitted; previously, it only ensured that triples containing + relative IRI references were excluded.
      • +
    • The API now adds an {{JsonLdOptions/ordered}} + option, defaulting to false This is used in algorithms to + control iteration of map entry keys. Previously, the + algorithms always required such an order. The instructions for + evaluating test results have been updated accordingly.
      • +
    • The Generate Blank Node Identifier algorithm + has been updated to remove the specifics of how new blank node + identifiers are created.
      • +
    • Values of @type, or an alias of @type, may now have their @container set to @set + to ensure that @type entries are always represented as an array. This + also allows a term to be defined for @type, where the value MUST be a map + with @container set to @set.
      • +
    • Updated the IRI Expansion algorithm so that + if value contains a colon (:), but + prefix is not a term, to only return value + if it has the form of an IRI, otherwise fall through to + the rest of the algorithm.
      • +
    • The use of blank node identifiers to label properties is obsolete, + and may be removed in a future version of JSON-LD, + as is the support for generalized RDF Datasets + and thus the {{JsonLdOptions/produceGeneralizedRdf}} option may be also be removed.
      • +
    • Added API steps to accept text/html as input, + extracting either a specifically targeted script element, + the first found JSON-LD script element, + or all JSON-LD script elements.
      • +
    • Added {{RemoteDocument/contentType}} field to RemoteDocument.
      • +
    • Added support for protected contexts and term definitions.
      • +
    • Because scoped contexts can lead to contexts being reloaded, replace the + recursive context inclusion error with a context overflow error.
      • +
    • Added support for "@type": "@none" in a term definition to prevent value compaction.
      • +
    • Added support for JSON literals.
      • +
    • Term definitions with keys which are of the form of an IRI or a compact IRI MUST NOT + expand to an IRI other than the expansion of the key itself.
      • +
    • Consolidate RemoteDocument processing into the LoadDocumentCallback + including variations on HTML processing.
      • +
    • The IRI Compaction algorithm may generate an error if the result is an + IRI which could be confused with a compact IRI in the + active context.
      • +
    • By default, all contexts are propagated when traversing node objects, other than + type-scoped contexts. This can be controlled using the @propagate + entry in a local context.
      • +
    • A context may contain a @import entry used to reference a remote context + within a context, allowing JSON-LD 1.1 features to be added to contexts originally + authored for JSON-LD 1.0.
      • +
    • The colliding keywords error is not issued for `@type`; + instead, previous values of `@type` are prepended to any new values, when expanding.
      • +
    • A node object may include an included block, + which is used to contain a set of node objects which are treated + exactly as if they were node objects defined in an array including the containing + node object. + This allows the use of the object form of a JSON-LD document when there is more + than one node object being defined, and where those node objects + are not embedded as values of the containing node object.
      • +
    • A relative IRI reference has been added as a possible value for @vocab in + a context. When this is set, vocabulary-relative IRI references, such as the + entries of node objects, are expanded or compacted relative + to the base IRI and the vocabulary mapping using string concatenation.
      • +
    • In the LoadDocumentCallback, if the retrieved content is not any JSON media type + and there is a link header with `rel=alternate` and `type=application/ld+json`, redirect + to that content.
      • +
    • Value objects, and associated context and term definitions have been updated to + support `@direction` for setting the base direction of strings.
      • +
    • It is no longer required that language tags be normalized to lower case, + other than for testing considerations. + Language tags that are not valid according to [[BCP47]] are rejected.
      • +
    • The processing mode is now implicitly `json-ld-1.1`, unless set + explicitly to `json-ld-1.0`.
      • +
    • Improve notation using IRI, IRI reference, and relative IRI reference.
      • +
    • Ignore terms and IRIs that have the form of a keyword (`"@"1*ALPHA`).
    +
    + +
    + Substantive changes since the Recommendation of 16 January 2014 + +
    +