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

> Discover how uad_lists.json structures Android package data and uses removal recommendations to guide debloating decisions and badge colors in Universal Android Debloater. Safely manage your device.

- Repository: [Universal-Debloater-Alliance/universal-android-debloater-next-generation](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation)
- Tags: api-reference
- Published: 2026-06-18

---

**The [`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json) file lives 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. 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:**

```json
{
  "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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json) resides 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).

### Core Data Structures

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

```rust
#[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`.

```rust
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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/package_row.rs), where the `removal` field determines the color of the recommendation badge:

```rust
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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-cli/src/commands.rs) uses the same structure to filter packages. For example, to list only packages marked as `Recommended`:

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

```

## Practical Code Examples

### Loading the List with Fallback

```rust
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

```rust
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

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

```

## Summary

- **[`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json)** is a flat JSON object keyed by Android package names, located at [`resources/assets/uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-core/src/uad_lists.rs) handles deserialization with a remote‑first, embedded‑fallback strategy.
- Both the **GUI** ([`package_row.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/package_row.rs)) and **CLI** ([`commands.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/resources/assets/uad_lists.json). It is also embedded directly into the binary 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) 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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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.