Added note about data round-tripping issues.
authorManu Sporny <msporny@digitalbazaar.com>
Thu, 12 May 2011 21:05:34 -0400
changeset 29 598c6b2fe2d3
parent 28 87caf5a79553
child 30 3770c6e17245
Added note about data round-tripping issues.
spec/latest/index.html
--- a/spec/latest/index.html	Mon May 09 20:47:15 2011 -0400
+++ b/spec/latest/index.html	Thu May 12 21:05:34 2011 -0400
@@ -1407,7 +1407,7 @@
      "name": "http://xmlns.com/foaf/0.1/name",
      "age": "http://xmlns.com/foaf/0.1/age",
      "homepage": "http://xmlns.com/foaf/0.1/homepage",
-****     "@type":
+****     "@coerce":
      {
         "xsd:integer": "age",
         "xsd:anyURI": "homepage",
@@ -1474,6 +1474,15 @@
 can use JSON-LD as their storage format. The group needs feedback from 
 CouchDB and MongoDB experts regarding the usefulness of JSON-LD in those
 environments.</p>
+
+<p class="issue">MongoDB does not allow the '.' character to be used in
+key names. This prevents developers from storing IRIs as keys, which also
+prevents storage of the data in normalized form. While this issue can
+be avoided by using CURIEs for key values, it is not known if this
+mechanism is enough to allow JSON-LD to be used in MongoDB in a way that
+is useful to developers.
+</p>
+
 </section>
 
 </section>
@@ -1771,13 +1780,13 @@
                 "name" : "http://xmlns.com/foaf/0.1/name",
                 "age" : "http://xmlns.com/foaf/0.1/age",
                 "homepage" : "http://xmlns.com/foaf/0.1/homepage",
-                "@type": {
+                "@coerce": {
                    "xsd:nonNegativeInteger": "age",
                    "xsd:anyURI": "homepage"
                 }
               },
               "name" : "Joe Jackson",
-              "age" : 42,
+              "age" : "42",
               "homepage" : "http://example.org/people/joe" };
 
 // Map the language-native object to JSON-LD
@@ -1818,6 +1827,36 @@
 not use values that are going to undergo automatic conversion. This is due
 to the lossy nature of <strong>xsd:double</strong> values.</p>
 
+<p class="issue">Round-tripping data can be problematic if we mix and
+match @coerce rules with JSON-native datatypes, like integers. Consider the 
+following code example:</p>
+
+<pre class="example" data-transform="updateExample">
+<!--
+var myObj = { "@context" : { 
+                "number" : "http://example.com/vocab#number",
+                "@coerce": {
+                   "xsd:nonNegativeInteger": "number"
+                }
+              },
+              "number" : 42 };
+
+// Map the language-native object to JSON-LD
+var jsonldText = jsonld.normalize(myObj);
+
+// Convert the normalized object back to a JavaScript object
+var myObj2 = jsonld.parse(jsonldText);
+-->
+</pre>
+
+<p class="issue">At this point, myObj2 and myObj will have different
+values for the "number" value. myObj will be the number 42, while
+myObj2 will be the string "42". This type of data round-tripping
+error can bite developers. We are currently wondering if having a
+"coerce validation" phase in the parsing/normalization phases would be a 
+good idea. It would prevent data round-tripping issues like the
+one mentioned above.</p>
+
 </section>
 
 </section>