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 used for the standard 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 these basic rules:

• 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.
• The top-level node is always an object used to convey metadata about the contents, and it should only exist in the JSON file for that purpose. A few key/value pairs are require and some others are options:
  • 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 repository web service or folder that hosts this file and objects.
  • time - Optional time objects were queried, in "YYYY-MM-DDTHH:MM:SS+HH:MM" format (see ISO 8601).
  • title - Optional title for the JSON file.
  • description - Optional summary of the purpose of contents of the JSON file.
  • token - Optional User Token used to authenticate a Web Service request.
  • contents - Array of objects.
• 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.
• 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.
• 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 service request.  This is only available in the context of a Put web service request.
• Keys that represent a content type field with a single object, whether embedded or a reference, are provided as an object.  If a reference, a string containing a cQuery that resolves to the object may also be provided (see References).
• 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 containing a cQuery that resolves to the object may also be provided (see References).
• Objects are approved in the order they appear in the JSON (depth-first).
• References can be defined before the objects they reference are defined.

References

When a field references an object, it may be specified in one of the following ways.

• Object - A JSON object with at least one of the following fields specified (will pick first that matches)
  • _MyID
  • UUID
  • DOID
  • OID
  • ID
  • unique/key field
• String - A JSON string that matches one of the following (will pick first that matches)
  • cQuery
  • Key=Value
  • Object Key

Object

_MyID

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

{"_MyID": 1}

UUID

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

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

DOID

Refers to the dimension-specific object ID of another object in the same cJSON 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 >