From 2b917877b5447dc550709eb27b91f46887742808 Mon Sep 17 00:00:00 2001 From: Anatoly Scherbakov Date: Wed, 24 Jul 2024 00:04:04 +0400 Subject: [PATCH 1/3] #605 Resolve the questions about "JSON Serialization" term --- .gitignore | 2 + index.html | 252 ++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 203 insertions(+), 51 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..2c28b57d --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Support JetBrains IDEs +.idea diff --git a/index.html b/index.html index f860ab89..4d723092 100644 --- a/index.html +++ b/index.html @@ -485,7 +485,9 @@

Features

strings, numbers, booleans, and null to describe the data represented by a JSON document. Algorithms act on this internal representation with API entry points responsible for - transforming between the concrete and internal representations.

+ transforming between concrete representations and the internal representation. + See + for more details on transforming to or from the internal representation.

JSON-LD uses contexts to allow Linked Data to be expressed in a way that is specifically tailored to a particular @@ -5711,6 +5713,30 @@

Algorithm

is used instead of looking at the HTTP Link Header directly. For the sake of simplicity, none of the algorithms in this document mention this directly.

+
+ Candidate Correction 5 +

Details about transforming to and from a given serialization format + have been abstracted so that other specifications can define + serialization and deserialization requirements for their specific formats. + The algorithm is now more explicit about serializing and deserializing + to the internal representation. + See marked changes here and in the following locations:

+ +

For more information, refer to issue 605.

+
+ +

Methods resolving a {{Promise}} with the internal representation + MUST either + map it to the datatype used by the implementation, as described in , + or serialize it to JSON (or another appropriate serialization format) + as described in .

 + 
       /*
        * The JsonLd interface is created to expose the JsonLdProcessor interface.
@@ -5757,18 +5783,18 @@ 
Algorithm

           an @context entry is added to the map result.

 
         
    
-          
  1. Create a new {{Promise}} promise and return it.
+          
  2. Create a new {{Promise}} promise and return it.
             The following steps are then deferred.
    3. 
-          
  3. If the provided input
+          
  4. If the provided input
             is a RemoteDocument,
             initialize remote document to input.
    5. 
-          
  5. Otherwise, if the provided input
+          
  6. Otherwise, if the provided input
             is a string representing the IRI of a remote document, await and dereference it as remote document
             using LoadDocumentCallback, passing input
             for {{LoadDocumentCallback/url}},
             and the {{JsonLdOptions/extractAllScripts}} option from options
             for extractAllScripts.
    7. 
-          
  7. Set expanded input to the result of
+          
  8. Set expanded input to the result of
             using the expand() method
             using either remote document
             or input
@@ -5777,45 +5803,47 @@ 
    Algorithm
    
             and options,
             with {{JsonLdOptions/ordered}} set to false,
             and {{JsonLdOptions/extractAllScripts}} defaulting to false.
    9. 
-          
  9. Set context base to the {{RemoteDocument/documentUrl}}
+          
  10. Set context base to the {{RemoteDocument/documentUrl}}
             from remote document, if available, otherwise to the {{JsonLdOptions/base}} option
             from options.
    11. 
-          
  11. If context is a map
+          
  12. If context is a map
             having an @context entry,
             set context to that entry's value,
             otherwise to context.
    13. 
-          
  13. Initialize active context
+          
  14. Initialize active context
             to the result of the Context Processing algorithm
             passing a new empty context as active context
             context as local context,
             and context base as base URL.
    15. 
-          
  15. Set base IRI in active context to the {{JsonLdOptions/base}} option from options, if set;
+          
  16. Set base IRI in active context
+          to the {{JsonLdOptions/base}} option from options, if set;
             otherwise, if the compactToRelative option is true,
             to the IRI of the currently being processed document, if available;
             otherwise to null.
    17. 
-          
  17. Set compacted output to the result of using the Compaction algorithm,
-            using active context,
+          
  18. Set compacted output to the result of
+            using the Compaction algorithm,
+            with active context,
             null for active property,
             expanded input as element,
             and the {{JsonLdOptions/compactArrays}}
             and {{JsonLdOptions/ordered}}
             flags from options.
             
      
-              
    1. If compacted output is an empty array,
+              
    2. If compacted output is an empty array,
                 replace it with a new map.
      3. 
-              
    3. Otherwise, if compacted output is an array,
+              
    4. Otherwise, if compacted output is an array,
                 replace it with a new map with a single entry
                 whose key is the result of
                 IRI compacting `@graph`
                 and value is compacted output.
      5. 
-              
    5. If context was not null,
+              
    6. If context was not null,
                 add an @context entry to compacted output and set its value
                 to the provided context.
      7. 
             
    
           
    19. 
-          
  19. Resolve the promise with compacted output
-            transforming compacted output from the
-              internal representation to a JSON serialization.
    20. 
+          
  20. Resolve the promise with compacted output
+            transforming compacted output from the
+            internal representation to a JSON serialization.
    21. 
         

 
         

@@ -5842,37 +5870,40 @@ 
Algorithm

           according to the steps in the Expansion algorithm:

 
         
    
-          
  1. Create a new {{Promise}} promise and return it.
+          
  2. Create a new {{Promise}} promise and return it.
             The following steps are then deferred.
    3. 
-          
  3. If the provided input
+          
  4. If the provided input
             is a RemoteDocument,
             initialize remote document to input.
    5. 
-          
  5. Otherwise, if the provided input
+          
  6. Otherwise, if the provided input
             is a string representing the IRI of a remote document, await and dereference it as remote document
             using LoadDocumentCallback, passing input
             for {{LoadDocumentCallback/url}},
             the {{JsonLdOptions/extractAllScripts}} option from options
             for extractAllScripts.
    7. 
-          
  7. If {{RemoteDocument/document}}
-            from remote document is a string, transform into the internal representation.
+          
  8. If {{RemoteDocument/document}}
+            from remote document is a string, transform it into the internal representation
+            based on {{RemoteDocument/contentType}} from remote document,
+            (see ).
             If {{RemoteDocument/document}} cannot be transformed to the internal representation,
             reject promise passing a loading document failed error.
    9. 
-          
  9. Initialize a new empty active context.
+          
  10. Initialize a new empty active context.
             The base IRI and original base URL of the active context is set to the {{RemoteDocument/documentUrl}}
             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.
    11. 
-          
  11. If the {{JsonLdOptions/expandContext}} option in options is set,
+          
  12. 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.
             If {{JsonLdOptions/expandContext}} is a map having an @context entry,
             pass that entry's value instead for local context.
    13. 
-          
  13. If remote document has a {{RemoteDocument/contextUrl}},
+          
  14. If remote document has a {{RemoteDocument/contextUrl}},
             update the active context using the Context Processing algorithm,
             passing the {{RemoteDocument/contextUrl}} as local context,
             and {{RemoteDocument/contextUrl}} as base URL.
    15. 
-          
  15. Set expanded output to the result of using the Expansion algorithm,
+          
  16. Set expanded output to the result of
+            using the Expansion algorithm,
             passing the active context,
             {{RemoteDocument/document}} from remote document or input
             if there is no remote document as element,
@@ -5889,18 +5920,18 @@ 
    Algorithm
    
               JsonLdRecords, which are implicitly already in the
               internal representation.
             
      
-              
    1. If expanded output is a
+              
    2. If expanded output is a
                 map that contains only an @graph entry,
                 set expanded output that value.
      3. 
-              
    3. If expanded output is null,
+              
    4. If expanded output is null,
                 set expanded output to an empty array.
      5. 
-              
    5. If expanded output is not an array,
+              
    6. If expanded output is not an array,
                 set expanded output to an array containing only expanded output.
      7. 
             
    
           
    17. 
-          
  17. Resolve the promise with expanded output
-            transforming expanded output from the
-              internal representation to a JSON serialization.
    18. 
+          
  18. Resolve the promise with expanded output
+            transforming expanded output from the
+            internal representation to a JSON serialization.
    19. 
         

 
         

@@ -5923,19 +5954,19 @@ 
Algorithm

           according to the steps in the Flattening algorithm:

 
         
    
-          
  1. Create a new {{Promise}} promise and return it.
+          
  2. Create a new {{Promise}} promise and return it.
             The following steps are then deferred.
    3. 
-          
  3. If the provided input
+          
  4. If the provided input
             is a RemoteDocument,
             initialize remote document to input.
    5. 
-          
  5. Otherwise, if the provided input
+          
  6. Otherwise, if the provided input
             is a string representing the IRI of a remote document, await and dereference it as remote document
             using LoadDocumentCallback, passing input
             for {{LoadDocumentCallback/url}},
             and the {{JsonLdOptions/extractAllScripts}} option from options
             for extractAllScripts.
           
    7. 
-          
  7. Set expanded input to the result of
+          
  8. Set expanded input to the result of
             using the expand() method
             using either remote document
             or input
@@ -5943,13 +5974,13 @@ 
    Algorithm
    
             for input,
             and options
             with {{JsonLdOptions/ordered}} set to false.
    9. 
-          
  9. Initialize an empty identifier map.
    10. 
-          
  10. Set flattened output to the result of using the Flattening algorithm,
+          
  11. Initialize an empty identifier map.
    12. 
+          
  12. Set flattened output to the result of using the Flattening algorithm,
             passing expanded input as element,
             and the {{JsonLdOptions/ordered}} flag
               from options.
             
      
-              
    1. If context is not null,
+              
    2. If context is not null,
                 set flattened output to the result of
                 using the compact() method
                 using flattened output for input,
@@ -5962,10 +5993,9 @@ 
      Algorithm
      
                 otherwise to null.
      3. 
             
    
           
    13. 
-          
  13. Resolve the promise with flattened output
-            transforming flattened output from the
-              internal representation to a JSON serialization,
-              if necessary.
    14. 
+          
  14. Resolve the promise with flattened output
+            transforming flattened output from the
+            internal representation to a JSON serialization.
    15. 
         

 
         

@@ -5997,15 +6027,15 @@ 
Algorithm

           from an arbitrary input, other than the toRdf() method.

 
         
    
-          
  1. Create a new {{Promise}} promise and return it.
+          
  2. Create a new {{Promise}} promise and return it.
             The following steps are then deferred.
    3. 
-          
  3. Set expanded result to the result of invoking the
+          
  4. Set expanded result to the result of invoking the
             Serialize RDF as JSON-LD Algorithm method
             using dataset
             and options.
    5. 
-          
  5. Resolve the promise with expanded result
-            transforming expanded result from the
-              internal representation to a JSON serialization.
    6. 
+          
  6. Resolve the promise with expanded result
+            transforming expanded output from the
+            internal representation to a JSON serialization.
    7. 
         

 
         

@@ -6091,7 +6121,7 @@ 
Algorithm

       or an already dereferenced RemoteDocument.

 
     
When the value is a JsonLdRecord or sequence of JsonLdRecords,
-      the values are taken as their equivalent internal representation values,
+      the values are taken as their equivalent internal representation values,
       where a JsonLdRecord is equivalent to a map,
       and a sequence of JsonLdRecords is equivalent to an array
       of maps. The map entries are converted to their equivalents
@@ -6108,11 +6138,127 @@ 
Algorithm

       which can be dereferenced to retrieve a valid JSON document.

 
     
When the value is a JsonLdRecord or sequence of JsonLdRecords,
-      the values are taken as their equivalent internal representation values,
+      the values are taken as their equivalent internal representation values,
       where a JsonLdRecord is equivalent to a map,
       and a sequence of JsonLdRecords is equivalent to an array
       of maps. The map entries are converted to their equivalents
       in [[INFRA]].

+
+    

+      
Internal Representation in Implementations

+
+      

+        USVString,
+        JsonLdRecord,
+        sequence,
+        and other types defined in [[WebIDL]] and [[INFRA]], and used above as input and output types for
+        JsonLdProcessor functions, comprise the data structure known
+        as the internal representation.
+        JSON-LD algorithms are defined against those types.
+      

+
+      

+        Implementations map [[WebIDL]] and [[INFRA]] types to types specific to the
+        programming language in use. For instance:
+      

+
+      
+        
+          
+            
+            
+            
+            
+          
+        
+        
+          
+            
+            
+            
+            
+          
+          
+            
+            
+            
+            
+          
+          
+            
+            
+            
+            
+          
+          
+            
+            
+            
+            
+          
+          
+            
+            
+            
+            
+          
+          
+            
+            
+            
+            
+          
+          
+            
+            
+            
+            
+          
+        
+      
WebIDL TypeINFRA TypeJavaScript TypePython Type
USVStringStringStringstr
JsonLdRecordMapObjectdict
sequencelistArraylist
longinteger [[?XMLSCHEMA11-2]]Numberint
doubledouble [[?XMLSCHEMA11-2]]Numberfloat
booleanbooleanBooleanbool
nullnullNullNone

+
+      

+      The table above is only provided as an example.
+        The mappings used for a particular implementation are out of scope for
+        this specification.
+      

+    

+
+    

+      
Serialization and Deserialization

+    
+
+      
This section defines the requirements for serializing and deserializing
+        JSON from and to the internal representation, as appropriate,
+        based on the provided or requested Content-Type.
+        A Content-Type of application/json,
+        or media type with a +json suffix as defined in [[RFC6839]]
+        MUST serialize or deserialize to a format consistent with the JSON Grammar
+        as specified in [[RFC8259]].

+
+      
This specification does not define serializations of the internal representation
+        for other media types, which may be defined by other specifications.

+
+      
See 
+        for details on extracting JSON from HTML.

+
+      

+        
To transform a JSON-conforming string [[RFC8259]],

+        

+          deserialize into the
+          internal representation as described in {{LoadDocumentCallback}};
+        

+
+        
To transform the internal representation to a JSON-LD document
+        

+        

+          serialize to JSON [[RFC8259]] using an appropriate serializer (e.g.,
+          [[ECMASCRIPT]] [=ToString=]);
+        

+      

+    
+    This section left intentially blank.
+    

   
 
   
RDF Dataset Interfaces

@@ -6416,7 +6562,8 @@ 
LoadDocumentCallback

           
If multiple HTTP Link Headers using the http://www.w3.org/ns/json-ld#context link relation are found,
             the promise is rejected with a JsonLdError whose {{JsonLdError/code}} is set to multiple context link headers
             and processing is terminated.

-          
Processors MAY transform document to the internal representation.

+          
Processors MAY transform a document to the internal representation,
+            as described in .

           
The HTTP Link Header is ignored for documents served as application/ld+json,
             text/html, or application/xhtml+xml.

         
@@ -6903,6 +7050,9 @@ 
Change log

       Embedding JSON-LD in HTML Documents [[JSON-LD11]]
       for treating script elements as a single document,
       as described in Candidate Correction 4.
+    
  • 2024-10-31: Abstract JSON serialization from WebIDL interfaces to allow
+      for alternative formats,
+      as described in Candidate Correction 5
    • 
   
   
 

From 1bfdba473cf50b35eadb5badaf338e281b457dfb Mon Sep 17 00:00:00 2001
From: Anatoly Scherbakov 
Date: Sun, 26 Jan 2025 13:03:30 +0400
Subject: [PATCH 2/3] #605 Replace `change_5` with `change_6`, to disambiguate
 against another PR

---
 index.html | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/index.html b/index.html
index 4d723092..fb5bb6fa 100644
--- a/index.html
+++ b/index.html
@@ -5713,8 +5713,8 @@ 
    Algorithm
    
       is used instead of looking at the HTTP Link Header directly. For the sake of simplicity, none of the algorithms
       in this document mention this directly.
    
 
-    
    
-      Candidate Correction 5
+    
    
+      Candidate Correction 6
       
    Details about transforming to and from a given serialization format
         have been abstracted so that other specifications can define
         serialization and deserialization requirements for their specific formats.
@@ -5731,7 +5731,7 @@ 
    Algorithm
    
       
    For more information, refer to issue 605.
    
     
    
 
-    
    Methods resolving a {{Promise}} with the internal representation
+    
    Methods resolving a {{Promise}} with the internal representation
       MUST either
       map it to the datatype used by the implementation, as described in ,
       or serialize it to JSON (or another appropriate serialization format)
@@ -5841,7 +5841,7 @@ 
    Algorithm
    
                 to the provided context.
             
           
-          
  • Resolve the promise with compacted output
+          
  • Resolve the promise with compacted output
             transforming compacted output from the
             internal representation to a JSON serialization.
    • 
         
@@ -5929,7 +5929,7 @@ 
    Algorithm
    
                 set expanded output to an array containing only expanded output.
             
           
-          
  • Resolve the promise with expanded output
+          
  • Resolve the promise with expanded output
             transforming expanded output from the
             internal representation to a JSON serialization.
    • 
         
@@ -5993,7 +5993,7 @@ 
    Algorithm
    
                 otherwise to null.
             
           
-          
  • Resolve the promise with flattened output
+          
  • Resolve the promise with flattened output
             transforming flattened output from the
             internal representation to a JSON serialization.
    • 
         
@@ -6033,7 +6033,7 @@ 
    Algorithm
    
             Serialize RDF as JSON-LD Algorithm method
             using dataset
             and options.
-          
  • Resolve the promise with expanded result
+          
  • Resolve the promise with expanded result
             transforming expanded output from the
             internal representation to a JSON serialization.
    • 
         
@@ -6226,7 +6226,7 @@ 
    Internal Representation in Implementations
    
 
     
    
       
    Serialization and Deserialization
    
-    
+    
 
       
    This section defines the requirements for serializing and deserializing
         JSON from and to the internal representation, as appropriate,
@@ -6257,7 +6257,7 @@ 
    Serialization and Deserialization
    
         
       
    
     
-    This section left intentially blank.
+    This section left intentially blank.
     
   
 
@@ -7052,7 +7052,7 @@ 
    Change log
    
       as described in Candidate Correction 4.
     
  • 2024-10-31: Abstract JSON serialization from WebIDL interfaces to allow
       for alternative formats,
-      as described in Candidate Correction 5
    • 
+      as described in Candidate Correction 5
   
   
 

From def68a16aba6d89e958d95d490d6e8fab2e2bbe5 Mon Sep 17 00:00:00 2001
From: Anatoly Scherbakov 
Date: Mon, 27 Jan 2025 21:57:20 +0400
Subject: [PATCH 3/3] #605 Replace `#change_5` with `#change_7`

---
 index.html | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/index.html b/index.html
index fb5bb6fa..94f4d8cd 100644
--- a/index.html
+++ b/index.html
@@ -5713,7 +5713,7 @@ 
    Algorithm
    
       is used instead of looking at the HTTP Link Header directly. For the sake of simplicity, none of the algorithms
       in this document mention this directly.
    
 
-    
    
+    
    
       Candidate Correction 6
       
    Details about transforming to and from a given serialization format
         have been abstracted so that other specifications can define
@@ -5731,7 +5731,7 @@ 
    Algorithm
    
       
    For more information, refer to issue 605.
    
     
    
 
-    
    Methods resolving a {{Promise}} with the internal representation
+    
    Methods resolving a {{Promise}} with the internal representation
       MUST either
       map it to the datatype used by the implementation, as described in ,
       or serialize it to JSON (or another appropriate serialization format)
@@ -5841,7 +5841,7 @@ 
    Algorithm
    
                 to the provided context.
             
           
-          
  • Resolve the promise with compacted output
+          
  • Resolve the promise with compacted output
             transforming compacted output from the
             internal representation to a JSON serialization.
    • 
         
@@ -5929,7 +5929,7 @@ 
    Algorithm
    
                 set expanded output to an array containing only expanded output.
             
           
-          
  • Resolve the promise with expanded output
+          
  • Resolve the promise with expanded output
             transforming expanded output from the
             internal representation to a JSON serialization.
    • 
         
@@ -5993,7 +5993,7 @@ 
    Algorithm
    
                 otherwise to null.
             
           
-          
  • Resolve the promise with flattened output
+          
  • Resolve the promise with flattened output
             transforming flattened output from the
             internal representation to a JSON serialization.
    • 
         
@@ -6033,7 +6033,7 @@ 
    Algorithm
    
             Serialize RDF as JSON-LD Algorithm method
             using dataset
             and options.
-          
  • Resolve the promise with expanded result
+          
  • Resolve the promise with expanded result
             transforming expanded output from the
             internal representation to a JSON serialization.
    • 
         
@@ -6226,7 +6226,7 @@ 
    Internal Representation in Implementations
    
 
     
    
       
    Serialization and Deserialization
    
-    
+    
 
       
    This section defines the requirements for serializing and deserializing
         JSON from and to the internal representation, as appropriate,
@@ -6257,7 +6257,7 @@ 
    Serialization and Deserialization
    
         
       
    
     
-    This section left intentially blank.
+    This section left intentially blank.
     
   
 
@@ -7052,7 +7052,7 @@ 
    Change log
    
       as described in Candidate Correction 4.
     
  • 2024-10-31: Abstract JSON serialization from WebIDL interfaces to allow
       for alternative formats,
-      as described in Candidate Correction 5
    • 
+      as described in Candidate Correction 7