# How UAD-NG Debloat Lists (`uad_lists.json`) Are Structured and Used for Package Recommendations > Learn how UAD-NG debloat lists (uad_lists.json) structure package names and metadata to generate safe package recommendations for Android. - Repository: [Universal-Debloater-Alliance/universal-android-debloater-next-generation](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation) - Tags: internals - Published: 2026-06-20 --- **The debloat lists in Universal Android Debloater-Next Generation (UAD-NG) are JSON files embedded at compile time that map Android package names to metadata including removal safety levels, which the CLI and GUI filter to generate package recommendations.** The Universal Android Debloater-Next Generation (UAD-NG) relies on a centralized JSON database to determine which Android packages are safe to remove. Understanding the **debloat lists ([`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json)) structure** is essential for contributors and advanced users who want to customize recommendations or understand how the safety classification system works. This file drives the entire recommendation engine for both the command-line interface and the graphical user interface. ## JSON Structure and Metadata Fields The canonical debloat list resides at [`resources/assets/uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/resources/assets/uad_lists.json) in the repository root. This file contains a single JSON object where each key represents a fully-qualified Android package identifier. ### Package Identifier Keys Top-level keys use standard Android package naming conventions (e.g., `com.android.bluetooth`). Each key maps to an object containing metadata fields that drive the recommendation engine. ### Core Metadata Fields Every package entry contains the following fields: - `list` – Categorizes the source origin (`Aosp`, `Oem`, `Carrier`, `Google`, `Misc`, `Pending`, or `Unlisted`) - `description` – Human-readable explanation of the package's purpose - `dependencies` – Array of package names that must remain installed for this package to function - `neededBy` – Array of packages that depend on this one - `labels` – Optional tags for UI grouping and filtering ### The Removal Recommendation Field The `removal` field is the critical component for **package recommendations**. It accepts one of five values: - `Recommended` – Safe to remove for most users - `Advanced` – Removal requires some technical knowledge - `Expert` – Only for expert users who understand potential breakage - `Unsafe` – Likely to break core functionality - `Unlisted` – Not yet categorized ## Rust Data Models and Deserialization The UAD-NG codebase defines Rust structs that mirror the JSON schema exactly, enabling type-safe deserialization via Serde. ### The Package Struct Defined in [`crates/uad-core/src/uad_lists.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-core/src/uad_lists.rs) (lines 21-30), the `Package` struct captures every JSON field: ```rust pub struct Package { pub list: UadList, pub description: String, pub dependencies: Vec, pub needed_by: Vec, pub labels: Vec, pub removal: Removal, } ``` The type alias `PackageHashMap` represents the deserialized data as `HashMap`. ### UadList and Removal Enums Lines 32-42 define the `UadList` enum for source categorization, while lines 54-62 define the `Removal` enum for safety levels. These enums ensure that only valid values from the JSON are accepted at runtime. ## Loading and Runtime Usage UAD-NG embeds the debloat list directly into the binary to ensure offline functionality, then deserializes it at runtime. ### Embedding with include_str At line 19 of [`crates/uad-core/src/uad_lists.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-core/src/uad_lists.rs), the JSON is embedded using the `include_str!` macro: ```rust const UAD_LISTS_JSON: &str = include_str!("../../../resources/assets/uad_lists.json"); ``` This guarantees the tool ships with a complete, offline-capable database. ### The load_debloat_lists Function The `load_debloat_lists` function (lines 207-215) handles deserialization and optional remote updates: ```rust pub fn load_debloat_lists(remote: bool) -> Result { // If remote is true, attempts to fetch latest from GitHub // Otherwise, or on failure, deserializes UAD_LISTS_JSON serde_json::from_str(UAD_LISTS_JSON) .map_err(|_| /* fallback logic */) } ``` When `remote` is `false`, the function parses the embedded string. When `true`, it attempts to download the latest version from GitHub, falling back to the embedded copy on network failure. ## Filtering for Package Recommendations Both the CLI and GUI consume the `PackageHashMap` to present filtered views based on user-selected safety levels. ### CLI Filtering by Removal Level The CLI implements `RemovalFilter` in [`crates/uad-cli/src/filters.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-cli/src/filters.rs) to match packages against desired safety levels: ```rust pub enum RemovalFilter { Recommended, Advanced, Expert, Unsafe, Unlisted, } impl RemovalFilter { pub fn matches(&self, info: &PackageInfo) -> bool { match self { Self::Recommended => info.removal == Removal::Recommended, Self::Advanced => info.removal == Removal::Advanced, Self::Expert => info.removal == Removal::Expert, Self::Unsafe => info.removal == Removal::Unsafe, Self::Unlisted => info.removal == Removal::Unlisted, } } } ``` This allows users to run commands like `--filter Recommended` to see only safe removals. ### GUI Filtering and Expert Mode In the GUI layer ([`crates/uad-gui/src/views/list.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-gui/src/views/list.rs) and [`crates/uad-gui/src/widgets/package_row.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-gui/src/widgets/package_row.rs)), the `removal` field drives the visual presentation. The application checks the `expert_mode` setting before displaying `Unsafe` packages: ```rust // Inside package_row.rs if self.removal != Removal::Unsafe || settings.general.expert_mode { // Render normally } else { // Show warning badge or disable row } ``` This protects casual users from accidentally removing critical system components while allowing experts to access all options. ## Summary - The **debloat lists ([`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json))** use a JSON object structure with package IDs as keys and metadata objects as values. - The `removal` field categorizes packages into `Recommended`, `Advanced`, `Expert`, `Unsafe`, or `Unlisted` safety levels. - The file is embedded at compile time via `include_str!` in [`crates/uad-core/src/uad_lists.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-core/src/uad_lists.rs) and deserialized into a `PackageHashMap`. - The `load_debloat_lists` function supports both offline (embedded) and online (remote) loading with automatic fallback. - CLI filters use `RemovalFilter` to match packages by safety level, while the GUI respects expert mode settings when displaying `Unsafe` entries. ## Frequently Asked Questions ### What happens if uad_lists.json is corrupted or missing? UAD-NG embeds a default copy of [`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json) directly into the binary using `include_str!` at line 19 of [`crates/uad-core/src/uad_lists.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-core/src/uad_lists.rs). If the remote fetch fails or the local file is corrupted, the application falls back to this embedded version, ensuring the tool never crashes due to missing list data. ### How does UAD-NG determine the removal recommendation for a package? The `removal` field in [`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json) is manually curated by the Universal Debloater Alliance community based on testing and user reports. Each package is classified as `Recommended`, `Advanced`, `Expert`, or `Unsafe` depending on the likelihood and severity of system breakage when removed, with `Unlisted` indicating packages awaiting review. ### Can I customize the debloat lists for my specific device? Yes. While UAD-NG ships with the standard [`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json), you can modify the JSON file in the `resources/assets/` directory before compiling, or contribute device-specific entries to the upstream repository. The structure supports custom `labels` and `dependencies` to handle OEM-specific variations, and the `load_debloat_lists` function will parse your custom entries into the same `PackageHashMap` structure. ### Why does the GUI hide some packages that appear in the CLI? The GUI respects an "expert mode" setting that filters out `Removal::Unsafe` entries by default to prevent accidental system damage. In [`crates/uad-gui/src/widgets/package_row.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-gui/src/widgets/package_row.rs), the application checks this setting before rendering packages. Enable expert mode in the GUI settings to view all packages including those marked `Unsafe`.