Guidelines:Cargo

From Zelda Wiki, the Zelda encyclopedia
Jump to navigation Jump to search
If you have questions regarding Zelda Wiki's usage of Cargo, please bring them to the #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:

TFH Green Link ok.png
Do
TFH Red Link desperate.png
Don't

Place all Cargo parser functions behind templates.

===List of Armor===
{{Armor List|BotW}}

Do not use #cargo_query or any other Cargo parser function in articles directly.

===List of Armor===
{{#cargo_query:
tables= Armor
|fields= Armor, Level, Materials
|where= game = 'BotW'
}}

Every template using #cargo_query should:

Every template using #cargo_store should:

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

  1. Problem: A template needs to associate inputs to pre-defined configuration data in order to generate output.

    TemplateData

    Template:Color
    Input: Color name, text
    Output: Colored text

    Module:Color/Data maps color names to CSS colors

    Template:Flag
    Input: Region code
    Output: Region flag

    Module:Region/Data maps region codes to filenames of region flags

    Template:Scale
    Input: Controller inputs
    Output: Music notes positioned on a music scale

    Module:Scale/Data maps controller inputs to music note files and relative position data

Problems solved with Cargo data

  1. Problem: Template A receives input on page X and Template B needs to re-use that data on page Y.

  2. 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.

    TemplateData

    Template:On This Day
    Input: Date
    Output: Event that happened on that date

  3. 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.

    TemplateData

    Data:Translations[a]

    Template:Media
    Template:Media
    Template:Term
    Any other template with game parameters

    1. 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:

  1. Null-editing the page storing the data
  2. Purging the page querying the data

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.