Checked for versions: Java Edition 1.20 to 26.3.
What actually changed
An item is now its ID plus a list of components. Each component has a fixed shape that the game checks when the command is read, which is why a typo that NBT used to swallow now stops the command. The other big difference: there are no free keys any more. A tag you used to invent, such as role:"guard", has to live inside custom_data.
The same item, before 1.20.5 and on 1.21.5 – 26.x:
/give @p minecraft:paper{display:{Name:'{"text":"Guild Pass","italic":false}'},CustomModelData:12,role:"guard"} 1
/give @p minecraft:paper[minecraft:custom_name={text:"Guild Pass",italic:false},minecraft:custom_model_data={floats:[12f]},minecraft:custom_data={role:"guard"}] 1
Old tag to component
| Before 1.20.5 | From 1.20.5 | Later change |
|---|---|---|
display.Name | custom_name, or item_name | 1.21.5: written as SNBT text, {text:"…"} |
display.Lore | lore | 1.21.5: each line SNBT text |
CustomModelData:12 | custom_model_data | 1.21.4: {floats:[12f]}, with flags, strings and colors lists |
Enchantments | enchantments | 1.21.5: {"minecraft:sharpness":3} without the levels wrapper |
AttributeModifiers | attribute_modifiers | 1.21: namespaced id; 1.21.2: no generic.; 1.21.5: a plain list |
Unbreakable:1b | unbreakable={} | |
HideFlags | show_in_tooltip fields, hide_additional_tooltip | 1.21.5: tooltip_display={hidden_components:[…]} |
Your own tags, e.g. role:"guard" | custom_data={role:"guard"} | The only place for custom keys |
display.color | dyed_color | 1.21.5: dyed_color=12345 instead of {rgb:12345} |
Potion, CustomPotionEffects | potion_contents | |
SkullOwner | profile | |
BlockEntityTag, EntityTag | block_entity_data, entity_data |
When a world is opened in a newer version, the game converts the items stored in it. Commands are not converted: command blocks, function files and saved notes keep the old syntax until you rewrite them.
The two later changes
1.21.4 changed how models are chosen. custom_model_data became four typed lists (floats, flags, strings, colors), and the resource pack picks a model through an item definition in assets/<namespace>/items/, which an item points to with the item_model component. The old overrides in item model files stopped working.
1.21.5 changed how components are written. Text components are SNBT instead of JSON strings, several components dropped their wrapper (enchantments, attribute_modifiers, dyed_color), and every show_in_tooltip field moved into one tooltip_display component.
Why custom_data matters for servers
A visible name is easy to fake with an anvil. If a shop, a door or a quest checks a hidden value in custom_data instead, a renamed vanilla item does not pass. Villager trades from 1.20.5 compare the components you list in the price, so a trade that asks for custom_data={currency:"guild_voucher"} accepts only the real voucher.
Moving a server without breaking things
- List every place items are created: command blocks, functions, loot tables, villager offers, plugin configs.
- Convert names, lore and invented tags first (
custom_data), because shops and quests read them. - If you move to 1.21.4 or later, rewrite the model hooks and the resource pack together: the command fills a slot, the item definition reads it.
- Test each item once in game before it reaches players, and keep the list somewhere the whole team can see.
FAQ
custom_name or item_name?
custom_name acts like an anvil rename and is italic unless you set italic:false. item_name is the item's own name, not italic, and an anvil cannot remove it.
Can I still add my own data to an item?
Yes, inside custom_data. It accepts any compound, and commands, predicates and villager trades can check it.
Is there an official list of components?
The game lists them in the /give auto-complete, and the Minecraft Wiki page "Data component format" documents each one with its history.