# desired_ilvl.json vs desired_ilvl_list.json in AzerothAuctionAssassin

> Understand the difference between desired_ilvl.json and desired_ilvl_list.json in AzerothAuctionAssassin. Learn why desired_ilvl_list.json is the actively maintained format for advanced item sniping.

- Repository: [FF14 Advanced Market Search/azerothauctionassassin](https://github.com/ff14-advanced-market-search/azerothauctionassassin)
- Tags: internals
- Published: 2026-03-01

---

**The single-object [`desired_ilvl.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl.json) is deprecated legacy code, while the array-based [`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json) is the actively maintained format that supports multiple ilvl sniping rules and additional filtering options.**

When configuring item level (ilvl) sniping in the `ff14-advanced-market-search/azerothauctionassassin` repository, users encounter two similarly named JSON files in the `AzerothAuctionAssassinData/` directory. Understanding the difference between [`desired_ilvl.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl.json) and [`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json) is critical because only one format is actively used by the current scanner engine, while the other exists solely for backward compatibility.

## Structural Differences Between the Two Formats

### Legacy Single-Rule Format (desired_ilvl.json)

[`desired_ilvl.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl.json) stores a single JSON object defining one sniping rule. It supports basic fields including `ilvl`, `buyout`, `sockets`, `speed`, `leech`, `avoidance`, and `item_ids`.

```json
{
  "ilvl": 360,
  "buyout": 1000,
  "sockets": false,
  "speed": true,
  "leech": false,
  "avoidance": false,
  "item_ids": [204965, 204930]
}

```

This format restricts users to one ilvl configuration and requires explicit `item_ids`. The file appears in `.gitignore` and the `Dockerfile` creates an empty placeholder with `printf "{}" > /app/AzerothAuctionAssassinData/desired_ilvl.json` to prevent deployment errors for legacy setups.

### Modern Multi-Rule Format (desired_ilvl_list.json)

[`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json) stores a JSON **array** of objects, allowing multiple independent sniping rules in one file. Each object supports all legacy fields plus `required_min_lvl`, `required_max_lvl`, `max_ilvl`, and `bonus_lists`. Crucially, entries can omit `item_ids` to create "broad group" rules that match any item meeting the ilvl criteria.

```json
[
  {
    "ilvl": 457,
    "buyout": 175001,
    "sockets": false,
    "speed": false,
    "leech": false,
    "avoidance": false,
    "item_ids": [208420]
  },
  {
    "ilvl": 470,
    "buyout": 250001,
    "sockets": false,
    "speed": false,
    "leech": false,
    "avoidance": false
  }
]

```

## Code Implementation and Parsing

### How the List Format Is Parsed

The active parsing logic resides in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) within the `MegaData.__set_desired_ilvl_list()` method (lines 320-388). This function reads [`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json), groups entries by ilvl, and builds comprehensive sniping entries.

```python

# utils/mega_data_setup.py

def __set_desired_ilvl_list(self, path_to_data=None):
    item_list_name = "desired_ilvl_list"
    file_name = f"{item_list_name}.json"
    env_var_name = item_list_name.upper()
    ilvl_info = {}

    # Group items by ilvl or treat as "broad" groups

    ilvl_groups = defaultdict(list)
    broad_groups = []
    for item in ilvl_info:
        if "item_ids" not in item or len(item["item_ids"]) == 0:
            broad_groups.append(item)
        else:
            ilvl_groups[item["ilvl"]].append(item["item_ids"])

    DESIRED_ILVL_LIST = []

    # Build a sniping entry for each ilvl group

    for ilvl, item_id_groups in ilvl_groups.items():
        all_item_ids = [i for g in item_id_groups for i in g]
        item_names, item_ids, base_ilvls, base_required_levels = get_ilvl_items(ilvl, all_item_ids)
        for item in ilvl_info:
            if item["ilvl"] == ilvl:
                snipe_info, _ = self.__set_desired_ilvl(item, item_names, base_ilvls, base_required_levels)
                DESIRED_ILVL_LIST.append(snipe_info)

    # Build entries for "broad" groups (no ilvl or IDs supplied)

    if broad_groups:
        item_names, item_ids, base_ilvls, base_required_levels = get_ilvl_items()
        for item in broad_groups:
            snipe_info, _ = self.__set_desired_ilvl(item, item_names, base_ilvls, base_required_levels)
            DESIRED_ILVL_LIST.append(snipe_info)

    return DESIRED_ILVL_LIST

```

The resulting `self.DESIRED_ILVL_LIST` contains fully populated dictionaries with `item_names`, `base_ilvls`, and `required_min_lvl` that the scanner consumes during live auctions.

### The Deprecated Placeholder

In the same file, the code initializes `self.DESIRED_ILVL_ITEMS` and `self.min_ilvl` as empty placeholders marked for deprecation:

```python

# utils/mega_data_setup.py

self.DESIRED_ILVL_ITEMS, self.min_ilvl = {}, 100000

```

No functional code path populates this variable from [`desired_ilvl.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl.json). The scanner in [`mega_alerts.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/mega_alerts.py) (lines 299-322) exclusively iterates over `self.DESIRED_ILVL_LIST`, making the legacy file format operationally irrelevant.

## Functional Capabilities and Use Cases

| Capability | desired_ilvl.json | desired_ilvl_list.json |
|------------|-------------------|------------------------|
| **Structure** | Single JSON object | JSON array of objects |
| **Rule Count** | One rule only | Unlimited rules |
| **Required Fields** | Must include `item_ids` | Can omit `item_ids` for broad matching |
| **Advanced Filters** | Not supported | Supports `required_min_lvl`, `required_max_lvl`, `max_ilvl`, `bonus_lists` |
| **UI Support** | None | Import/export via [`node-ui/mega-alerts.js`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/node-ui/mega-alerts.js) and [`node-ui/main.js`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/node-ui/main.js) |
| **Engine Usage** | Ignored by scanner | Consumed by [`mega_alerts.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/mega_alerts.py) |

The modern format enables complex scenarios like sniping any item above ilvl 470 regardless of specific ID, or setting different buyout thresholds for different ilvl ranges. The UI components in the `node-ui/` directory specifically handle serialization and deserialization of [`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json) for user management.

## Summary

- **[`desired_ilvl.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl.json)** is a deprecated, single-object format maintained only for backward compatibility; the scanner ignores its contents.
- **[`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json)** is the current standard—a JSON array supporting multiple rules, broad group matching (without `item_ids`), and advanced filtering options.
- The parsing logic in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) method `__set_desired_ilvl_list()` exclusively handles the list format, populating `self.DESIRED_ILVL_LIST` for use by [`mega_alerts.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/mega_alerts.py).
- The `Dockerfile` creates an empty [`desired_ilvl.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl.json) placeholder to prevent legacy deployment scripts from failing, though the application never reads from it.

## Frequently Asked Questions

### Can I still use desired_ilvl.json for ilvl sniping?

No. The current engine only reads from `DESIRED_ILVL_LIST`, which is populated exclusively from [`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json). The legacy file is initialized as an empty dictionary in [`utils/mega_data_setup.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/utils/mega_data_setup.py) and never processed by the scanning logic in [`mega_alerts.py`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/mega_alerts.py).

### How do I convert my old desired_ilvl.json to the new format?

Wrap your existing single object in square brackets to convert it to a JSON array, then rename the file to [`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json). For example, change `{ "ilvl": 360... }` to `[ { "ilvl": 360... } ]`. The UI components in [`node-ui/mega-alerts.js`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/node-ui/mega-alerts.js) also provide import/export functionality to manage these configurations graphically.

### What happens if both files exist in AzerothAuctionAssassinData?

The scanner prioritizes [`desired_ilvl_list.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl_list.json) through the `__set_desired_ilvl_list()` method. The `DESIRED_ILVL_ITEMS` variable remains an empty placeholder (`{}, 100000`), so [`desired_ilvl.json`](https://github.com/ff14-advanced-market-search/azerothauctionassassin/blob/main/desired_ilvl.json) has no effect on live scans even if present in the directory.

### Why does the Dockerfile create an empty desired_ilvl.json?

The build process runs `printf "{}" > /app/AzerothAuctionAssassinData/desired_ilvl.json` to maintain backward compatibility with legacy deployment scripts that expect the file to exist. This prevents runtime file-not-found errors for older configurations, even though the application logic no longer consumes the file's contents.