cc.json file format

The .cc.json file format is CodeCharta’s data interchange API. Generate files from your own tools to open them in the visualization or process them with the CodeCharta Shell. A .cc.json.gz file contains the same JSON, compressed with gzip.

Structure

A 2.x file has three top-level properties:

Property	Purpose
meta	Project name, format version, checksum and optional commit hash.
files	A file tree with exactly one root folder and stable IDs for files and folders.
lenses	Analysis results, such as metrics, dependencies and domain words, joined to the file tree by node ID.

Metrics live in lenses, not on file nodes. When producing files, follow the specification’s rules for node IDs and checksums so that CodeCharta can combine results from different tools reliably.

Lenses

Lens	Purpose and availability
metrics	Per-node metric values, attribute descriptions and aggregation types.
dependency	Edges between files, dependency levels and optional declarations, namespaces and declaration-level edges.
domain	Per-node word frequencies and optional TF-IDF scores.

Unused lenses can be omitted. Unknown lenses are preserved when cc.json files are read and written. Operations that cannot safely update them may reject the file.

Minimal example

Download minimal.cc.json and open it in the visualization. It describes hello.ts with ten lines of real code (rloc) and helper.ts with five. The dependency lens records that hello.ts depends on helper.ts once. It uses format 2.1 for the dependency graph’s node levels.

{
  "meta": {
    "projectName": "Hello",
    "apiVersion": "2.1",
    "checksum": "a27742273fea0f455807fa68b3462052"
  },
  "files": [
    {
      "id": "164ddff4bb1345e1",
      "name": "root",
      "type": "Folder",
      "children": [
        {
          "id": "225cc9d293c8fed0",
          "name": "hello.ts",
          "type": "File"
        },
        {
          "id": "a4a37106220d6798",
          "name": "helper.ts",
          "type": "File"
        }
      ]
    }
  ],
  "lenses": {
    "metrics": {
      "attributes": {
        "225cc9d293c8fed0": {
          "rloc": 10
        },
        "a4a37106220d6798": {
          "rloc": 5
        }
      },
      "attributeTypes": {
        "rloc": "absolute"
      }
    },
    "dependency": {
      "edges": [
        {
          "fromId": "225cc9d293c8fed0",
          "toId": "a4a37106220d6798",
          "attributes": {
            "dependencies": 1
          }
        }
      ],
      "nodes": {
        "164ddff4bb1345e1": {
          "level": 0
        },
        "225cc9d293c8fed0": {
          "level": 1
        },
        "a4a37106220d6798": {
          "level": 0
        }
      },
      "attributeTypes": {
        "dependencies": "absolute"
      }
    }
  }
}

The edge points from the file that uses another file (fromId) to the file it uses (toId). Its dependencies attribute counts the code-level references. The nodes map places files and folders in the dependency graph: helper.ts is at level 0 and hello.ts at level 1 because it depends on helper.ts. Levels are local to siblings, not global ranks. The synthetic root is at level 0 in its own scope. The optional logical graph (declarations, namespaces and declaration-level edges) is omitted here.

More examples

For additional 2.x examples, see these files in the repository:

• Metrics and edges.
• Domain words alongside metrics and edges.

The example gallery also has larger maps from real projects, including JUnit, Apache HTTP Server and NetBeans. Those showcase files use the legacy 1.x format: the visualization opens them directly, but run ccsh convert before using them with other shell commands.

Schema and specification

Use these references when implementing an integration:

• JSON Schema (draft-07): field definitions, types and required properties.
• Format specification: examples, stable IDs, checksums, lens semantics and merge behavior.
• Schema changelog: changes between format versions.

The schema defines the structure; the specification also describes semantic rules that JSON Schema cannot express. These references are maintained in the repository rather than duplicated on this page.

Validate your output

Run the Validation Tool before opening or distributing generated files:

ccsh check minimal.cc.json

It checks the schema and references between analysis results and declared nodes. Gzip-compressed files are accepted too.

Compatibility

The shell currently writes format 2.1 and reads 2.x files. Minor versions add optional fields; breaking changes require a new major version. Older tools can reject newer files that use fields they do not recognize, so update CodeCharta when consuming those files.

The visualization also opens legacy 1.x files. For shell commands, upgrade them first with ccsh convert. See Versioning for CodeCharta’s release policy.