Writing pack.mcmeta for a data pack

The minimum

A data pack is a folder or zip with two things at its root: pack.mcmeta and data/.

{
  "pack": {
    "pack_format": 61,
    "description": "What this pack does"
  }
}

That is the whole required file. pack_format is the only field that changes behaviour; description is what the player sees in the pack list.

Two rules that break most first attempts

pack.mcmeta must be at the root. Inside a zip, that means the top level of the archive. If you select your project folder and compress it, everything ends up one level down and the game finds nothing. Select the contents and compress those.

The format number is data-pack specific. Resource packs use the same field name and a completely separate sequence of numbers. If you ship both a resource pack and a data pack, you need two different numbers, and using one for both is a mistake that produces a warning in one of them and no obvious clue why.

Getting the right number

There is no formula relating pack_format to the Minecraft version. It increments when the layout changes, which happens on its own schedule.

The reliable way, and the one that does not go stale: set a deliberately wrong number, load the pack, and read the warning. The game names the format it expected. Takes a minute and is always correct for the version in front of you.

Failing that, the version's own jar contains its pack.mcmeta, which states the number by definition.

Supporting a range

Newer versions understand supported_formats:

{
  "pack": {
    "pack_format": 61,
    "supported_formats": { "min_inclusive": 57, "max_inclusive": 61 },
    "description": "Works on several versions"
  }
}

Set both. Versions that understand the range use it and load with no warning. Versions that do not ignore it and fall back to pack_format.

Declaring a range is a claim that the pack works across it. If a folder was renamed inside that range, the middle of your range silently gets a half-working pack and no warning, which is worse than the warning would have been. Test both ends.

The folder layout, and what changed

pack.mcmeta
data/
  <namespace>/
    function/
    advancement/
    recipe/
    loot_table/
    predicate/
    tags/
      block/
      item/
      function/

Several of these directories were renamed from plural to singular at a format bump: functions became function, advancements became advancement, recipes became recipe, loot_tables became loot_table.

This is the single most common reason a working data pack stops working after an update, and it is nearly invisible: the game does not report an error, it looks in the new directory, finds nothing, and loads a pack that does nothing. If your pack goes quiet after an update, check the directory names first.

Your namespace should be your own, not minecraft, unless you specifically intend to override vanilla behaviour.

Testing

/datapack list
/reload

/datapack list shows what the game actually loaded, which is the fastest way to tell a packaging problem from a content problem. If your pack is not in that list, it is not loaded, and no amount of debugging your functions will help.

/reload re-reads packs without restarting. It reloads content, not the pack list, so a newly added pack still needs a restart or a /datapack enable.

Shipping it

Put the Minecraft versions you support in your release metadata, not only in the description. That metadata is what catalogues read, including the data pack catalogue here, which filters on the exact versions each release declares. A pack that lists them properly is a pack people can find by filtering to their own version, which is how most people look.

If a format bump breaks compatibility badly enough that one file cannot cover both, ship two downloads with clear labels. Two honest downloads beat one that half works.