Pack structure & pack.mcmeta

The anatomy of a Minecraft Java data pack: where it lives, how it loads, the complete folder tree and registry list, namespace rules, and the full pack.mcmeta schema — targeting 1.21+ (singular folders, pack_format 48).

What a data pack is & where it lives

A data pack is a collection of files that configures the gameplay-side, server/world data of Minecraft: functions, advancements, recipes, loot tables, predicates, item modifiers, tags, world generation, dimensions, and dynamic registries (enchantments, damage types, mob variants, and more). A data pack is either a folder or a .zip archive whose root contains a pack.mcmeta file (and optionally a pack.png icon).

Data packs affect server-side / world data only. Client-visible assets — textures, models, sounds, fonts, language files — belong to resource packs, a separate system with its own format numbers (see pack_format history).

A pack may be dropped into a world's datapacks/ folder as an unzipped folder or as a .zip. During world creation, packs can be added on the "More" → "Data Packs" screen (drag-and-drop of the folder or zip onto the game window is supported), letting you order Available vs Selected packs before the world is generated.

Enabling, disabling & /reload

The /datapack command manages packs in a loaded world (op / cheats required). Pack references use the file/<name> prefix for on-disk packs (the zip name or folder name).

# In-game commands (op / cheats required)
/datapack list                     # list all packs (available + enabled)
/datapack list available           # only disabled/available packs
/datapack list enabled             # only enabled packs, in load order
/datapack enable "file/mypack"     # enable a pack
/datapack enable "file/mypack" first   # force to front of load order
/datapack enable "file/mypack" last    # force to end of load order
/datapack enable "file/mypack" before "file/other"
/datapack enable "file/mypack" after  "file/other"
/datapack disable "file/mypack"    # disable a pack

Load order matters and can be set with first / last / before / after (see Load order & override rules).

What /reload does — and does not — reload

/reload re-reads the functions-and-data subset of packs without leaving the world: registry tags, loot tables, recipes, advancements, item modifiers, predicates, functions, and structure templates. It runs #minecraft:load afterwards.

The data pack folder tree

Every data pack has this skeleton. The only mandatory file is pack.mcmeta at the root.

<pack name>/                      # a folder OR the root of a .zip
├── pack.mcmeta                   # REQUIRED — metadata
├── pack.png                      # OPTIONAL — 128×128 icon shown in the pack list
└── data/
    └── <namespace>/              # e.g. minecraft, my_pack
        ├── function/             #  *.mcfunction
        ├── structure/            #  *.nbt
        ├── advancement/          #  *.json
        ├── recipe/               #  *.json
        ├── loot_table/           #  *.json
        ├── predicate/            #  *.json
        ├── item_modifier/        #  *.json
        ├── tags/                 #  subfolders per tagged registry
        │   ├── function/
        │   ├── block/
        │   ├── item/
        │   ├── entity_type/
        │   ├── fluid/
        │   ├── game_event/
        │   └── <other registry>/ #  e.g. tags/damage_type/, tags/worldgen/biome/ ...
        ├── worldgen/             #  subfolders per worldgen registry
        ├── dimension/            #  *.json
        ├── dimension_type/       #  *.json
        └── <dynamic registry>/   #  enchantment/, damage_type/, banner_pattern/, ...

A complete minimal pack targeting 1.21 (format 48):

# my_pack/  (a data pack targeting 1.21, format 48)
my_pack/
├── pack.mcmeta
├── pack.png
└── data/
    ├── my_pack/
    │   ├── function/
    │   │   └── hello.mcfunction          # ID: my_pack:hello
    │   └── loot_table/
    │       └── blocks/custom_ore.json    # ID: my_pack:blocks/custom_ore
    └── minecraft/
        └── tags/
            └── function/
                └── load.json             # ties into #minecraft:load

The complete registry-folder list

The folders below are the registries a 1.21+ pack can populate. They fall into three groups by how they load.

File-based (functional) folders — hot-reloadable

These are re-read by /reload.

tags/ sub-folders (registry tags)

Any registry that supports tags gets a folder under tags/; the folder name matches the singular registry name (post-1.21).

worldgen/ sub-folders (load-time dynamic registries)

worldgen/biome/
worldgen/configured_carver/
worldgen/configured_feature/
worldgen/density_function/
worldgen/noise/
worldgen/noise_settings/
worldgen/placed_feature/
worldgen/processor_list/
worldgen/structure/
worldgen/structure_set/
worldgen/template_pool/
worldgen/world_preset/
worldgen/flat_level_generator_preset/
worldgen/multi_noise_biome_source_parameter_list/

Top-level dynamic-registry folders (load-time; not hot-reloadable)

Well-established through 1.21.1 (format 48):

dimension/                 dimension_type/
banner_pattern/            chat_type/
damage_type/               painting_variant/
jukebox_song/              trim_material/
trim_pattern/              instrument/
enchantment/               enchantment_provider/
wolf_variant/

Added in later 1.21.x (verify per target version):

Each mob-variant JSON typically carries asset_id, baby_asset_id, and spawn_conditions.

Namespaces & resource locations

Everything in a pack is addressed by a resource location (also called an identifier or namespaced ID) of the form namespace:path. The file data/<namespace>/<registry>/<path>.(json|mcfunction|nbt) maps to the ID namespace:path in that registry.

Character rules

• Format: namespace:path. If the colon is omitted, the namespace defaults to minecraft (e.g. diamond → minecraft:diamond). Always writing the : is recommended.
• Valid characters: 0-9, a-z (lowercase), _ (underscore), - (hyphen), . (dot).
• / (forward slash): allowed in the path only, never in the namespace. Slashes in the path become sub-directories on disk.
• Convention is snake_case.
• The minecraft namespace holds vanilla content and can be used to override vanilla files or to place required tag files (minecraft:load, minecraft:tick).

The pack.mcmeta schema

pack.mcmeta is a JSON file at the pack root. Its top-level keys are pack (required) and the optional overlays, filter, features, and (resource-packs-only) language.

Examples

The primary form for 1.21 (format 48):

my_pack/pack.mcmeta

{
  "pack": {
    "pack_format": 48,
    "description": "My 1.21 data pack"
  }
}

A rich description via a text component:

my_pack/pack.mcmeta

{
  "pack": {
    "pack_format": 48,
    "description": [
      { "text": "My Pack ", "color": "gold", "bold": true },
      { "text": "v1.0", "color": "gray" }
    ]
  }
}

A version-range pack using the pre-25w31a supported_formats field — loads 1.21 → 1.21.4 quietly:

my_pack/pack.mcmeta

{
  "pack": {
    "pack_format": 48,
    "description": "Compatible 1.21 – 1.21.4",
    "supported_formats": { "min_inclusive": 48, "max_inclusive": 61 }
  }
}

The new min_format / max_format form (25w31a / 1.21.9+):

my_pack/pack.mcmeta

{
  "pack": {
    "description": "1.21.9+ pack",
    "min_format": [88, 0],
    "max_format": [88, 0]
  }
}

Overlays (multi-version packs)

Overlays (added 23w31a) let one pack ship alternate copies of files that the game swaps in only when the running version's format falls inside the overlay's declared range. This is the canonical way to support several Minecraft versions from a single pack when their schemas differ.

• Overlay directories live at the pack root (siblings of data/), each containing its own data/<namespace>/… tree (its own pack.mcmeta/pack.png are ignored).
• overlays.entries[] in the root pack.mcmeta maps each directory to a format range.
• When a client's format matches, the overlay's files are layered on top of the base data/.
• Directory-name characters: a-z, 0-9, _, -, and (since 23w31a) ..

The overlays block schema:

"overlays": {
  "entries": [
    {
      "directory": "<overlay folder name>",
      "formats": <int | [min,max] | {min_inclusive,max_inclusive}>   // pre-25w31a
      // 25w31a+ : replace "formats" with:
      // "min_format": <int|[maj,min]>, "max_format": <int|[maj,min]>
    }
  ]
}

Full example — one pack, base = 1.21, overlay for 1.21.2/1.21.3

# multi_ver_pack/ tree
multi_ver_pack/
├── pack.mcmeta
├── data/                         # BASE: written for 1.21 (format 48)
│   └── my_pack/recipe/thing.json
└── overlay_1_21_2/               # overlay dir (root sibling)
    └── data/
        └── my_pack/recipe/thing.json   # 1.21.2-shaped variant of the same file

The pre-25w31a form of the metadata:

multi_ver_pack/pack.mcmeta

{
  "pack": {
    "pack_format": 48,
    "description": "Works on 1.21 – 1.21.3",
    "supported_formats": { "min_inclusive": 48, "max_inclusive": 57 }
  },
  "overlays": {
    "entries": [
      {
        "directory": "overlay_1_21_2",
        "formats": { "min_inclusive": 57, "max_inclusive": 57 }
      }
    ]
  }
}

The same pack in the 25w31a+ form (min_format/max_format everywhere):

multi_ver_pack/pack.mcmeta

{
  "pack": {
    "description": "Works across the 1.21.9 boundary",
    "min_format": [48, 0],
    "max_format": [88, 0]
  },
  "overlays": {
    "entries": [
      { "directory": "overlay_1_21_9", "min_format": [88, 0], "max_format": [88, 0] }
    ]
  }
}

Load order & override rules

Multiple enabled packs are applied in a defined load order; later packs win for same-ID single files, while tags merge by default.

• Single files (functions, recipes, loot tables, advancements, …): if the same ID exists in multiple enabled packs, only the file from the last pack in load order is used (full override).
• Tags: tag JSONs merge across packs (each pack's entries are added) unless a tag file sets "replace": true, which discards earlier packs' entries for that tag.
• Vanilla is the lowest-priority pack; any data pack can override or extend it.
• Load order is set by enable position (/datapack enable … first|last|before|after) and the Available/Selected ordering on the world-creation screen. The filter block can additionally hide files from earlier-loaded packs.

Lifecycle tags: #minecraft:load & #minecraft:tick

Two vanilla function tags are how packs auto-run code. They are ordinary tags, so multiple packs contribute to them by merging.

data/minecraft/tags/function/load.json

{
  "values": [ "my_pack:setup" ]
}

data/minecraft/tags/function/tick.json

{
  "values": [ "my_pack:main_loop" ]
}

• #minecraft:load — functions listed here run once when the world loads and after each /reload. Use for initialization (scoreboards, constants).
• #minecraft:tick — functions here run every tick (20×/second). Use sparingly; heavy tick logic is the main performance pitfall.

Deep coverage of function tags, ordering, and scheduling lives in Tags. This page only establishes the fundamentals.

Sources

• Data pack — Minecraft Wiki
• pack.mcmeta — Minecraft Wiki
• Pack format — Minecraft Wiki
• Resource location — Minecraft Wiki
• Identifier — Minecraft Wiki
• /datapack command — Minecraft Wiki
• Mob variant definitions — Minecraft Wiki
• /dialog command — Minecraft Wiki
• Java Edition 1.21.5 — Minecraft Wiki
• Tutorial: Creating a data pack — Minecraft Wiki