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.