NBT path format

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 child tags can be chosen from previous tags.

Nodes

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 when resolving path. Tags in the final tag collection are just the targets selected by the NBT path.

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

In an NBT path, . (dot/period) characters separate the nodes. Required nodes can be used arbitrarily, except the root compound tag node must be the first in the path when it is present.

Name escaping

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 node (that is, followed by nothing but a period or the end of the path). That being said, the "reasonable character set" for defining a tag name includes all ASCII lowercase and uppercase letters, digits, underscore, period, and square and curly brackets (Regular expression: [a-zA-Z0-9_\.[\]{}]*).

Quoted strings, such as "Lorem ipsum" or 'Lorem ipsum', can be used if a tag name needs to be escaped.

Examples

Mixed path

• {}—Specifies the root tag
• {foo:4.0f}—Specifies the root tag if its children tag "foo" is 4.0f
• foo—Specifies the tag named "foo" under the root tag
• foo.bar or foo{}.bar—Specifies foo's children tag 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 children tag named "A [crazy name]!" under that first element
• foo.bar[0]."A [crazy name]!".baz—Specifies the children tag named "baz" under that crazily named tag
• foo.bar[]—Specifies all elements of the list (or array) "bar"
• foo.bar[].baz—Specifies the children tags named "baz" under all elements of the list "bar"
• foo.bar[{baz:5b}]—Specifies all elements of the list "bar", in which the "baz" tags are 5b
• foo{bar:"baz"}—Specifies the "foo" tag if its child tag "bar" has the value "baz"
• foo{bar:"baz"}.bar—Specifies the "bar" tag under "foo", only if it matches the value "baz"

Example 1

/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

The tree structure

• The root entity data
  •  foo: The "foo" element
    •  bar: The "bar" element
      • The first element of list "bar"
        •  A [crazy name]!: The "A [crazy name]!" element
          •  baz: The "baz" element; the target element of this example.
      • Another unrelated element in list "bar"

Example 2

/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:

Chat log

* Alex jumps on top of a chest. * Alex runs the command: /data get block ~ ~ ~ 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex only wants to look at the chest's inventory. They could search the Minecraft Wiki for what the name of that tag is, but because they understand how to read NBT format they decide to figure it out from that last command's output. * Alex runs the command: /data get block ~ ~ ~ Items 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants to narrow this down to the second item in the chest. Counting from 0, the second item would be element 1. * Alex runs the command: /data get block ~ ~ ~ Items[1] 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the "tag" tag. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the "pages" tag. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag.pages 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the fourth element from this list. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag.pages[3] 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex has what they need now, and uses the paths they have gathered to edit the book from outside the chest. * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.pages[3] set value '{"text":"And this pig here\'s named Babe."}' Modified block data of 0 55 0 * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.pages prepend value '{"text":"Call me Ishmael."}' Modified block data of 0 55 0 * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.author set value "Cthulhu the Sleeper"

History

Java Edition
1.20		Pre-release 2			Single quotation marks are now supported in NBT paths.