ChemDoodle JSON Format

Introduction

The ChemDoodle JSON format is the native way to present data to the ChemDoodle Web Components. JSON (JavaScript Object Notation) is the native object format for Javascript, so it is particularly suitable for us to use it with the ChemDoodle Web Components.

There are two benefits to using ChemDoodle JSON, the first being that we can easily manipulate it in Javascript, and the second being that it is immediately recognized as a Javascript object rather than having to parse and preformat a string. It is also much more powerful to use ChemDoodle JSON instead of another chemical format, as ChemDoodle JSON was specifically created for the ChemDoodle Web Components and fully and completely describes every last object supported by the ChemDoodle Web Components and vice versa.

Our ChemDoodle JSON format was created to be minimalistic, so tags are chosen to be as short as possible. It also makes copious use of default values, so we do not need to specify a lot of information, like single bond orders or carbon labels.

Usage

ChemDoodle JSON can be directly used in Javascript. However, it is important to keep in mind that the objects declared by ChemDoodle JSON are not the same as data structures declared by the ChemDoodle Web Components API. This is because the API’s data structures, in many cases, have cyclical references and therefore the JSON equivalent would be infinitely long. Additionally, the API’s data structures contain a lot of metadata and longer, more readable, variable names that would pollute the JSON string, and defeat its purpose as a minimalistic format. To work with this, the ChemDoodle Web Components contains a JSONInterpreter class to convert between ChemDoodle JSON and the ChemDoodle Web Components‘ data structures.

Using the JSONInterpreter class is simple and is similar to using other interpreters, except that instead of handling strings, the JSONInterpreter handles objects. The JSONInterpreter class can be found in the ChemDoodle.io package and currently contains the following functions:

  • molTo – Converts a Molecule data structure to a JSON protocol Javascript object.
  • molFrom – Converts a a JSON protocol Javascript object to a Molecule data structure.
  • shapeTo – Converts a Shape data structure to a JSON protocol Javascript object.
  • shapeFrom – Converts a a JSON protocol Javascript object to a Shape data structure.
  • contentTo – Converts a provided Array of Molecule data structures and Array of Shape data structure to a JSON protocol Javascript object.
  • contentFrom – Converts a a JSON protocol Javascript object to an object containing two Arrays, molecules and shapes, containing the Molecule data structures and Shape data structures.

Use these functions as follows:

1
2
3
4
5
var mol = myCanvas.getMolecule();
// this line converts the Molecule data structure to the JSON protocol Javascript object
var dummy = new ChemDoodle.io.JSONInterpreter().molTo(mol);
// this line reconstructs the Molecule data structure from the JSON object
var reconstructed = new ChemDoodle.io.JSONInterpreter().molFrom(dummy);

One last thing to keep in mind is that the JSON object is not a string, but in some cases must be handled like a string, such as when transfering data to and from a server through AJAX. In these cases, make use of the Javascript functions JSON.stringify() and JSON.parse() to convert to and from a string respectively.

1
2
3
4
//asString is a JSON representation as a string of the Object obj
var asString = JSON.stringify(obj);
//asObj is the Javascript Object reconstructed from the JSON string
var asObj = JSON.parse(asString);

ChemDoodle desktop

ChemDoodle desktop contains several tools for creating ChemDoodle JSON from drawings and other file types. It also contains a tool to optimize PDB files into ChemDoodle JSON for quick loading into 3D Canvases.

ChemDoodle JSON Generator

Use this sketcher and 3D editor below to help you create 2D and 3D content in the ChemDoodle JSON format. Just load and draw the content to be represented and press the Create ChemDoodle JSON button below the sketcher or editor.



Format

Content
(Object) : This is the root object.
{
m (Array) : Array of molecule objects. If there are no molecule objects, this array can be left out.
[
{
}, ...

]

,s (Array) : Array of shape objects. If there are no shape objects, this array can be left out.

[
{
}, ...

]

}

Content Examples
Isomers of Butane
{“m”:[{"a":[{"x":85,"y":144},{"x":102.32050807568878,"y":134},{"x":67.67949192431124,"y":134},{"x":85,"y":164}],”b”:[{"b":0,"e":1},{"b":0,"e":2},{"b":0,"e":3}]},{“a”:[{"x":213,"y":131},{"x":230.32050807568876,"y":121},{"x":247.64101615137753,"y":131},{"x":264.9615242270663,"y":121}],”b”:[{"b":0,"e":1},{"b":1,"e":2},{"b":2,"e":3}]}]}
Diels-Alder Reaction
{“m”:[{"a":[{"x":37.5,"y":117.4},{"x":37.5,"y":137.4},{"x":54.820508075688764,"y":147.4},{"x":54.820508075688764,"y":107.4}],”b”:[{"b":0,"e":1},{"b":1,"e":2,"o":2},{"b":0,"e":3,"o":2}]},{“a”:[{"x":98,"y":139},{"x":98,"y":119},{"x":115.32050807568876,"y":109,"l":"O"}],”b”:[{"b":0,"e":1,"o":2},{"b":1,"e":2}]},{“a”:[{"x":260,"y":108},{"x":277.3205080756888,"y":118},{"x":277.3205080756888,"y":138},{"x":260.00000000000006,"y":148.00000000000003},{"x":242.67949192431126,"y":138.00000000000009},{"x":242.67949192431118,"y":118.00000000000009},{"x":294.6410161513776,"y":108,"l":"O"}],”b”:[{"b":0,"e":1},{"b":1,"e":2},{"b":2,"e":3},{"b":3,"e":4},{"b":4,"e":5,"o":2},{"b":5,"e":0},{"b":1,"e":6}]}],”s”:[{"t":"Line","x1":158,"y1":128,"x2":203.0111097397076,"y2":128,"a":"synthetic"}]}

Molecule
(Object) : This is the root object.

{
a (Array) : Array of atom objects.
[
{
i (String) : A unique identifier for this atom, only needs to be provided if necessary
,l (Stringdefault='C') : Label
,x (Numberrequired) : X coordinate
,y (Numberrequired) : Y coordinate
,z (Numberdefault=0) : Z coordinate
,c (Integerdefault=0) : Charge
,m (Integerdefault=-1) : Mass
,r (Integerdefault=0) : Number of radicals
,p (Integerdefault=0) : Number of lone pairs
,q (Objectdefault=undefined) : If present, this object defines the query for the atom, as described by the query section below
}, ...

]

,b (Array) : Array of bond objects. This array does not need to be included if it is empty.

[
{
i (String) : A unique identifier for this bond, only needs to be provided if necessary
,b (Integerrequired) : Index of the atom in the atom array that this bond begins with.
,e (Integerrequired) : Index of the atom in the atom array that this bond ends with.
,o (Numberdefault=1) : Bond order, this can be integers or positive half increments or 0
,s (Stringdefault='none') : Stereochemistry of the bond. Accepted values are 'none', 'protruding', 'recessed' or 'ambiguous'.
,q (Objectdefault=undefined) : If present, this object defines the query for the bond, as described by the query section below
}, ...

]

}

Molecule Examples
Methane
{“a”:[{"y":0,"x":0}]}
Ethane
{“b”:[{"e":1,"b":0}],”a”:[{"y":-5,"x":-8.6603},{"y":5,"x":8.6603}]}
Pyridine
{“a”:[{"x":115,"y":100,"l":"N"},{"x":132.3205080756888,"y":110},{"x":132.32050807568882,"y":130},{"x":115.00000000000007,"y":140.00000000000003},{"x":97.67949192431126,"y":130.00000000000009},{"x":97.67949192431118,"y":110.00000000000009}],”b”:[{"b":0,"e":1},{"b":1,"e":2,"o":2},{"b":2,"e":3},{"b":3,"e":4,"o":2},{"b":4,"e":5},{"b":5,"e":0,"o":2}]}

Query
A query defines attributes to atoms and bonds for searching and other cheminformatics functions. Each member of a Query object is itself an object that holds two values, ‘v’ for the actual value, and ‘n’ (that when present) to represent the negate or opposite. An iChemLabs query range string is any comma separated string of ranges and numbers, with number ranges denoted with a dash. For instance, ‘-1,2,4-7′ means -1 or 2 or between 4 and 7.
(Object) : This is the root object.

{
as (Objectrequired) : This variable holds the atom element types, including wildcards in an array. This is the identity variable. This is required for atom queries in the ChemDoodle JSON format.
,bs (Objectrequired) : This variable holds the bond types, including wildcards in an array. This is the identity variable. This is required for bond queries in the ChemDoodle JSON format.
,@ (Object) : This variable holds the hash value for atom and bond CIP stereochemistry. For atoms ‘A’ is any, ‘R’ is rectus and ‘S’ is sinestra. For bonds ‘A’ is any, ‘E’ is entegen and ‘Z’ is zusammen.
,A (Object) : This variable holds the hash value for atom and bond aromaticity. This variable is implied and will be set if present, but true should be set to the value.
,C (Object) : This variable holds the charge range for atoms. The value is a iChemLabs query range string.
,H (Object) : This variable holds the hydrogen count range for atoms. The value is a iChemLabs query range string.
,R (Object) : This variable holds the ring count range for atoms and bonds. The value is a iChemLabs query range string.
,S (Object) : This variable holds the hash value for atom saturation. This variable is implied and will be set if present, but true should be set to the value.
,X (Object) : This variable holds the total connectivity range for atoms. The value is a iChemLabs query range string.
,x (Object) : This variable holds the total connectivity range for atoms without including hydrogens. The value is a iChemLabs query range string.
}

Query Examples
Atom Query
{“m”:[{"a":[{"q":{"@":{"v":"R"},"A":{"v":true},"R":{"n":true,"v":"2,3-5"},"as":{"v":["x","C","Se","Pt"]}},”x”:205.3205,”y”:153}]}]}
Bond Query
{“m”:[{"a":[{"x":124,"i":"a0","y":348},{"x":141.3205,"i":"a1","y":338}],”b”:[{"q":{"@":{"v":"Z"},"bs":{"v":["1","3","h"]},”A”:{“n”:true,”v”:true},”R”:{“v”:”1-3,6″}},”b”:0,”e”:1,”i”:”b0″}]}]}

Line (Shape, 2D)
(Object) : This is the root object.

{
t (Stringrequired) : This value is ‘Line’ and is used to define its shape type.
,i (String) : A unique identifier for this shape, only needs to be provided if necessary
,x1 (Numberrequired) : X coordinate of the start point
,y1 (Numberrequired) : Y coordinate of the start point
,x2 (Numberrequired) : X coordinate of the end point
,y2 (Numberrequired) : Y coordinate of the end point
,a (Numberdefault=undefined) : Arrow type. Accepted values are ‘synthetic’, ‘retrosynthetic’, ‘resonance’ and ‘equilibrium’.
}

Line Examples
Synthetic Arrow
{“t”:”Line”,”x1″:0,”y1″:0,”x2″:40,”y2″:0,”a”:”synthetic”}

Pusher (Shape, 2D)
(Object) : This is the root object.

{
t (Stringrequired) : This value is ‘Pusher’ and is used to define its shape type.
,i (String) : A unique identifier for this shape, only needs to be provided if necessary
,o1 (Stringrequired) : The id of the chemical object this Pusher points from
,o2 (Stringrequired) : The id of the chemical object this Pusher points to
,e (Numberdefault=1) : Number of electrons being pushed; this can also be -1, specifying a bond forming pusher
}

Pusher Examples
Electron Pair Pusher from a Bond to an Atom
{“m”:[{"a":[{"x":392.5,"y":309.4,"i":"a0"},{"x":392.5,"y":289.4,"i":"a1","l":"O"}],”b”:[{"b":0,"e":1,"i":"b0","o":2}]}],”s”:[{"i":"s0","t":"Pusher","o1":"b0","o2":"a1","e":2}]}

Bracket (Shape, 2D)
(Object) : This is the root object.

{
t (Stringrequired) : This value is ‘Bracket’ and is used to define its shape type.
,i (String) : A unique identifier for this shape, only needs to be provided if necessary
,x1 (Numberrequired) : X coordinate of the start point
,y1 (Numberrequired) : Y coordinate of the start point
,x2 (Numberrequired) : X coordinate of the end point
,y2 (Numberrequired) : Y coordinate of the end point
,c (Numberdefault=0) : The charge amount associated with this bracket (displayed at the top right).
,m (Numberdefault=0) : The multiple count associated with this bracket (displayed at the center left).
,r (Numberdefault=0) : The repeat count associated with this bracket (displayed at the bottom right).
}

Bracket Examples
Bracket with a 2+ charge
{“s”:[{"i":"s0","t":"Bracket","x1":5,"y1":5,"x2":15,"y2":15,"c":2}]}

Distance (Shape, 3D)
(Object) : This is the root object.

{
t (Stringrequired) : This value is ‘Distance’ and is used to define its shape type.
,i (String) : A unique identifier for this shape, only needs to be provided if necessary
,a1 (Stringrequired) : The id of the first Atom this Distance connects
,a2 (Stringrequired) : The id of the second Atom this Distance connects
}

Distance Examples
Distance between two atoms
{“m”:[{"a":[{"x":0,"y":-0.2633,"i":"a0","l":"O"},{"x":-0.8109999999999999,"y":0.2633,"i":"a1","l":"H"},{"x":0.8109999999999999,"y":0.2633,"i":"a2","l":"H"}],”b”:[{"b":0,"e":1,"i":"b0"},{"b":0,"e":2,"i":"b1"}]}],”s”:[{"i":"s0","t":"Distance","a1":"a1","a2":"a2"}]}

Angle (Shape, 3D)
(Object) : This is the root object.

{
t (Stringrequired) : This value is ‘Angle’ and is used to define its shape type.
,i (String) : A unique identifier for this shape, only needs to be provided if necessary
,a1 (Stringrequired) : The id of the first Atom of this Angle
,a2 (Stringrequired) : The id of the second Atom of this Angle
,a3 (Stringrequired) : The id of the third Atom of this Angle
}

Angle Examples
Angle through three atoms
{“m”:[{"a":[{"x":0,"y":-0.2633,"i":"a0","l":"O"},{"x":-0.8109999999999999,"y":0.2633,"i":"a1","l":"H"},{"x":0.8109999999999999,"y":0.2633,"i":"a2","l":"H"}],”b”:[{"b":0,"e":1,"i":"b0"},{"b":0,"e":2,"i":"b1"}]}],”s”:[{"i":"s0","t":"Angle","a1":"a1","a2":"a0","a3":"a2"}]}

Torsion (Shape, 3D)
(Object) : This is the root object.

{
t (Stringrequired) : This value is ‘Torsion’ and is used to define its shape type.
,i (String) : A unique identifier for this shape, only needs to be provided if necessary
,a1 (Stringrequired) : The id of the first Atom of this Torsion
,a2 (Stringrequired) : The id of the second Atom of this Torsion
,a3 (Stringrequired) : The id of the third Atom of this Torsion
,a4 (Stringrequired) : The id of the fourth Atom of this Torsion
}

Torsion Examples
Torsion through four atoms
{“m”:[{"a":[{"x":-2.18,"y":0.0553,"i":"a0","l":"Cl"},{"x":-0.49420000000000003,"y":-0.584,"i":"a1"},{"x":0.49420000000000003,"y":0.584,"i":"a2"},{"x":2.18,"y":-0.0553,"i":"a3","l":"Cl"},{"x":-0.3366,"y":-1.1932,"i":"a4","l":"H","z":0.89},{"x":-0.3366,"y":-1.1932,"i":"a5","l":"H","z":-0.89},{"x":0.3366,"y":1.1932,"i":"a6","l":"H","z":-0.89},{"x":0.3366,"y":1.1932,"i":"a7","l":"H","z":0.89}],”b”:[{"b":0,"e":1,"i":"b0"},{"b":1,"e":2,"i":"b1"},{"b":2,"e":3,"i":"b2"},{"b":1,"e":4,"i":"b3"},{"b":1,"e":5,"i":"b4"},{"b":2,"e":6,"i":"b5"},{"b":2,"e":7,"i":"b6"}]}],”s”:[{"i":"s0","t":"Torsion","a1":"a0","a2":"a1","a3":"a2","a4":"a3"}]}

Unit Cell (Shape, 3D)
(Object) : This is the root object.

{
t (Stringrequired) : This value is ‘UnitCell’ and is used to define its shape type.
,i (String) : A unique identifier for this shape, only needs to be provided if necessary
,o (Array) : The vector defining the origin corner; this is an array of length 3, with values of numbers for x, y, and z in that order
,x (Array) : The vector defining the x corner; this is an array of length 3, with values of numbers for x, y, and z in that order
,y (Array) : The vector defining the y corner; this is an array of length 3, with values of numbers for x, y, and z in that order
,z (Array) : The vector defining the z corner; this is an array of length 3, with values of numbers for x, y, and z in that order
,xy (Array) : The vector defining the xy corner; this is an array of length 3, with values of numbers for x, y, and z in that order
,xz (Array) : The vector defining the xz corner; this is an array of length 3, with values of numbers for x, y, and z in that order
,yz (Array) : The vector defining the yz corner; this is an array of length 3, with values of numbers for x, y, and z in that order
,xyz (Array) : The vector defining the xyz corner; this is an array of length 3, with values of numbers for x, y, and z in that order
}

Unit Cell Examples
Gold atom in a face-centered cubic unit cell
{“s”:[{"xy":[2.0393,2.0393,-2.0393],”yz”:[-2.0393,2.0393,2.0393],”xz”:[2.0393,-2.0393,2.0393],”t”:”UnitCell”,”x”:[2.0393,-2.0393,-2.0393],”xyz”:[2.0393,2.0393,2.0393],”y”:[-2.0393,2.0393,-2.0393],”i”:”s0″,”z”:[-2.0393,-2.0393,2.0393],”o”:[-2.0393,-2.0393,-2.0393]}],”m”:[{"a":[{"x":0,"y":0,"l":"Au"}]}]}