Schema Version 1.0 (Stable)

JSON Report Schema Contract

This specification defines the machine-readable JSON structure produced by JsonReportExporter in Voodoo Hardware Info. It allows automated parsers, CI test harnesses, and AI models to ingest device reports deterministically.

Root Object Structure

The root JSON document contains exactly three primary top-level keys:

Key Type Description
metadata object Schema version, generator application version, and UTC timestamps.
device object High-level device summary: manufacturer, model, build fingerprint, and OS release.
categories object Dictionary of exported categories keyed by category ID (e.g. "soc", "camera").

Field Object Schema Definition

Every hardware property in the fields array adheres to this strict dictionary contract:

Property Type Presence Description
id string Required Namespaced identifier (e.g. soc.core_count, memory.total_bytes).
display_name string Required Human-readable label shown in the UI.
data_type string Required Enum: BOOLEAN, INTEGER, FLOAT, STRING, BYTES, LIST.
availability string Required Canonical state: AVAILABLE, UNSUPPORTED, PERMISSION_REQUIRED, PERMISSION_DENIED, ROOT_REQUIRED, RESTRICTED_BY_ANDROID, RETRIEVAL_FAILED, UNKNOWN.
value primitive | null Required Native JSON type (boolean, integer, float, string) if AVAILABLE; null otherwise.
unavailability_reason string Conditional Present only when availability != AVAILABLE. Explains why the field could not be retrieved.
formatted_value string Required Pre-formatted userland representation with units (e.g. "8 GB", "2.73 GHz").
source string Required Enum: ANDROID_API, LINUX_PROC, LINUX_SYSFS, SYSTEM_PROPERTY, ROOT_SHELL.
retrieval_method string Required Exact technical method or file path used (e.g. "ActivityManager.MemoryInfo.totalMem", "/proc/zoneinfo").
min_api_required integer Required Minimum Android API level where this retrieval method is valid.
confidence string Required Enum: DIRECT_MEASUREMENT, INFERRED, FALLBACK.
requires_root boolean Optional True if elevated root access is required to read this field.
permission_required string Optional Manifest permission required (e.g. "android.permission.ACCESS_FINE_LOCATION").

Illustrative JSON Segment

Below is an illustrative JSON excerpt generated from the Kotlin JsonReportExporter showing both an available integer metric and an unavailable property:

{
  "metadata": {
    "schema_version": 1,
    "app_name": "Voodoo Hardware Info",
    "app_version": "1.0",
    "timestamp_ms": 1795000000000,
    "timestamp_utc": "2026-11-19T10:30:00Z",
    "categories_exported": 18
  },
  "device": {
    "manufacturer": "Samsung",
    "brand": "samsung",
    "model": "SM-G973F",
    "device_codename": "beyond1",
    "product": "beyond1ltexx",
    "hardware": "exynos9820",
    "android_release": "12",
    "sdk_int": 31,
    "fingerprint": "samsung/beyond1ltexx/beyond1:12/SP1A.210812.016/G973FXXSGHVI1:user/release-keys"
  },
  "categories": {
    "soc": {
      "category_id": "soc",
      "display_name": "SoC",
      "collection_duration_ms": 14,
      "has_errors": false,
      "total_fields": 22,
      "available_fields": 22,
      "fields": [
        {
          "id": "soc.core_count",
          "display_name": "CPU Core Count",
          "data_type": "INTEGER",
          "availability": "AVAILABLE",
          "value": 8,
          "formatted_value": "8 Cores",
          "source": "LINUX_SYSFS",
          "source_display": "Linux Sysfs (/sys)",
          "retrieval_method": "/sys/devices/system/cpu/possible",
          "min_api_required": 1,
          "confidence": "DIRECT_MEASUREMENT"
        },
        {
          "id": "soc.gpu_clock_mhz",
          "display_name": "GPU Current Frequency",
          "data_type": "INTEGER",
          "availability": "ROOT_REQUIRED",
          "value": null,
          "unavailability_reason": "Root Access Required",
          "formatted_value": "[Root Access Required]",
          "source": "LINUX_SYSFS",
          "source_display": "Linux Sysfs (/sys)",
          "retrieval_method": "/sys/class/kgsl/kgsl-3d0/gpuclk",
          "min_api_required": 1,
          "confidence": "DIRECT_MEASUREMENT",
          "requires_root": true
        }
      ]
    }
  }
}

Schema Changelog

v1.0 (2026-11-19): Initial versioned JSON schema implementation in Phase 9. Preserves native primitives, records 9 explicit availability states, and encapsulates provenance metadata.