NBT path format

From Minecraft Wiki
Jump to: navigation, search
Information icon.svg
This feature is exclusive to Java Edition.

An NBT path is a descriptive label used to specify a collection of particular elements from an NBT data tree. A path has the general form node.….node, where each node declares what types of sub-elements can be chosen from a previous tag.

Node[edit]

These are all seven types of nodes available.

The tags collection start with only one element (i.e. the root tag) and changes along the nodes on the path. NBT path consumers operate on the final collection of the tags.

Name Format Description Selection Result Example Example Description
Root Compound Tag {tag}, where tag is the compound NBT content and can be empty. Selects the starting tag only if it matches the compound tag given (if given).
Only applicable as the first element in the path.
The starting tag, or nothing if matching fails. {Invisible:1b} Selects the root tag if it has a subtag  Invisible with value 1.
{} Selects the root tag.
Named Tag name, where name can be a plain or an escaped string Selects the subtags named name in the previous tags. A collection of tags; no more elements than the previous tag collection. May be nothing. VillagerData Selects the VillagerData subtag.
"A cool name[]" Selects the A cool name[] subtag.
Named Compound Tag name{tag}, where name can be a plain or an escaped string, and tag is the compound NBT content which can be empty. Selects the sub compound tags matching the compound tag given (if given) and named name in the previous tags. A collection of compound tags; no more elements than the previous tag collection. May be nothing. VillagerData{profession:"minecraft:nitwit"} Select the  VillagerData tag only if it has a subtag  profession with value minecraft:nitwit.
VillagerData{} Selects the  VillagerData tag if it is a compound tag.
Element of Named List or Array Tag name[index], where name can be a plain or an escaped string and index is an integer. Selects elements at index (or listLength + index if index is negative) of the lists (or array) named name in the previous tags. A collection of tags; no more elements than the previous tag collection. May be nothing. Pos[0] Selects the first child tag in the "Pos" sublist (or array).
Inventory[-1] Selects the last child tag in the "Inventory" sublist (or array).
All Elements of Named List or Array Tag name[] Selects all elements of the sub-lists (or array) named name in the previous tags. A collection of tags; may have more elements than the previous tag collection. May be nothing. ActiveEffects[] Select all the elements in the "ActiveEffects" subtag of the last tag.
Compound Elements of Named List Tag name[{tag}], where name can be a plain or an escaped string and tag is the compound NBT content which can be empty. Selects the compound elements matching the compound tag given (if given) and in the lists named name in the previous tags. A collection of compound tags; may have more elements than the previous tag collection. May be nothing. Inventory[{Count:25b}] Select the elements of  Inventory tag that has a subtag  Count with value 25.
Foo[{}] Selects the elements of  Foo tag.
Elements of Sub-List (or Array) of Named List Tag name[index or blank][index or blank][index or blank]......[index or tag], where name can be a plain or an escaped string, index is an integer, and tag is the compound NBT content which can be empty. Selects the child elements of the child elements in the lists named name in the previous tags. A collection of tags; may have more elements than the previous tag collection. May be nothing. foo[][{}] Select the elements of the sub-lists in sub-lists in  foo tag.
foo.bar[0][0].baz Select the baz tag in the first element of the first element of the bar list in the  foo tag.

In the path, . (dot/period) characters separate the nodes. The nodes can be mixed and matched, except the root node with object must be the first in the path when it is present.

Name escaping[edit]

The valid character set (without quote) for a path seems to be all non-whitespace characters, as long as any opening brackets and braces ([ and {) are closed and at the end of each term (that is, followed by nothing but a period or the end of the path—. or ). That being said, the "reasonable character set" for defining a data tag includes all lowercase and uppercase letters, numbers, underscore, period, and square and curly brackets (Regular expression: [a-zA-Z0-9\.[\]{}]*)

Quoted strings, such as "Lorem ipsum", may be used if a name of a key needs to be escaped.

Examples[edit]

Mixed path[edit]

  • {}—Specifies the root tag
  • {foo:4.0f}—Specifies the root tag if the "foo" subtag is set to 4.0f
  • foo—Specifies the tag named "foo" under the root tag
  • foo.bar or foo{}.bar—Specifies foo's subtag named "bar".
  • foo.bar[0]—Specifies the first element of the list (or array) "bar"
  • foo.bar[-1]—Specifies the last element of the list (or array) "bar"
  • foo.bar[0]."A [crazy name]!"—Specifies the subtag named "A [crazy name]!" under that first element
  • foo.bar[0]."A [crazy name]!".baz—Specifies the subtag named "baz" under that crazily named tag
  • foo.bar[]—Specifies all elements of the list (or array) "bar"
  • foo.bar[].baz—Specifies the subtags named "baz" under all elements of the list "bar"
  • foo.bar[{baz:5b}]—Specifies all elements of the list "bar", in which the "baz" tag is set to 5b
  • foo{bar:"baz"}—Specifies the "foo" tag if its subtag "bar" has the value "baz"
  • foo{bar:"baz"}.bar—Specifies the "bar" tag if it matches the value "baz"

Example 1[edit]

/data get entity @p foo.bar[0]."A [crazy name]!".baz

These names have been arbitrarily picked, for demonstrative purposes.

  • foo—Specifies the subtag named "foo" under the root tag.
  • foo.bar—Specifies foo's child named "bar".
  • foo.bar[0]—Specifies the first element of the list "bar"
  • foo.bar[0]."A [crazy name]!"—Specifies the child named "A [crazy name]!" under that first element
  • foo.bar[0]."A [crazy name]!".baz—Specifies the child named "baz" under that crazily named element

Example 2[edit]

/data get block ~ ~ ~ Items[1].tag.pages[3]

A player has written a book and placed it inside a chest at their feet, and are going to work up to the above command in stages. Observe the following imaginary chat log: