Common Trait Convention (**)


This convention is intended to bring the Ore Dictionary system from Forge to datapack's custom items. This is done by utilizing the Item's custom NBT feature. We can insert any kind of NBT inside the Item, which we can access using other commands.

With that, we can create a unified lookup system that every datapack can use to search for a specific item they want. You can then use the Common Trait Convention's provided syntax to construct a search function to find the item you need.

Example Usage

It can be hard to visualize how this convention would be useful in the real world, so we compiled some useful usage that would not be possible without this convention.

  1. Suppose you added a custom furnace which let you smelt copper ore into ingots. With this convention, you can detect for any copper ore from any datapacks to smelt it.
  2. Suppose you added a fridge block that only accepts food items. With this convention, you can detect any food items, even the custom ones from other datapacks.
  3. Suppose you added a custom anvil which lets you repair tools straight from the material instead of the ingot. With this convention, you can detect any kind of material from other datapacks, even when the base material doesn't match.


Traits represent behavior and properties that an object can have. By specifying these traits inside the item's NBT, other datapacks will be able to refer to that item via traits instead of item IDs directly.

Traits are a compound tag of strings to booleans and so will look like this in NBT (notice traits: {...}?)

/give @s diamond{ctc: {traits: {"some": 1b, "trait": 1b, "here": 1b}, id: "example", from: "convention:wiki"}}

Do note that there is no underlying mechanic that separates traits from any general NBT in the minecraft engine, we are creating this mechanic ourselves.


Common Trait Convention's syntax will be stored inside the ctc NBT of an item. Inside ctc are the NBT tags: id, from and traits.

  • id: The internal ID of your item. This doesn't matter outside your datapack, but should be unique within your datapack.
  • from: A namespace specifying which datapack the item comes from.
  • traits: A set of traits.

For example, We will use an expanded form of the NBT used in /give command for readability. (but it's actually compacted into one line)

/give @s minecraft:iron_ore{
    ctc: {
        id: "my_copper_ore",
        from: "convention:wiki",
        traits: {"metal/copper": 1b, "block": 1b, "ore": 1b}
} 1

Minecraft does not have a set data type, so we replicate it using a compound tag. This means every trait must have a value of 1b or true to stay consistent.

Let's look at these traits:

  • metal/copper. This trait tells us that this item is copper.
  • block. This trait tells us that this item is a placeable block.
  • ore. This trait tells us that this item is an ore.


  • When you are attempting to check for a custom item using id tag must be done alongside from tag as well, you cannot separate it because it would break compatibility.
  • The opposite of the above is not true, you can check for from tag without requiring id tag.
  • If you use id tag to check for a custom item, there is no need to check for traits tag as well.

Slash Notation

In the above example, you will notice the use of / in metal/copper. This is used for categorization when a name alone could be ambiguous or difficult to understand. For example, what would the trait orange mean? Is it the color orange or the fruit orange?

In such a case we'd use slash notation to separate them. color/orange and fruit/orange


To detect or check for trait items you just need to check the traits NBT of the item.

Detect if the player is holding a weapon

execute as @a if data entity @s SelectedItem.tag.ctc.traits."tool/weapon" run ...

This command detects if the item the player is holding has the trait tool/weapon.

Detect if the container contains copper ore

execute if block ~ ~ ~ Items[].tag.ctc.traits{"metal/copper": 1b, "ore": 1b} run ...

This command detects if the container contains an item with the traits metal/copper and ore

Detect if the container contains a placeable item

execute if block ~ ~ ~ Items[].tag.ctc.traits."block" run ...

This command detects if the container contains an item with the trait block.

While quotes around the trait are not necessary in all cases, I always keep them there to stay consistent.

Basic Traits

This is a provided list of traits that you can use. This doesn't mean you can't create new traits for your own use, but if there is a trait that suits your need in the list, you should use it.

The list is split into multiple groups and you should not use traits from the same group twice.

Object Type Group

This trait represents the state of the matter that this item holds.

gasGaseous substance
liquidLiquid substance
blockPlaceable item
itemNormal minecraft item

Special Type Group

This group represents common traits from Minecraft.

This group is an exception to the rule above, you can use multiple traits from this group as much as you like.

oreOre block that can usually be found in caves
seedItem that can be used to grow plants
flowerFlower item
grassBlock that can spread from one block to another
saplingBlock that can grow into a tree
vegetableFood item that comes from seed
logItem that drops from tree trunk
planksItem that comes from processing log

Compression Group

This trait represents an item that can be combined to create a more compact version of itself and vice versa.

For example:

  • redstone dust -> redstone block
  • ice -> packed ice
  • iron block -> iron ingot
packedMost packed form of item, usually a block
ingotNormal form of item, usually an ingot
nuggetSmallest form of item, usually a nugget

Edible Group

This trait represents an edible item that can be used by the player (drinking included).

foodAll types of edible item

Armor Group

This trait represents an item that can be worn by players and other entities.

armorAll types of wearable item

Tool Sub-group

This trait uses Slash Notation!

This trait represents an item that can be used to interact with the world.

tool/miningThis item can be used to mine stone-like blocks
tool/choppingThis item can be used to cut wooden blocks
tool/tillingThis item can be used to till soil
tool/wateringThis item can be used to water soil
tool/weaponThis item can be used to fight monsters and other players

Gem Sub-group

This trait uses Slash Notation!

This trait represents any item that has a crystalline structure.

gem/diamondDiamond gemstone
gem/rubyRuby gemstone
gem/emeraldEmerald gemstone
gem/sapphireSapphire gemstone
gem/lapisLapis Lazuli gemstone
gem/obsidianAny Obsidian material
gem/quartzAny Quartz material
gem/opalOpal gemstone

Metal Sub-group

This trait use Slash Notation!

This trait represents common metallic items.

metal/ironItem made up of iron
metal/goldItem made up of gold
metal/copperItem made up of copper
metal/aluminiumItem made up of aluminium
metal/tinItem made up of tin
metal/silverItem made up of silver
metal/leadItem made up of lead
metal/nickelItem made up of nickel
metal/platinumItem that made up of platinum