Difference between revisions of "X3D JSON Encoding"

From Web3D.org
Jump to: navigation, search
(Design Requirements, Goals and Use Cases)
(direct source of .json instead of indirect)
Line 16: Line 16:
 
* We want conversion rules to permit implementations that can achieve user goals.
 
* We want conversion rules to permit implementations that can achieve user goals.
  
Guideline: the more this work progresses, the more the JSON output resembles VRML/ClassicVrml structure with slight differences in syntax. This approach has a valuable extra benefit in that results are broadly understandable by many programmers.
+
Guideline: the more this work progresses, the more the JSON output resembles VRML/ClassicVrml structure with slight differences in syntax. This approach has a valuable extra benefit in that results are broadly understandable by many programmers.
  
 
== Initial implementations ==
 
== Initial implementations ==
Line 30: Line 30:
 
== Conversion Considerations ==
 
== Conversion Considerations ==
  
Primary design criterion: round-trippable lossless representation of X3D scene.
+
Primary design criterion: round-trippable lossless representation of X3D scene.
  
Conversion approach of greatest practical interest: XML to/from JSON. Issues:
+
Conversion approach of greatest practical interest: XML to/from JSON. Issues:
  
# How to convert attribute names to distinguish them from child elements. Resolution: "@attributeName".
+
# 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.
+
# 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).
+
# 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.  
 
# 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  
 
# jslint-validatable field/fieldValue representations within Scripts and prototypes  
Line 57: Line 57:
 
# 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 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.
 
# 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
+
# 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
+
## [https://tools.ietf.org/html/rfc7159 IETF] (referencing ECMA) states that <code>.json</code> is the standard extension
 
## Internet MIME-type is <code>application/json</code>
 
## 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?
 
# Can a file reader distinguish the incoming encodings (.x3d .x3dv .x3db .x3de .json/.x3dj) independent of file extension or MIME media type?

Revision as of 12:27, 28 September 2015

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.

Guideline: the more this work progresses, the more the JSON output resembles VRML/ClassicVrml structure with slight differences in syntax. This approach has a valuable extra benefit in that results are broadly understandable by many programmers.

Initial implementations

Conversion Considerations

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

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

  1. How to convert attribute names to distinguish them from child elements. Resolution: "@attributeName".
  2. JSON handling of container elements to preserve parent/child relationships, distinguishing child elements from attributes Resolution: use SFNode/MFNode field names as unique keys.
  3. 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).
  4. 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.
  5. jslint-validatable field/fieldValue representations within Scripts and prototypes
  6. Support for singleton (self-closing) XML tags also needs to be considered, without loss of generality.
  7. 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 X3D standards as shown in the 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.

  1. Is there a good/consistent way for X3DOM to utilize such capabilities?
  2. Is there a way for Three.js X3D loader, D3.js X3D loader, or other javascript libraries, to utilize such capabilities?
  3. 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.
  4. What is the right file extension? .json is distinguishable from .js used in plain Javascript in Script code; .x3dj distinguishes X3D JSON
    1. IETF (referencing ECMA) states that .json is the standard extension
    2. Internet MIME-type is application/json
  5. Can a file reader distinguish the incoming encodings (.x3d .x3dv .x3db .x3de .json/.x3dj) independent of file extension or MIME media type?
  6. 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)
  7. Show .dot notation in JavaScript code accessing elements and attributes, see if it is sensible

Probably lots more... What else?

References

Mailing list discussions