Resource location

Namespaced identifiers are a way to declare and identify built-in and user-defined game objects in Minecraft without potential ambiguity or conflicts.

Usage
Namespaced identifiers are used as plain string to reference blocks, items, entity types, recipes, functions, advancements, tags, and various other objects in vanilla Minecraft.

A few examples (including, but not limited to):
 * argument in command target selectors.
 * : the parameter for the function variable.
 * The in entity NBT data root tag.
 * used for identifying an advancement.
 * The in item NBT format.

A valid namespaced identifier has a format of, where only certain characters can be used.

Legal characters
The namespace and the name of an ID should only contain the following symbols:


 * Numbers
 * Lowercase letters
 * Underscore
 * Hyphen/minus
 * Forward slash
 * Directory separator; cannot be used in namespace.
 * Dot
 * File suffix separator; cannot be used in namespace.

The preferred naming convention for either namespace or name is.

Conversion to string
A namespaced ID would be converted to a string by appending its namespace with a  (colon) and its name.

Examples: For tags, in addition, an extra  would be prepended before the namespace.

Examples:

Conversion from string
Unlike that namespaced IDs can always be converted to strings, some strings cannot convert to namespaced IDs.

A few restrictions:
 * The string can have at most one  (colon) character
 * When a tag is accepted, the string can optionally have a  in front
 * The rest of the string must fulfill the requirement of legal characters
 * If the  is present, the part of string before the   must not contain   or

When the  is present, the part of string before the   (excluding the   in front for tags) becomes the namespace and that after the   becomes the name.

When the  is absent,   becomes the namespace and the whole string (excluding the   in front for tags) becomes the name.

It is recommended to always include a  in the string format of namespaced IDs.

Reasons include:

A few of the examples below demonstrate the advantage of always including a.
 * This is the only way to specify a namespace other than
 * It is less confusing: it would be identical when the game converts the ID to a string again, compared ones without a specific namespace having a  namespace added
 * It could help debugging when a wrong format is accidentally used, such as  (resolves to  ) versus


 * Examples

Locating contents in packs
Given objects from resource packs and data packs are files, the namespaced ID can also be used to find corresponding files that declared objects of the ID.

Though the locations varies by object and pack type, there is a pattern to follow. In general, The location is in a fashion of, where all the   (forward slash) symbol (may be part of  or ) is replaced by operating system-dependent directory separator.

Possible values of

Possible values of  and

Note: Certain elements in the resource pack is not necessarily backed by an object with namespace ID, such as GUI textures.

Given the type of content we want to locate, we can find out the corresponding, , and. Then, we can substitute in and find out the final file location of the content.

Examples

Namespace
A namespace is a domain for contents. It is to prevent potential content conflicts or unintentional overrides of object of a same name.

For example, if two data packs add two new minigame mechanisms to Minecraft and both have a function named. Without namespaces, these two functions would clash and the minigames would be broken. But if they have different namespaces of  and , the functions would become   and  , which no longer conflict.

Custom namespace
The namespace should be distinct for different projects or content creations (e.g. a data pack, a resource pack, a mod, backing data/resource packs for a custom map, etc.)

To prevent potential clashes, the namespace should be as particular as possible.: In either case, these poorly chosen namespaces reduces the exposure of a project and brings difficulties for debugging when there is multiple content creations applied to the game.
 * Avoid alphabet soups. For example, a project named "nuclear craft" should not use the namespace, as this is too ambigous.
 * Avoid words that are too vague.  would not be informative to look up as well, but   would be much better.

namespace
Minecraft reserves the  namespace; when a namespace is not specified, a namespaced ID will fall-back to. As a result, the  namespace should only be used by content creators when the content needs to overwrite or modify existing Minecraft data, such as adding a function to the   function tag.