Input Schema

PIQUE Lite requires structured JSON input data to assess and visualize software quality. This section outlines the required structure and key components of the input file. PIQUE Lite does not assume a fixed or predetermined number of Quality Aspects, Product Factors, Measures, or Diagnostics. The structure and quantity of these elements depend entirely on the user-defined PIQUE model that produces the JSON output.

PIQUE Lite supports two types of input JSON files:

• Full PIQUE Output JSON: the complete output generated directly by PIQUE, containing evaluator metadata, thresholds, weights, and descriptive fields.

• Compacted JSON: a reduced and streamlined version of the full output. It keeps the same nested JSON-object sections (e.g., tqi, quality_aspects, product_factors, measures, diagnostics), but removes redundant metadata such as thresholds and diagnostic-level details. Parent–child relationships are not expressed through nested children arrays. Instead, connections between Product Factors → Measures → Diagnostics are encoded through the weights objects.

Both formats follow the same conceptual PIQUE model structure and can be used interchangeably in PIQUE Lite.

Input JSON File(s)

A valid JSON file for PIQUE Lite must represent a PIQUE quality model, including quality aspects, product factors, measures, and diagnostics. If the file is invalid or missing required structural fields, PIQUE Lite will display an error message.

As mentioned in the previous section, PIQUE Lite supports two different formats, each expressing the same model in a different way:

• Full JSON
  Uses explicit nesting. Product Factors contain children arrays of Measures; Measures contain children arrays of Diagnostics.

• Compacted JSON
  Removes nesting. Product Factors do not contain children; instead, they reference Measures through weights. Measures and Diagnostics are stored separately in their own sections, and the relationships are represented through mappings rather than array nesting.

Both formats can be uploaded to PIQUE Lite. The compacted version simply removes redundancy and reduces file size while preserving all model relationships needed for visualization. Users typically upload multiple versions of their JSON output over time. PIQUE Lite automatically visualizes these versions for comparison and trend analysis.

JSON Structure

Regardless of format, PIQUE Lite expects the same conceptual hierarchy, they should also contains the following basic items:

• Top Level:

  • name: "Binary Security Quality". Represents the total computed quality
  • value: Numeric value representing the overall quality score

• Quality Aspects:

  • name: Name of the quality aspect (e.g., "Availability")
  • value: Numeric value for the quality aspect

• Product Factors:

  • name: CWE number (e.g., "CWE-1211"). Represents a specific weakness (e.g., "Authentication Errors"). See the Factors section for more info on CWE
  • value: Numeric value for the factor

• Measures:

  • name: Name of the measure (e.g., "CVE-CWE-294 Measure")
  • value: Numeric value for the measure

• Diagnostics:

  • name: Name of the diagnostic (e.g., "CVE-CWE-294 Diagnostic")
  • value: Numeric value for the diagnostic

The number of elements at each level is not fixed and is entirely determined by the PIQUE model.

Example JSON - Full PIQUE Output JSON

The full JSON contains:

• model-level fields (e.g., name, additionalData, global_config)
• evaluator metadata, thresholds, weights
• descriptive text
• full hierarchical objects under factors

Below is an excerpt from an actual full PIQUE output:

{
  "name": "C Vendor Quality Model",
  "additionalData": {
    "projectName": "verifier"
  },
  "global_config": {
    "benchmark_strategy": "pique.calibration.MeanSDBenchmarker",
    "weights_strategy": "pique.calibration.NaiveWeighter"
  },
  "factors": {
    "product_factors": {
      "CWE-703 Improper_exception_handling": {
        "name": "CWE-703 Improper_exception_handling",
        "value": 0.0,
        "description": "The software does not properly anticipate or handle exceptional conditions...",
        "weights": { ... },
        "eval_strategy": "...",
        "normalizer": "...",
        "utility_function": "..."
      }
    }
  }
}

This version may include many additional properties that describe how PIQUE computed values.

Example JSON - Compacted JSON Format

The compacted version keeps the same nested JSON-object structure as the full PIQUE output, but removes redundant metadata (for example, thresholds and diagnostic children maps). Here are the key important aspects of the compacted formact, comparing to the full PIQUE output format:

• No children arrays appear in compacted output.
• Relationships are represented via weights object, which reference measures/diagnostics defined elsewhere.

This format reduces file size while preserving the relationships needed for visualization and analysis.

Example excerpt from a compacted PIQUE output:

{
  "name": "C Vendor Quality Model",
  "additionalData": {
    "projectName": "verifier"
  },
  "global_config": {
    "benchmark_strategy": "pique.calibration.MeanSDBenchmarker",
    "weights_strategy": "pique.calibration.NaiveWeighter"
  },
  "factors": {
    "product_factors": {
      "CWE-703 Improper_exception_handling": {
        "name": "CWE-703 Improper_exception_handling",
        "value": 0.0,
        "description": "The software does not properly anticipate or handle exceptional conditions that rarely occur during normal operation of the software.",
        "weights": {
          "CWE-703": 0.25,
          "CWE-391": 0.25,
          "CWE-252": 0.25,
          "CWE-476": 0.25
        },
        "eval_strategy": "evaluator.QualityAspectEvaluator",
        "normalizer": "pique.evaluation.DefaultNormalizer",
        "utility_function": "pique.evaluation.DefaultUtility"
      }
    }
  }
}

In the full compacted file, related measures and diagnostics appear in their own measures and diagnostics sections. The links between them and this product factor are expressed entirely through the weights objects, not through nested children arrays. This reduced structure still supports the full hierarchical model expected by PIQUE Lite.

Structure of the Quality Model

The quality model is organized hierarchically and does not require fixed counts of elements. The example structure below describes a typical PIQUE hierarchy, but actual PIQUE models may define fewer or more elements at any level.

• Quality Aspects (QA): Represent high-level characteristics.
• Product Factors (PF): Represent specific weaknesses or sub-characteristics.
• Measures: Quantify aspects of software quality.
• Diagnostics: Provide raw analysis tool findings.

Both the full and compacted formats adhere to this model.

Key Components

Factors

Factors define conceptual components of the quality model. They include:

• Total Quality Index (TQI)
• Quality Aspects
• Product Factors

In the full PIQUE output, factors may include evaluator metadata, thresholds, and weights. In the compacted version, thresholds and some redundant metadata are removed, but factors still include their names, values, descriptions, and weights objects that encode relationships to lower-level elements.

Measures

Measures are concrete, quantifiable components derived from diagnostics. They may be positive or negative depending on model configuration. Evaluation metadata appears only in the full format.

Diagnostics

Diagnostics represent the raw outputs of analysis tools. These serve as the foundation for computing measure values and factor aggregation. The compact format retains only the numeric values.