cJSON

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.

Example

/**
 * 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.

Rules

cJSON follows the rules below.

Comments

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.

Objects

Each object in the contents array corresponds to a Content Type defined in the repository or as a Content Type object in the contents array.  Objects contain key/value pairs, where the key corresponds to a Content Type Field Identifier, and the value that corresponds to the data, child object(s) or connection(s) for that field.  Missing fields will be populated at the destination with their default values, according to the Content Type.

Consider the following field rules.

• 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).

References

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.

• 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.

Object

_MyID

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

{"_MyID": 1}

UUID

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

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

DOID

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

{"DOID": 12345}

OID

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

{"OID": 12345}

ID

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}

String

cQuery

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

"/"

Key=Value

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.

"Identifier=Example"

Object Key

The Object Key as a string.

"Example"

Processing

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.

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.

• < Binary
• XML >