View source for X3D JSON Encoding

These are X3D Working Group notes on the creation of an X3D JSON encoding and a corresponding conversion process.

== Design Requirements, Goals and Use Cases ==

Design requirement:
* Round-trippable encoding supporting X3D abstract specification

Design goals and primary use cases:
* Exchange format for a variety of 3D geometry and scene graphs
* Loader for various JavaScript-controlled renderers
* Manipulate a scene graph using JavaScript

Are there any special use cases for having X3D JSON available in JavaScript?
* Are there any use cases that might modify how X3D is represented in JSON?
* If so, it would be good to spell them out and understand them well.
* We want conversion rules to permit implementations that can achieve user goals.

== Initial implementations ==

* Experimental [http://www.web3d.org/x3d/stylesheets/X3dToJson.xslt X3dToJson.xslt] stylesheet converts .x3d into .json encoding. In version control at [https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/x3d/stylesheets/X3dToJson.xslt sourceforge]
** Current work: lists of comments; field/fieldValue representations for Scripts and prototypes
* Embedded in [https://savage.nps.edu/X3D-Edit/ X3D-Edit] for testing
* Initial Hello World examples deployed ([http://x3dgraphics.com/examples/X3dForAdvancedModeling/HelloWorldScenes/HelloWorld.x3d .x3d]) ([http://x3dgraphics.com/examples/X3dForAdvancedModeling/HelloWorldScenes/HelloWorld.html .html]) ([http://x3dgraphics.com/examples/X3dForAdvancedModeling/HelloWorldScenes/HelloWorld.xhtml x3dom .xhtml]) ([http://x3dgraphics.com/examples/X3dForAdvancedModeling/HelloWorldScenes/HelloWorld.json .json])
* Conversion syntax discussions continue on [http://web3d.org/pipermail/x3d-public_web3d.org/2014-October/002981.html x3dom-developers mail list] (with [http://www.x3dom.org/x3dom/test/functional/flipper.html "dump scene as json" test] by Dr. Yvonne Jung)
* X3D Examples include build scripts to convert .x3d to .json, then perform [http://www.jslint.com jslint] validation

== Conversion Considerations ==

Primary design criterion:  round-trippable lossless representation of X3D scene.

Conversion approach of greatest practical interest:  XML to/from JSON.  Issues:

# How to convert attribute names to distinguish them from child elements.  Resolution: "@attributeName".
# JSON handling of container elements to preserve parent/child relationships, distinguishing child elements from attributes  Resolution: use SFNode/MFNode field names as unique keys.
# Creation of JSON elements with datatypes appropriate to content (e.g., integer, float, strings, etc.).  Note special JSON rules for floats (not equivalent to IEEE floats).
# Both X3D and JSON can include comments, and so need an option for inclusion (by default) or removal (optional) of comments in order to ensure 100% round-trip conversion capabilities. 
# jslint-validatable field/fieldValue representations within Scripts and prototypes 
# Support for singleton (self-closing) XML tags also needs to be considered, without loss of generality.
# Inclusion and preservation of embedded XML namespace information in an XML (.x3d) document: might not be necessary or possible.

== Standardization ==

Probably smartest to first start out defining an X3D best practice.

This capability likely needs to be defined as one of the [http://www.web3d.org/standards X3D standards] as shown in the [http://www.web3d.org/specifications/X3dSpecificationRelationships.png X3D Specification Relationships] diagram.

The most probable place to put it is as a new Part 5 to ISO/IEC 19776. In this manner, it would correspond to the XML, Classic VRML, and Compressed Binary encodings.

== Discussion points ==

Here are suggested discussion points for X3D teleconferences and future followups.

# Is there a good/consistent way for X3DOM to utilize such capabilities?
# Is there a way for [http://threejs.org Three.js] X3D loader, [http://d3js.org D3.js] X3D loader, or other javascript libraries, to utilize such capabilities?
# Is there a single authoritative reference for JSON itself? and for JSON-XML conversions? See [6] for the JSON Data Interchange Format, need to confirm no others.
# What is the right file extension?  .json is distinguishable from .js used in plain Javascript in Script code; .x3dj distinguishes X3D JSON
## [http://en.wikipedia.org/wiki/JSON Wikipedia] (referencing ECMA) states that <code>.json</code> is the standard extension
## Internet MIME-type is <code>application/json</code>
# Can a file reader distinguish the incoming encodings (.x3d .x3dv .x3db .x3de .json/.x3dj) independent of file extension or MIME media type?
# Once a canonical form for X3D as JSON is established, add conversion capabilities to X3D-Edit and also autoconvert, test and publish JSON for all of the 3800+ scenes in the [http://www.web3d.org/x3d-resources/content/examples/X3dResources.html#Examples X3D Examples Archives]
# Compare compression size and decompression speed of a TestMesh.x3d.json.gz to TestMesh.x3db and TestMesh.x3d.exi (EXI will likely win because it includes data typing)

Probably lots more... What else?

== References ==

* XML to JSON Converter (provides option to assign a prefix to JSON attributes, default is @ character) http://www.freeformatter.com/xml-to-json-converter.html
* Apache Camel, XML JSON Data Format (camel-xmljson) [http://camel.apache.org/xmljson.html
* JavaScript Object Notation (JSON) Definition http://json.org
* ECMA 404: JSON Data Interchange Format (Final Draft) http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
* JSON Markup Language (JsonML) http://www.jsonml.org/
* XSLTJSON: Transforming XML to JSON using XSLT http://www.bramstein.com/projects/xsltjson
* Converting Between XML and JSON http://www.xml.com/pub/a/2006/05/31/converting-between-xml-and-json.html
* XML/JSON Perl Converter http://search.cpan.org/~ken/XML-XML2JSON-0.06/lib/XML/XML2JSON.pm
* IBM's PHP converter http://www.ibm.com/developerworks/library/x-xml2jsonphp
* Java Converter http://www.json.org/javadoc/org/json/XML.html
* Google Code Library https://code.google.com/p/x2js

'''Mailing list discussions'''
* Initial message [http://web3d.org/pipermail/x3d-public_web3d.org/2014-July/002854.html]
* July's thread listing [http://web3d.org/pipermail/x3d-public_web3d.org/2014-July/thread.html]
* Ongoing on [http://www.web3d.org/mailman/listinfo/x3d-public_web3d.org x3d-public mailing list], occasionally on [http://www.x3dom.org/?page_id=3 x3dom mailing list]