Forum:Article names for data pack contents

The current article names for data pack contents generally reuse the names used by the game itself or in snapshot news articles (e.g. loot table, structure set, configured feature). However, some of these conflict with the main articles, for example there is data for dimensions, advancements, and now enchantments. These articles are currently prefixed with "Custom" to distinguish them from the main articles, for example Custom dimension, Custom advancement, Custom enchantment, Custom biome. There's also some cases where there isn't a conflict with the article name without "custom", in particular Custom noise settings.

In my opinion, using "custom" is misleading; confusing at best; and completely incorrect at worst. When I see an article name like "Custom Dimension" I'd expect a tutorial on how to create a custom dimension, not a description of the data format used to describe all dimensions in the game, including vanilla and modded ones. At the same time, there are some articles like loot table that could use a separate article with a higher-level overview of the concept of what a loot table is without going into the technical details.

The reason for why "Custom" was used to distinguish is likely that custom dimensions and custom worlds used to not be included in the game files themselves and would only be relevant for actual custom data packs, not the vanilla worldgen for a good while. This however has changed some time ago; now the game includes all files for vanilla worldgen in its .jar file exactly as described on custom biome for example.

Another thing to note is that custom advancement was recently moved from "Advancement/JSON format" to be consistent with the other data pack articles using "custom". I agree that we should probably avoid using "sub-articles" as much as we can because these articles typically can't be found very easily.

I therefore want to propose to rename data pack articles where there is a conflict between the main name and the data article to remove the word "custom". With the new data-driven enchantment system, I have moved custom enchantment to "Enchantment data", which was reverted and a discussion was started on Talk:Custom enchantment where I was asked to create a forum topic.

Besides "Enchantment data", another possibility for naming would be "Enchantment format" like we currently use for things like item format or entity format; or even a combination like "Enchantment data format". | violine1101 ^(talk) 12:03, 8 May 2024 (UTC)

👁 Image
 Strong support for updating the names. I personally prefer "Enchantment format" to match existing articles. -- 👁 Image
MarkusRost (talk) 12:18, 8 May 2024 (UTC)

👁 Image
 Support - I support the name change, it's becomes just to obvious to change these names after your explanation, would prefer 'Enchantment format' as with the other articles because of consistency. - 👁 Image
StizzurpXDD^(talk) 12:30, 8 May 2024 (UTC)

👁 Image
 Support renaming, but 👁 Image
 Oppose both the "data" and "format" suffixes, Both "Enchantment data" and "Enchantment format" can too easily be confused with the Data component format#enchantments used to store enchantments on an item stack. "Biome data" and "Biome format" could be too easily confused with biome storage in Chunk format. Also, item format and entity format describe something different: The nbt format for individual item stacks and entities. Should we (which appears likely) get data pack defined items, we'd run into naming issues again if we used the "data" or "format" suffixes. I don't really have a better suggestion though, except maybe making them all sub-pages of data pack, but I'm 👁 Image
 Unsure about that myself. | jacobsjo (talk) 13:11, 8 May 2024 (UTC)

All of these articles have one thing in common, they are about a specific format for defining some data. Whether that data is defined as NBT or JSON depends on the use case, but all of them are data formats. I'm not sure if it's necessary to enforce a distinction in the article name, and if so, using "format" to mark that distinction seems confusing as well. If we want to be super duper consistent about this, we could have NBT things that are in world saves named "save format" and JSON things in data packs "data format". I.e.: "chunk format" → "chunk save format", "entity format" → "entity save format", "item format" → "item save format", "custom dimension" → "dimension data format", "custom biome" → "biome data format", etc.

This would also already prepare the wiki in case Mojang also adds data-driven items, where we would then have both "item save format" and "item data format". For blockstates, there could also be "blockstate data format" and "blockstate resource format" (currently hidden in a tutorial page) in case they also end up being customizable via data packs.

Actual names are obviously open for discussion (and I'm not convinced these are the best ones) but if we want to be consistent here we should also be clear.

Besides, I just noticed – is there a particular reason for why "data component format" is not just called "component format"? Where's that "data" coming from? In the snapshot changelog where components were introduced they were just called "component". | violine1101 ^(talk) 13:45, 8 May 2024 (UTC)

To answer your final point, the game code uses the term DataComponents for this, and now in 24w18a they added EnchantmentEffectComponents. I think it's good here to be specific, to a avoid a future "Tag" overloading. — Misode (talk) 15:15, 8 May 2024 (UTC)

Ah thanks, that makes sense. I agree that it's best to avoid overloading from the start. Though "data" seems a bit generic – but that's on Mojang. | violine1101 ^(talk) 15:28, 8 May 2024 (UTC)

So maybe "Enchantment Effect Format" would be a good name for the article. --Simanelix ^(T|C) 15:32, 8 May 2024 (UTC)

The article is about the entire definition of enchantments, including their name, the required levels, and supported items. "Enchantment Effect Format" would only describes the entries of the [NBT Compound / JSON Object] effect field. -- jacobsjo (talk) 15:42, 8 May 2024 (UTC)

👁 Image
 I love this idea --Simanelix ^(T|C) 15:31, 8 May 2024 (UTC)

👁 Image
 Support standardizing a new naming convention. I think another example would be "enchantment definition" versus the existing "enchantment format". The definition being the description of what is an enchantment, and format being the syntax for how to use it. But I realize this may not be intuitive enough. I agree that using "custom" is not appropriate anymore, now that it also defines the non-custom aspects. I really think "definition" is a good word for this, but I'm not convinced it is the best. - Jack McKalling (talk) 13:43, 8 May 2024 (UTC)

👁 Image
 Support I agree that "definition" is a good term for this. Its also already in use in a few places such as Item modifier#Definition and in official change-logs such as 24w18a: "Path to painting definition is data/<namespace>/painting_variant/<id>.json" | jacobsjo (talk) 14:58, 8 May 2024 (UTC)

👁 Image
 Support - As per MarkusRost's comment. - 👁 Image
StizzurpXDD^(talk) 08:14, 9 May 2024 (UTC)

👁 Image
 Support "definition" -- 👁 Image
MarkusRost (talk) 15:45, 8 May 2024 (UTC)

👁 Image
 Support After thinking about it for a bit, I feel like "definition" does indeed seem to fit the best. Using the JSON files you're defining something new, so that makes semantic sense and is clearer than calling it just "format". | violine1101 ^(talk) 19:45, 9 May 2024 (UTC)

👁 Image
 Soft support. "Definition" is currently the best suggestion, though I'm also not entirely convinced it's the best possible word. I can't think of anything better though. – ZacNVR (talk) 01:05, 10 May 2024 (UTC)

👁 Image
 Support "definition" Chixvv (talk) 02:17, 14 May 2024 (UTC)

What about including the specific file format in the title; i.e. "Enchantment JSON definition" or "Entity NBT format"? The current proposal of "Enchantment definition" still seems confusing for someone who's not technically oriented or familiar with the naming scheme, whereas having JSON or NBT in the name more clearly indicates to me what it's about. I'm not familiar enough with the pages to know whether these names would accurately describe them though. –⁠Sonicwave ^talk 05:10, 17 May 2024 (UTC)

I don't think that's necessary. The first sentence of these pages is already some form of "<thing>s are defined using JSON files within a data pack in the path [...]". Generally, I'd prefer the scope of the articles to be "How are <thing>s defined (in data packs)?", and not "What is the format of the files defining <thing>s in data packs?".

Also, internally the encoding and decoding system supports both formats. Recently this resulted in cases where the same data can be specified in JSON or NBT depending on the use-case: Since 24w20a a Painting variant (-> Painting variant definition) can be defined in a data pack using a JSON file or inlined in the Painting#Entity_data. So "Painting variant JSON definition" would be wrong. I'd prefer these pages have a consistent naming scheme that doesn't depend on the format of the files. -- jacobsjo (talk) 11:09, 17 May 2024 (UTC)

Since the "definition" suffix seems like the currently preferred option, I propose the following specific page moves:

-- jacobsjo (talk) 14:24, 13 May 2024 (UTC)

We could also make World generation definition map redirect to Custom world generation and Noise settings definition map redirect to Noise settings, just for consistency. --Simanelix ^(T|C) 18:19, 13 May 2024 (UTC)

What do you mean by "map"? We can certainly make redirects, if you mean that. But I'd oppose having the "definition" suffix on all data pack pages (there are a lot more not listed here, see Template:Data packs). [Noise settings] needs to also explain the concept of noise settings, not just detail how to define them. -- jacobsjo (talk) 18:39, 13 May 2024 (UTC)

👁 Image
 ClarificationWhen I use "map" I mean "redirect". I do a lot of programming, and mapping is just how I interpret redirects. --Simanelix ^(T|C) 01:52, 14 May 2024 (UTC)

I don't think we need to do that. We're also not redirecting Loot table definition to Loot table. — Misode (talk) 19:51, 13 May 2024 (UTC)

By the way, we need to have a non-technical version of the Loot table page, because loot tables are used to describe the drops on a lot of pages. --Simanelix ^(T|C) 01:50, 14 May 2024 (UTC)

Loot table is the technical implementation of various sources of loot in the game. We already have Drops for the gameplay explanation. Loot table should stay technical, although I don't see a reason to split the usage and other info from the definition of loot tables. — Misode (talk) 02:02, 14 May 2024 (UTC)

👁 Image
 Support — Misode (talk) 19:13, 15 May 2024 (UTC)