Skip to content
This repository has been archived by the owner on Jan 21, 2020. It is now read-only.

Metadata Format

Jump to bottom
Andrew Okin edited this page Aug 28, 2017 · 2 revisions

This article describes the format used to store metadata about the mods in the archive. Metadata is stored as a set of YAML files in this Git repository. The website reads these files and uses them to determine what mods to list and information about those mods.

Mod Metadata

Every mod in the archive has a YAML metadata file describing it. Each file's name determines the mod ID and therefore its URL on the website. It should be all lowercase, with only letters, numbers, and symbols like - and _. No spaces.

Let's break down a sample mod file.

format: 1
name: Sample Mod
desc: |
  This mod does nothing. It is just a sample.
authors: [Nobody]
  • format must always be 1.
  • name specifies the mod's human-readable name.
  • desc is optional, but may be a long (potentially multiple paragraph) description of the mod. Markdown is supported in the description field.
  • authors should be a list of author names.

Mod Versions

Next is a list of versions. This starts with a versions: field, followed by an indented list of versions available for this mod. Every new version starts with a - character on the left. Mod versions should always be listed in sorted order from newest to oldest.

versions:
- name: 1.0.0
  mcvsn: [b1.6.4]
  files:
  - filename: SampleMod.zip
    desc: |
      This description is optional.
    ipfs: QmSWAMZZDR6NrFUR7B26yDaoVYp6VBigfSc3nsCaQ8S65Q
    hash:
      type: sha256
      digest: 92638a55df978caf89cf824e1196d12ef2eb5c9c187954257d0030a122efa05a
    urls:
    - type: page
      url: http://www.samplemod.com/download/1.0.0
    - type: original
      url: http://www.samplemod.com/download/1.0.0/direct-download
  • name should be the version number, such as 1.0.0 or pr6. Some mods use a Minecraft version number as their version number. Those mods should have that version number in their name field anyway. For mods without any discernable version numbering, the name field should be some sort of unique identifier like a release date or whatever. It is acceptable to have multiple versions with the same name, although it should be avoided if possible.
  • mcvsn is a list of Minecraft versions supported by this version of the mod. It is usually written on a single line, like this: [1.2.5, 1.2.4, 1.2.3]. The brackets must be included even if there is only a single version.

Files

Next is the files field, which contains a list of files released with this version of the mod. Most mods will only have a single file per version, but some mods were distributed either in multiple separate modules, or with separate files for the client and server. These mods should have all of the files associated with a single version grouped together in the files list for that version.

  - filename: SampleMod.zip
    desc: |
      This description is optional.
    hash:
      type: sha256
      digest: 92638a55df978caf89cf824e1196d12ef2eb5c9c187954257d0030a122efa05a
    ipfs: QmSWAMZZDR6NrFUR7B26yDaoVYp6VBigfSc3nsCaQ8S65Q
    urls:
    - type: page
      url: http://www.samplemod.com/download/1.0.0
    - type: original
      url: http://www.samplemod.com/download/1.0.0/direct-download
  • filename determines what the file should be called when it is downloaded. When possible, please use the original filename.
  • desc can contain an optional description of this file. It can be used to explain what the file is for if it isn't obvious.
  • hash field contains two sub-fields: type, which, for now, must always be sha256, and digest, which should be a sha256 hash of the archived file.
  • ipfs field should contain the file's IPFS hash. This allows the site to store the file and generate a download link for it. See for more information on adding files to IPFS.

URLs

Lastly, the urls list should list offical download links for the mod if they are available. There are two types of URL entry, page and original. The page URL should be a link to the mod's official download page, not a direct download link. The original URL should be a direct download link (if one is available), or possibly an adfly link. If either of these are not available (because the mod's website has been taken down, or for some other reason), then their entries can be omitted. If no URLs are listed, leave the field blank like this: urls: [].

When no URLs are available for a file, the archive will re-host it from IPFS.

Here is the complete sample metadata file:

format: 1
name: Sample Mod
desc: |
  This mod does nothing. It is just a sample.
authors: [Nobody]
versions:
- name: 1.0.0
  mcvsn: [b1.6.4]
  files:
  - filename: SampleMod.zip
    desc: |
      This description is optional.
    ipfs: QmSWAMZZDR6NrFUR7B26yDaoVYp6VBigfSc3nsCaQ8S65Q
    hash:
      type: sha256
      digest: 92638a55df978caf89cf824e1196d12ef2eb5c9c187954257d0030a122efa05a
    urls:
    - type: page
      url: http://www.samplemod.com/download/1.0.0
    - type: original
      url: http://www.samplemod.com/download/1.0.0/direct-download
Clone this wiki locally