Data component predicateShare feedback

Data component predicates (known as Item sub-predicates in Java Edition 1.21.4‌) are used to check conditions about data components. They are used in minecraft:item_predicate argument type, item modifiers, loot predicates, or advancement criteria. ‌In Java Edition 1.21.5​ they can also be used in entity and block predicates. They return a pass or fail result to the invoker, who acts differently based on this result.

List of data component predicate types

ID	Data type and format	CollapseData components to check
attribute_modifiers	[NBT Compound / JSON Object] Object, see below	attribute_modifiers
bundle_contents	[NBT Compound / JSON Object] Object, see below	bundle_contents
container	[NBT Compound / JSON Object] Object, see below	container
custom_data	[String] String or [NBT Compound / JSON Object] Object, see below	custom_data
damage	[NBT Compound / JSON Object] Object, see below	damage and max_damage
enchantments	[NBT List / JSON Array] Array, see below	enchantments
firework_explosion	[NBT Compound / JSON Object] Object, see below	firework_explosion
fireworks	[NBT Compound / JSON Object] Object, see below	fireworks
jukebox_playable	[NBT Compound / JSON Object] Object，see below	jukebox_playable
potion_contents	[String] String or [NBT List / JSON Array] Array, see below	potion_contents
stored_enchantments	[NBT List / JSON Array] Array, see below	stored_enchantments
trim	[NBT Compound / JSON Object] Object, see below	trim
writable_book_content	[NBT Compound / JSON Object] Object, see below	writable_book_content
written_book_content	[NBT Compound / JSON Object] Object, see below	written_book_content

Formats

attribute_modifiers

Checks modifiers in the attribute_modifiers data component.

• [NBT Compound / JSON Object] minecraft:attribute_modifiers
  • [NBT Compound / JSON Object] modifiers: (Optional) A collection predicate of attribute modifier.
    • [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any attribute modifier passing a test. To succeed, each test must be passed by at least one attribute modifier, but one attribute modifier does not have to pass all the tests.
      • [NBT Compound / JSON Object]: A test.
        • Predicate of attribute modifier see Template:Nbt inherit/attribute_modifier/template[show]
    • [Int] size: (Optional) Checks the total number of attribute modifiers. Matches an exact [Int]value, or checks if the value is between a range.
    • [NBT Compound / JSON Object] size: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.
    • [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of attribute modifiers that pass a test.
      • [NBT Compound / JSON Object]: A test and required number.
        • [NBT Compound / JSON Object] test: A test.
          • Predicate of attribute modifier see Template:Nbt inherit/attribute_modifier/template[show]
        • [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
        • [NBT Compound / JSON Object] count: Another format.
          • [Int] max: The maximum value.
          • [Int] min: The minimum value.

bundle_contents

Checks item stacks in the bundle_contents data component.

• [NBT Compound / JSON Object] minecraft:bundle_contents
  • [NBT Compound / JSON Object] items: (Optional) A collection predicate of item stack.
    • [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any item stack passing a test. To succeed, each test must be passed by at least one item stack, but one item stack does not have to pass all the tests.
      • [NBT Compound / JSON Object]: A test.
        • All possible conditions for items see Template:Nbt inherit/conditions/item/template[show]
    • [Int] size: (Optional) Checks the total number of item stacks. Matches an exact [Int]value, or checks if the value is between a range.
    • [NBT Compound / JSON Object] size: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.
    • [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of item stacks that pass a test.
      • [NBT Compound / JSON Object]: A test and required number.
        • [NBT Compound / JSON Object] test: A test.
          • All possible conditions for items see Template:Nbt inherit/conditions/item/template[show]
        • [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
        • [NBT Compound / JSON Object] count: Another format.
          • [Int] max: The maximum value.
          • [Int] min: The minimum value.

container

Checks item stacks in the container data component.

• [NBT Compound / JSON Object] minecraft:container
  • [NBT Compound / JSON Object] items: (Optional) A collection predicate of item stack.
    • [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any item stack passing a test. To succeed, each test must be passed by at least one item stack, but one item stack does not have to pass all the tests.
      • [NBT Compound / JSON Object]: A test.
        • All possible conditions for items see Template:Nbt inherit/conditions/item/template[show]
    • [Int] size: (Optional) Checks the total number of item stacks. Matches an exact [Int]value, or checks if the value is between a range.
    • [NBT Compound / JSON Object] size: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.
    • [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of item stacks that pass a test.
      • [NBT Compound / JSON Object]: A test and required number.
        • [NBT Compound / JSON Object] test: A test.
          • All possible conditions for items see Template:Nbt inherit/conditions/item/template[show]
        • [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
        • [NBT Compound / JSON Object] count: Another format.
          • [Int] max: The maximum value.
          • [Int] min: The minimum value.

custom_data

Checks custom_data data component. See NBT format § Testing NBT tags and NBT format § Conversion from JSON.

Either as a JSON object or an NBT compound tag, or a string. If a string, it is resolved into an NBT compound tag.

• [String][NBT Compound / JSON Object] minecraft:custom_data

damage

Checks remaining durability or damage value. Damage value is from the damage data component; remaining durability is the value max_damage data component minus damage value.

• [NBT Compound / JSON Object] minecraft:damage
  • [Int] damage: (Optional) Checks damage value. Matches an exact [Int]value, or checks if the value is between a range.
  • [NBT Compound / JSON Object] damage: (Optional) Another format.
    • [Int] max: (Optional) The maximum value.
    • [Int] min: (Optional) The minimum value.
  • [Int] durability: (Optional) Checks remaining durability. Matches an exact [Int]value, or checks if the value is between a range.
  • [NBT Compound / JSON Object] durability: (Optional) Another format.
    • [Int] max: (Optional) The maximum value.
    • [Int] min: (Optional) The minimum value.

enchantments

Checks enchantments on the item (enchantments in the enchantments data component).

• [NBT List / JSON Array] minecraft:enchantments: Array of conditions. The sub-predicate succeeds when all the conditions succeed.
  • [NBT Compound / JSON Object]: A condition.
    • [String][NBT List / JSON Array] enchantments: (Optional) Any number of enchantment(s) (an [String] ID, or a [String] tag with #, or an [NBT List / JSON Array] array containing [String] IDs). If more than one enchantment is specified, succeeds when any one of them is present.
    • [Int] levels: (Optional) Checks the level of the specified enchantment. Matches an exact [Int]value, or checks if the value is between a range. If more than one enchantment is specified, succeeds when any one of them matches the level. If [String][NBT List / JSON Array] enchantment is not specified, succeeds when any one of enchantments on the item matches the level.
    • [NBT Compound / JSON Object] levels: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.

firework_explosion

Checks the firework_explosion data component.

• [NBT Compound / JSON Object] minecraft:firework_explosion
  • Predicate of firework explosion effect see Template:Nbt inherit/firework predicate/template[show]

fireworks

Checks explosion effects in the fireworks data component.

• [NBT Compound / JSON Object] minecraft:fireworks
  • [NBT Compound / JSON Object] explosions: (Optional) A collection predicate of explosion effect.
    • [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any explosion effect passing a test. To succeed, each test must be passed by at least one explosion effect, but one explosion effect does not have to pass all the tests.
      • [NBT Compound / JSON Object]: A test.
        • Predicate of firework explosion effect see Template:Nbt inherit/firework predicate/template[show]
    • [Int] size: (Optional) Checks the total number of explosion effects. Matches an exact [Int]value, or checks if the value is between a range.
    • [NBT Compound / JSON Object] size: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.
    • [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of explosion effects that pass a test.
      • [NBT Compound / JSON Object]: A test and required number.
        • [NBT Compound / JSON Object] test: A test.
          • Predicate of firework explosion effect see Template:Nbt inherit/firework predicate/template[show]
        • [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
        • [NBT Compound / JSON Object] count: Another format.
          • [Int] max: The maximum value.
          • [Int] min: The minimum value.
  • [Int] flight_duration: (Optional) Checks the flight duration of this firework rocket, i.e. the number of gunpowders used to craft it. Matches an exact [Int]value, or checks if the value is between a range.
  • [NBT Compound / JSON Object] flight_duration: (Optional) Another format.
    • [Int] max: (Optional) The maximum value.
    • [Int] min: (Optional) The minimum value.

jukebox_playable

Checks jukebox song in the jukebox_playable data component.

• [NBT Compound / JSON Object] minecraft:jukebox_playable
  • [String][NBT List / JSON Array] song: (Optional) Any number of jukebox song(s) (an [String] ID, or a [String] tag with #, or an [NBT List / JSON Array] array containing [String] IDs). If more than one jukebox song is specified, succeeds when any one of them matches the testing song.

potion_contents

Checks [String] potion field in the potion_contents data component. Fails if there is no [String] potion field in the component.

• [String][NBT List / JSON Array] minecraft:potion_contents: Any number of potion type(s) (an [String] ID, or a [String] tag with #, or an [NBT List / JSON Array] array containing [String] IDs). If more than one potion type is specified, succeeds when any one of them matches the testing [String] potion field.

stored_enchantments

Checks enchantments on an enchanted book (enchantments in the stored_enchantments data component).

• [NBT List / JSON Array] minecraft:stored_enchantments: Array of conditions. The sub-predicate successes when all the conditions success.
  • [NBT Compound / JSON Object]: A condition.
    • [String][NBT List / JSON Array] enchantments: (Optional) Any number of enchantment(s) (an [String] ID, or a [String] tag with #, or an [NBT List / JSON Array] array containing [String] IDs). If more than one enchantment is specified, succeeds when any one of them is present.
    • [Int] levels: (Optional) Checks the level of the specified enchantment. Matches an exact [Int]value, or checks if the value is between a range. If more than one enchantment is specified, succeeds when any one of them matches the level. If [String][NBT List / JSON Array] enchantment is not specified, succeeds when any one of enchantments on the item matches the level.
    • [NBT Compound / JSON Object] levels: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.

trim

Checks the trim data component.

• [NBT Compound / JSON Object] minecraft:trim
  • [NBT List / JSON Array][String] material: (Optional) Any number of trim material(s) (an [String] ID, or a [String] tag with #, or an [NBT List / JSON Array] array containing [String] IDs) If more than one trim material is specified, succeeds when any one of them matches the testing trim material.
  • [NBT List / JSON Array][String] pattern: (Optional) Any number of trim pattern(s) (an [String] ID, or a [String] tag with #, or an [NBT List / JSON Array] array containing [String] IDs) If more than one trim pattern is specified, succeeds when any one of them matches the testing trim pattern.

writable_book_content

Checks pages in the writable_book_content data component. Raw texts are checked instead of filtered texts.

• [NBT Compound / JSON Object] minecraft:writable_book_content
  • [NBT Compound / JSON Object] pages: (Optional) A collection predicate of page.
    • [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any page passing a test. To succeed, each test must be passed by at least one page, but one page does not have to pass all the tests.
    • [String]: A test. Matches the full string of a page.
    • [Int] size: (Optional) Checks the total number of pages. Matches an exact [Int]value, or checks if the value is between a range.
    • [NBT Compound / JSON Object] size: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.
    • [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of pages that pass a test.
      • [NBT Compound / JSON Object]: A test and required number.
        • [String] test: A test. Matches the full string of a page.
        • [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
        • [NBT Compound / JSON Object] count: Another format.
          • [Int] max: The maximum value.
          • [Int] min: The minimum value.

written_book_content

Checks written_book_content data component.

• [NBT Compound / JSON Object] minecraft:written_book_content
  • [NBT Compound / JSON Object] pages: (Optional) A collection predicate of page. Checks the raw texts of pages instead of filtered texts.
    • [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any page passing a test. To succeed, each test must be passed by at least one page, but one page does not have to pass all the tests.
    • [Undefined]: A test. A text component. Matches the full text of a page.
    • [Int] size: (Optional) Checks the total number of pages. Matches an exact [Int]value, or checks if the value is between a range.
    • [NBT Compound / JSON Object] size: (Optional) Another format.
      • [Int] max: (Optional) The maximum value.
      • [Int] min: (Optional) The minimum value.
    • [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of pages that pass a test.
      • [NBT Compound / JSON Object]: A test and required number.
        • [Undefined] test: A test. A text component. Matches the full text of a page.
        • [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
        • [NBT Compound / JSON Object] count: Another format.
          • [Int] max: The maximum value.
          • [Int] min: The minimum value.
  • [String] author: (Optional) Matches the full string of author.
  • [String] title: (Optional) Matches the full string of title. Checks raw title instead of filtered title.
  • [Int] generation: (Optional) Checks the number of times this written book has been copied. 0 = original, 1 = copy of original, 2 = copy of copy, 3 = tattered. Matches an exact [Int]value, or checks if the value is between a range.
  • [NBT Compound / JSON Object] generation: (Optional) Another format.
    • [Int] max: (Optional) The maximum value.
    • [Int] min: (Optional) The minimum value.
  • [Boolean] resolved: (Optional) Checks whether the JSON text components have already been resolved (the [Boolean] resolved field in the data component is true).

History

[hide]Java Edition
1.20.5			24w11a				Added item sub-predicate.
			24w12a				Now item sub-predicate can be used in minecraft:item_predicate argument type.
							custom_data now can be defined in JSON object or NBT compound tag. Before, it can only be a quoted string of a SNBT.
			pre1				Added 8 new item sub-predicate types: container, bundle_contents, firework_explosion, fireworks, writable_book_content, written_book_content, attribute_modifiers, and trim.
1.21			24w18a				In enchantments and stored_enchantments, enchantment field is replaced by enchantments, and now can specify multiple enchantments.
			24w21a				Added a new item sub_predicate type jukebox_playable.
							In attribute_modifiers, name, and uuid fields are replaced by id.
[hide]Upcoming Java Edition
1.21.5			25w04a				renamed item sub-predicate to "data component predicate"
			25w10a				data component predicates are now usable from block and entity predicates.