Guidelines:Cargo
#wiki-tech
channel on our Discord server.Cargo is the extension Zelda Wiki uses to manage structured data.
Why Use Cargo?
Cargo allows us to re-use the same data on multiple different articles without duplicating it. For example, we use the data from the Upgrading page as folows:
- On each Material article (e.g. Amber Relic), list all the item upgrades that require that Material.
- On each item page (e.g. Wooden Shield), list all the upgrades of that item along with the Materials required to make it.
Without Cargo, we could only achieve this sort of thing by manually copy-pasting data on dozens of pages—hundreds for games like Breath of the Wild. This would be very difficult to maintain as any change to the data would have to be made on all the pages that duplicate it. With Cargo, we make the change on one page and it propagates to the other pages automatically.
Cargo Alternatives
Zelda Wiki uses Cargo instead of Semantic MediaWiki or Wikibase simply because Cargo was the only option offered to us by Gamepedia at the time. We've since regained our independence, but we see no compelling reason to migrate to another structured data extension.
Cargo Usage on Zelda Wiki
You can browse Zelda Wiki's Cargo data at Special:CargoTables.
For lists of templates which use Cargo to store or query data, and articles which use such templates, see Category:Cargo extension.
Best Practices
All Zelda Wiki articles and templates should adhere to the following guidelines:
Every template using #cargo_query should:
- Categorize pages in Category:Pages querying Cargo data
- Be categorized in Category:Cargo query templates
Every template using #cargo_store should:
- Categorize pages in Category:Pages storing Cargo data
- Categorize mainspace pages in Category:Articles storing Cargo data
- Be categorized in Category:Cargo storage templates
Every Cargo template should also be documented in the data table at Category:Cargo storage templates.
Data Namespace
In most cases, Zelda Wiki stores Cargo data in the main namespace. Many list templates and table templates serve a dual purpose: they format lists or tables of data for one article, while also storing that data for use in other articles.
Zelda Wiki also has a dedicated Data namespace for storing certain data in a central location separate from any article. Only users in the curator group can edit pages in the Data namespace.
The Data namespace is used for datasets which:
- are too large for a single wiki page to hold and need to be partitioned into several pages
- need to be protected as they have a history of editors adding invalid input
Data:Translations meets both of these conditions and constitutes the vast majority of the data in the Data namespace. Most other data sets are small enough to be kept in mainspace articles and benefit from any editor being able to update them.
Module Data
Zelda Wiki also uses Extension:Scribunto to store some structured data in Lua files using a JSON-like format. Cargo storage and Lua storage solve different problems.
Problems solved with Lua data
-
Problem: A template needs to associate inputs to pre-defined configuration data in order to generate output.
Template Data Template:Color
Input: Color name, text
Output: Colored textModule:Color/Data maps color names to CSS colors
Template:Flag
Input: Region code
Output: Region flagModule:Region/Data maps region codes to filenames of region flags
Template:Scale
Input: Controller inputs
Output: Music notes positioned on a music scaleModule:Scale/Data maps controller inputs to music note files and relative position data
Problems solved with Cargo data
-
Problem: Template A receives input on page X and Template B needs to re-use that data on page Y.
Template Data Figurines Cargo table
LocationFeatures Cargo table
Transcripts Cargo table
-
Problem: A template needs to associate inputs to pre-defined outputs, where the outputs are large blocks of wikitext that are unwieldy when represented as Lua strings.
Template Data Template:On This Day
Input: Date
Output: Event that happened on that date -
Problem: Multiple templates need access to a data set that needs to be protected and/or is too large to store on a single wikipage.
Template Data Template:Media
Template:Media
Template:Term
Any other template with game parameters- ↑ We gatekeep translation data because in the past we had problems with editors adding unofficial translations.
Troubleshooting
If an article has missing or outdated data, the problem can usually be fixed by:
If these steps do not fix the issue, check to see if the storing page has validation errors. Storage templates may ignore data that fails certain validation checks.
If all else fails, the problem is likely with the storage template itself. It may be running into a script error or attempting to store data that doesn't match the declared table schema.
Exporting Data
You are welcome to export our Cargo data and use it however you see fit. However, if you redistribute our data, you must respect the terms of our GFDL License.
API
To app developers: we would be happy to have you use Zelda Wiki as a data source. Please join our Discord server and tell us about your project!
We strongly recommend that you do not use the cargoquery API directly in your critical path, as we cannot provide any guarantees on the availability or stability of our data. Instead, we recommend that you implement your own intermediate persistence layer that periodically grabs Zelda Wiki's data.