Architecture Quality JSON format

In most cases, you can use Sigrid’s Architecture Quality capability without any need to think about its internal structure. However, power users may need this information when integrating their existing systems with Sigrid’s Architecture Quality. This is usually for one of the following reasons:

• You want to customize the Architecture Quality configuration.
• You want to extract Architecture Quality data using the Sigrid API, to integrate this data with one of your own systems.

In those situations, you will need to process the “raw” architecture graph beyond Sigrid’s user interface. This page explains the internal structure of this data.

The architecture graph

The architecture is represented by a graph structure, and the JSON file containing the analysis results is basically the JSON representation of the graph. In this graph, system elements are nodes and dependencies between those system elements are edges. Note that all relations between system elements are represented by those edges, including parent/child relations. This is explained in more detail in the sections below.

Each system element has two types of measurement results:

• measurementValues refers to metrics based on the system element’s current state.
• measurementTimeSeries refers to metrics based on the system element’s change history. Time series are aggregated by interval, e.g. per week or per month. Retaining the full change history for each system element would lead to an unmanagable amount of data, so this aggregation is necessary to ensure adequate performance.

Example JSON file

The example shows a JSON file for a very small system. Note that is a different example than the one shown in the picture in the previous section.

{
  "partner": "sig",
  "customer": "examplecustomername",
  "system": "examplesystemname",
  "metadata": {
    "scopeFile": "...",
    "analysisDate": "2019-03-01 10:20:58",
    "modelVersion": "1.3",
    "historyStartDate": "2023-02-04 12:34:56",
    "historyEndDate": "2023-08-14 12:34:56",
    "historyCommitCount": 123
  },
  "snapshot": {
    "date": "2019-03-01 10:20:58"
  },
  "systemElements": [
    {
      "id" : "fc570496-c70a-11e8-a8d5-f2801f1b9fd1",
      "name": "nl.sig:aap",
      "shortName": "aap",
      "type": "CODE_COMPONENT",
      "measurementValues": {
        "LINES_OF_CODE": 123
      },
      "measurementTimeSeries": {
        "CHURN": {
          "dataPoints": {
            "2021-01-03": 100,
            "2021-01-10": 200
          },
          "averageValue": 150
        }
      },
      "observations": ["USER_INTERFACE_WEB"],
      "technology": {
        "name": "Java",
        "type": "CODE",
        "contextName": "java"
      }
    }
  ],
  "dependencies": [
    {
      "sourceElementId": "fc570496-c70a-11e8-a8d5-f2801f1b9fd1",
      "targetElementId": "fc570496-c70a-11e8-a8d5-f2801f1b9fd2",
      "type": "CODE_CALL",
      "count": 2
    }
  ]
}

Field explanations

Note: The documentation covers all supported fields. The actual JSON output might include additional fields that are not listed below. Any fields not covered by this documentation should be considered experimental.

Notes:

1. Only available for system elements of type OBSERVATION.
2. Only available for system elements of type FILE.
3. Only available for system elements of type GROUPING.
4. For components, the shortName field is intended to be used as the display name.

System element types

The terminology for “system” is somewhat ambiguous. This term is sometimes used to describe individual repositories, and sometimes used to describe the entire product. In the context of this JSON file the root system element simply refers to the scope at which the analysis was performed, regardless of whether this describes a single repository or a multi-repo system.

Files in the root of a component are grouped into a “virtual component”, since this allows for better readability in Architecture Quality compared to depicting every single file individually. These virtual components have {path}$Files as their full name, and Files as their short name. The same logic is applied to files that exist in the root of the component.

Dependency types

Dependency types are considated into three “families”:

• Hierarchy dependencies indicate parent/child relations between system elements. The graph supports multiple aggregation hierarchies, so a system element can have multiple parents. However, it can only have a single parent of the same type. Having multiple aggregation hierarchies allows us to provide multiple architecture views, in particular to separate the development view from the runtime view.
• Call dependencies are conventional code/interface/data dependencies, where a change in the callee necessitates a change in the caller.
• Hidden dependencies are relations between system elements that do not “physically” exist in the source code, but that indicate parallel evolution over time. Links between architecture observations and system elements are also considered hidden dependencies.

[1] Duplication and co-evolution don’t really differentiate between “source” and “target”, such dependencies are pretty much bidirectional. For these types, dependencies from A to B should therefore be considered to dependencies from B to A.

Architecture observations