cJSON is a plain text file format used to serialize COMAND repository objects in JSON.  cJSON is identical to standard JSON, except JavaScript comments are allowed and ignored, just like JavaScript source code.  The data structures in cJSON follow a specific format described below.

JavaScript comments do not comply with standard JSON. So, to avoid confusion and respect standard JSON, COMAND JSON with comments is referred to as cJSON.


 * Contacts - Some contacts with photos.
    "type": "COMAND",
    "version": "1.0",
    "title": "Contacts",
    "description": "Some contacts with photos.",
    "source": "https://comandsystems.com/contacts",
    "time": "2013-10-16T15:39:25+0400",
    "contents": [
            "ID": 13,
            "OID": 2458,
            "UUID": "550e8400-e29b-41d4-a716-446655440013",
            "Type": {"UUID": "550e8400-e29b-41d4-a716-446655440123"},
            "Name": "Mary Smith",
            "EmergencyContact": {"OID": 2460},
            "PhotoFilename": "profile.jpg",
            "Photo": {"type": "url", "value": "files/1.jpg"},
            "Phones": [
                    "ID": 1,
                    "OID": 2478,
                    "UUID": "550e8400-e29b-41d4-a716-446655442323",
                    "Type": {"UUID": "550e8400-e29b-41d4-a716-446655441122"},
                    "Number": "555-555-5555",
                    "Description": "Mobile"
            "ID": 15,
            "OID": 2460,
            "UUID": "550e8400-e29b-41d4-a716-446655440015",
            "Type": {"UUID": "550e8400-e29b-41d4-a716-446655440123"},
            "Name": "John Smith",
            "EmergencyContact": {"OID": 2458}, // reference to Mary Smith
            "PhotoFilename": "mug.jpg",
            "Photo": {"type": "url", "value": "files/2.jpg"}

cJSON is a useful format because it is open and can be easily read and written by web developers, web applications and other software to access and transfer objects, including content types, content and file data.  It is more storage efficient than XML, but less efficient than binary files and databases.

In addition to being the file system storage engine format, cJSON files can also be used for backups and to transfer objects from one repository to another.

The correct MIME Type for cJSON is "application/cjson".  If there are no comments, then the MIME Type "application/json" can be used instead.


cJSON follows the rules below.


JavaScript comments (/* enclosed */ and // end of line) are valid and ignored, the same way they are in JavaScript source code. This does not comply with standard JSON.

Top Node

The top-level node is either an object that includes metadata about the contents, or an array of those objects.  An array is used, for example, to represent the results of each query in a response to a single Get Web Service request with multiple queries.

A few key/value pairs are require and the rest are optional.

  • type (required) - Always the string "COMAND". This is used by the COMAND API and other applications to verify the JSON file contains COMAND objects.
  • version (required) - The version of the COMAND JSON file format. Currently this is always "1.0". Future versions should be backward compatible.
  • source - Optional URL to the COMAND Web Services that provides access to the repository that stores these objects and those they reference, or to a folder that stores this cJSON and potentially others that represent the objects it contains and/or those they reference.  Typically, filenames are composed from the top-level object UUID and ".cjson" extension
  • repository - Optional UUID of the repository (root object).  If a repository is specified and matches the destination repository UUID, then OIDs and DOIDs will be used to match existing content.  Otherwise, OID and DOID are not used to match content because the source repository is not known and they are not consistent across repositories, so it is not safe to assume they will be the same in the destination.
  • time - Optional time objects were queried, in "YYYY-MM-DDTHH:MM:SS+HH:MM" format (see ISO 8601).  While not recommended when sharing with externally, any format supported by strtotime() is also supported.
  • title - Optional title of the file.
  • description - Optional summary of the contents of the file.
  • token - Optional User Token used to authenticate Web Services requests to the source.
  • contents - Array of objects.
Additional metadata is also provided in Web Service responses.  For details, see Web Services  Common Response Properties.


Each object contains keys based on the Identifier for each field specified in the file.  Missing fields should be populated at the destination with their default values, according to the Content Type.

  • OID/UUID - Just the OID or UUID key/value pair may be specified for an object. If only an OID is specified, it may reference an object in the file, or an object at the specified source.  If only a UUID is specified, it may reference an object in the file, an object at the specified source, or an object in any other repository.
  • Data Type Fields - Keys that represent a data type field may provide a value in boolean, number or string format. Text and binary values may be provided in an external file. In this case, the value will be an object with a type and value property, where the value is interpreted based on one of the following types.
    • string - value is a string that may contain JavaScript string escape codes for non-ascii characters. For example, the string "\u0227" represents the UTF8 text ȧ. This format is automatically decoded by JavaScript, but is not very space efficient (1 to 3 times the size of the raw binary data).
    • base64 - value is a base64 encoded string
    • url - value is a URL to the resource that contains the value.  The URL may reference binary or text data, and may be relative to the JSON file or URL (checked first when applicable) or source URL (checked second when defined) or absolute.
    • attachment - value is an ID that correspond to the ID provided in the response to a previous Attach Web Wervice request.  This is only available in the context of a Put Web Service request.
  • Content Type Single Fields - Keys that represent a content type field with a single object, whether embedded or a reference, are provided as an object.  A reference may also be a string (see References).
  • Content Type List Fields - Keys that represent a content type field with multiple objects, whether embedded or a reference, are provided as an array of objects.  If an item in the array is a reference, a string may also be provided (see References).
  • Type - The Type field has special significance.  When specified, if a matching object in the target repository can not be found or matched on a unique field, the object will be created.  Without the Type field specified, the object fields will only be used to match the referenced object, and an error will result if it can not be found.
  • Order Independence - Objects can be defined after other objects that reference them.
  • Approval Order - Objects are first stored in the destination repository in whatever order is determined to be necessary.  Objects are then approved in the order they appear in the file (depth-first).


When a field references an object, referenced objects may be specified in one of the ways listed below, which must uniquely identify the object within the repository.  If multiple matches are found, the reference will be ignored, and typically a warning emitted.

If a reference includes a Type key/value pair, the object will be created if it can not be found, when imported.
  • Object - A JSON object with one or more of the following fields.  If multiple specified, they will be processed in the order listed below, using the first match.
    • _MyID - Refers to the _MyID of another object in the same file.
    • UUID - Refers to the Universally Unique ID of an object in the file or target repository.
    • DOID - Refers to the Dimension-specific Object ID of an object in the file or target repository.
    • OID - Refers to the Object ID of an object in the file or target repository, but only if the target repository is the same as the source/repository specified in the Top Node.
    • ID - Refers to the ID of an object in the file or target repository, but only if the target repository is the same as the source or repository specified in Top Node.
    • unique/key field - Any field in the content type that is flagged as a Unique/Key field.
  • String - A JSON string that matches one of the following (will pick first that matches)
    • cQuery - A cQuery statement, which may include cPath and/or cQL.
    • Key=Value - A unique/key field followed by an equal sign (=) and corresponding value.
    • Object Key - The cObject Key.



Refers to the _MyID of another object in the same file.

{"_MyID": 1}


Refers to the UUID of another object in the file or in the repository.

{"UUID": "550e8400-e29b-41d4-a716-446655440013"}


Refers to the dimension-specific object ID of another object in the file or in the repository.

{"DOID": 12345}


Refers to the object ID of another object in the same cJSON file or in the repository.

{"OID": 12345}


Refers to the ID of another object in the same cJSON file or in the repository.  The Type must be specified as well, if it can not be implied by the field that references it.

{"ID": 123} or {"Type": "Contact", "ID": 123}



A string that contains a cQuery that resolves to a single object.



A key/value pair, where the key is a Field Identifier for a Unique/Key filed and value is that field's value to match on.


Object Key

The Object Key as a string.



cJSON is process in multiple passes to handle when objects are referenced before they are defined, cyclic relationships and other complexities.  While it often isn't necessary to understand how cJSON is processed, sometimes it is important or even critical.  For this reason, the process is outlined below.

1. Validation - The import data and references within the cJSON and potentially to existing content in the repository are validated.  If there are any errors, the import process will stop.

If the repository is not the same repository the JSON was exported from, IDs, OIDs, DOIDs are only considered "locally" within the cJSON, similar to a _MyID.  That is they can be used to establish references between content within the JSON, but will not be associated with content in the repository.  If the repository is the same as the export repository, IDs, OIDs and DOIDs will be used to reference content both within the JSON file and the repository.

2. Content Types - Any content types defined in the cJSON are applied to the repository first.  This way any content of those types that appear in the cJSON can be stored.

3. Store Objects - All objects are first stored (as a working-copy, not approved) in the repository with their field values.  If an existing object on the repository was matched, updates to that object will be stored.  Otherwise a new object will be stored.

4. Validate & Approve Objects - All stored objects are finally validated and approved (if valid) in the order that they appeared in the cJSON file (depth-first).  If they were not valid, the validation errors will be logged and the object will remain stored.