How uad_lists.json Is Structured and Used for Recommendations in Universal Android Debloater

The uad_lists.json file is a single‑level JSON object mapping Android package names to metadata objects, where the removal field encodes the recommendation level (Recommended, Advanced, Expert, or Unsafe) that drives both the GUI badge colors and CLI filtering logic.

The Universal Android Debloater Next Generation (UAD) relies on a curated JSON database to determine which system packages are safe to remove. Understanding how uad_lists.json is structured and used for recommendations is essential for contributors and advanced users who want to customize debloating behavior or integrate the tool into their own workflows.

JSON Schema and Package Metadata

The uad_lists.json file lives at resources/assets/uad_lists.json in the repository. It is a single‑level JSON object where each key is a fully qualified Android package name (e.g., "org.lineageos.jelly").

Package Metadata Fields

Each package entry contains the following fields:

• list: A string indicating the source category (e.g., Oem, Aosp, Misc, Carrier).
• description: Human‑readable text explaining the package’s purpose and removal consequences.
• dependencies: An array of package names that must remain installed for this package to function.
• neededBy: An array of packages that depend on this one.
• labels: Optional UI tags (currently unused in the baseline file).
• removal: The recommendation level that determines how safe it is to remove the package.

Example entry:

{
  "org.lineageos.jelly": {
    "list": "Oem",
    "description": "LineageOS Browser App, based on chromium.\nSafe to remove if you don't need it or have replaced it with another app.\nOtherwise there will be no browser app on your device.",
    "dependencies": [],
    "neededBy": [],
    "labels": [],
    "removal": "Recommended"
  }
}

The Removal Field and Recommendation Levels

The removal field is the core of the recommendation system. It uses four distinct levels:

• Recommended: Safe to remove for most users; no expected side effects.
• Advanced: Safe for experienced users who understand the implications.
• Expert: Only for expert users; may break specific functionality.
• Unsafe: Critical system packages that should not be removed.

Loading and Parsing the JSON

The Rust code responsible for deserializing uad_lists.json resides in crates/uad-core/src/uad_lists.rs.

Core Data Structures

The JSON maps directly to a HashMap<String, Package> type alias called UadList. The Package struct is defined as:

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Package {
    pub list: String,
    pub description: String,
    pub dependencies: Vec<String>,
    pub needed_by: Vec<String>,
    pub labels: Vec<String>,
    pub removal: Removal,
}

The Removal enum maps the string values to strongly typed variants that drive UI logic.

The Loader Function

The primary entry point is load_debloat_lists(remote: bool), which returns a Result<UadList, anyhow::Error>. The function implements a three‑tier fallback strategy:

1. If remote is true, attempt to download fresh JSON from the GitHub repository.
2. Fall back to a cached copy in the user’s cache directory ($CACHE_DIR/uad_lists.json).
3. Finally, fall back to the compiled‑in data via include_str! mapped to the constant DATA.

pub const LIST_FNAME: &str = "uad_lists.json";
pub static DATA: &str = include_str!("../../../resources/assets/uad_lists.json");

pub fn load_debloat_lists(remote: bool) -> Result<UadList, anyhow::Error> {
    // Attempts remote download, then cache, then embedded DATA
}

How Recommendations Drive the UI and CLI

Once loaded, the UadList is consumed by both the graphical interface and the command‑line tool to present recommendations to users.

GUI Badge Rendering

In crates/uad-gui/src/views/list.rs, the application calls load_debloat_lists(remote) and stores the result in UadListState. This state is passed to package_row.rs, where the removal field determines the color of the recommendation badge:

let badge = match pkg.removal {
    Removal::Recommended => badge_success("Recommended"),
    Removal::Advanced => badge_warning("Advanced"),
    Removal::Expert => badge_info("Expert"),
    Removal::Unsafe => badge_danger("Unsafe"),
};

CLI Filtering

The CLI tool in crates/uad-cli/src/commands.rs uses the same structure to filter packages. For example, to list only packages marked as Recommended:

let recommended: Vec<_> = uad_lists
    .values()
    .filter(|p| p.removal == Removal::Recommended)
    .collect();

Practical Code Examples

Loading the List with Fallback

use uad_core::uad_lists::{load_debloat_lists, UadList, DATA};

fn get_uad_list() -> UadList {
    // false = use cached/local copy; true forces remote download
    load_debloat_lists(false).unwrap_or_else(|_| {
        // Fallback to the compiled-in data if everything else fails
        DATA.parse().expect("Invalid embedded JSON")
    })
}

Checking a Specific Package’s Recommendation

use uad_core::uad_lists::{Removal, UadList};

fn get_recommendation(list: &UadList, pkg_name: &str) -> Option<Removal> {
    list.get(pkg_name).map(|pkg| pkg.removal.clone())
}

// Usage
let lists = get_uad_list();
if let Some(removal) = get_recommendation(&lists, "org.lineageos.jelly") {
    println!("Removal recommendation: {}", removal); // Prints "Recommended"
}

Filtering All Recommended Packages

let recommended_packages: Vec<_> = lists
    .iter()
    .filter(|(_, pkg)| pkg.removal == Removal::Recommended)
    .map(|(name, _)| name)
    .collect();

Summary

• uad_lists.json is a flat JSON object keyed by Android package names, located at resources/assets/uad_lists.json.
• The removal field encodes four recommendation levels (Recommended, Advanced, Expert, Unsafe) that determine safety for uninstallation.
• The load_debloat_lists function in crates/uad-core/src/uad_lists.rs handles deserialization with a remote‑first, embedded‑fallback strategy.
• Both the GUI (package_row.rs) and CLI (commands.rs) consume the Removal enum to render color‑coded badges and filter package lists.

Frequently Asked Questions

Where is uad_lists.json located in the repository?

The file is stored at resources/assets/uad_lists.json. It is also embedded directly into the binary via include_str! in crates/uad-core/src/uad_lists.rs as the constant DATA, ensuring the application can function even without an internet connection.

What do the different removal recommendation levels mean?

The removal field uses four tiers: Recommended (safe for everyone), Advanced (safe for experienced users), Expert (requires deep system knowledge), and Unsafe (critical system components). These values map to colored badges in the GUI and filter options in the CLI.

How does UAD handle missing or corrupted JSON files?

The load_debloat_lists function implements a three‑tier fallback: it first attempts to fetch the latest remote version, then checks the local cache directory, and finally falls back to the DATA constant compiled into the binary. This ensures the application never fails due to missing list files.

Can I customize the recommendations for my own device?

Yes. Advanced users can modify the uad_lists.json file in their cache directory (or edit the source file and recompile) to change removal values or add custom packages. However, changes to the dependencies and neededBy arrays require careful consideration to avoid breaking package relationships.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}