Data component predicate

This feature is exclusive to Java Edition.

Data component predicates (known as Item sub-predicates in Java Edition 1.21.4‌^{[not in future version]}) 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^[upcoming] 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[edit | edit source]

ID	Data type and format	Data 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[edit | edit source]

attribute_modifiers[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

[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.
	24w12a	`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`.
	24w21a	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"
1.21.5	25w10a	data component predicates are now usable from block and entity predicates.

Navigation[edit | edit source]