Basic Mod Metadata specifications.

[MrJeranimo]

Mod Managers and Indexers need to be able to store and use some metadata about mods. This post will talk about the bare minimum requirements for a mod's metadata to have a mod manager to function.

Properties

1. ModId: The unique constant Id of the mod. This should be the same name/id that is put in the manifest.toml, mod.toml, and the mod folder's name. This should not be separated from the name/id put in manifest.toml as that will cause abstraction issues and Mod Dependency issues. These need to be unique to allow for any mod to have the capability to be loaded at the same time in KSA as well as to let Mod Managers and Indexers tell them apart. This needs to be constant across all mod versions to allow Mod Managers and Indexers to properly store them and resolve dependency issues. The ModId must also be cross-compatible with Linux, Windows, and MacOS to prevent any issues now and in the future, thus they must follow a regex to determine cross-compatibility and must be less than 256 characters. Example regex I looked up, ^(?![\/:*?"<>|])[\w\s.-]+(?![\s.])$.

2. Display Name: The name displayed by Mod Managers which can be of indeterminate length and contain characters that ModId would not permit.

3. Authors: The authors of the mod.

4. Version: The version of the mod. My thought is to use a standard Major.Minor.Patch[-PreRelease] style for versioning as it is common and easy to understand if a version is newer or older. As for the PreRelease, it will use standard -alpha is older than -beta for matching versions, with -zeta being the newest before full release (Although I doubt a mod will use anything past -beta).

5. Description: The description of the mod.

6. Built For Game Version: Which KSA Version this mod was built for, can be multiple. Due to KSA's versioning system being quite unique and not fully reliable, my thought is to only have equality checks (does this version equal the other exactly) rather than a range. Hence why there can be multiple versions KSA is built for.

7. Mod Loader: If the mod is intended for use with a mod loader, which mod loaders, and if it can be used without one.

8. Mod Dependencies: A list of (ModId, Version) that this mod requires to be installed to work.

9. Source Code Link: A link to the source code of the mod.

10. Forums Post Link: A link to the KSA Forums about this mod release. This is to obey the KSA modding rules and to help with bot accounts as the mod poster will need an Ahwoo account.

11. License: The license of the mod. Can be either the name of a license (for popular ones) or a path to the license file.

12. Release Date: The release date (and time?) of this version of the mod.

13. Mod Size: The size in bytes of all the mod files, not including the metadata. This will be used to show the user how big the mod is.

14. Tags: A list of tags/categories the mod falls under (Parts, Code, Sounds, Tools, etc.).

15. Changelog: The changelog of this specific version. could be a string or maybe a link/path to view the changelog?

These are not all of the metadata properties for mods, they are just the most important ones I could think of off the top of my head. If you see any issues with any of them please comment.

[Maximilian-Nesslauer]

Thanks for getting this started.
Comments on the points where I would do something differently, plus two things I could not find in the list at all. Numbers refer to your list.

Before the individual points, I noticed one thing across the list:
about half of these are changed once or very rarely by the author (1, 2, 3, 7, 9, 10, 11, 14), and the other half change with every release (4, 12, 13, 15).

I think the format should make that split explicit: who writes a field decides whether it can be automated at all, and that part is expensive to change once files are published.

I want to make keeping the content manager up-to-date as easy as possible for both the content manager maintainers and also content creators.

A lot of (4, 12, 13, 15) changes like an author tagging a release on GitHub or uploading to SpaceDock and goes to bed could be automated.

At KSA's release pace, it could feel like a chore to update the content manager index each time a new release is pushed and/or easily be forgotten.

So my suggestion: the author writes the first half (1, 2, 3, 7, 9, 10, 11, 14) once, and everything in the second half (4, 12, 13, 15) can be derived per release by tooling.
We could create a watcher that picks up new releases from wherever they appear (GitHub / SpaceDock).
CKAN does it that way, one authored file plus one generated file per release (https://github.com/KSAModding/KSA-NetKAN and https://github.com/KSAModding/KSA-CKAN-meta) .

Whether the two halves also live in two separate repositories like that is a different question, and I would leave it open for now. It only starts to matter the day something automated actually commits: GitHub protection rules are per branch, not per folder, so "humans need reviews on the authored files" and "the bot pushes unattended" do not mix well inside one repo, and one generated commit per mod release buries the history of the authored half over time. None of that hurts before the watcher exists. The one thing I would pin down early is the URL clients fetch the index from: if that is a stable address instead of a direct repo path, the storage layout stays our internal business, and we can start with one repo and still reorganize later without breaking anyone's installed client.

It should IMO at least contain:

• a download location
• a checksum - verifying the download, and identifying it in a cache. Size (13) does neither
• the archive type
• install directives, i.e. which paths inside the archive go where. Without them we are assuming every archive has the same layout, and they do not
• a spec_version for the metadata format itself.
• release status (stable / testing / dev), so a nightly does not look like a release

On 1 (ModId): agreed on the principle, and it is worth saying that this is not something we get to choose: Mod.MakeUsing deserializes mod.toml and then overwrites the id with the folder name. The folder name is the identity (see research/ksa-mod-loading.md).

I ran your regex against a few edge cases though, and it does not hold up:

Input	Result
My Mod	matches	spaces allowed
MyMod (trailing space)	matches	the trailing (?![\s.]) sits at the end of the string, where the lookahead always succeeds
MyMod.	matches	same
.MyMod	matches	hidden file on Unix
My"Mod	rejected	but by the character class - the leading lookahead is redundant, none of `/:*?"<>

And one thing no regex fix covers: folder names are case-insensitive on Windows and case-sensitive on Linux, so MyMod and mymod are one mod on one platform and two mods on the other. The game will not pick a rule for us.

There is also a game-side landmine: ModManifest.Save regenerates manifest.toml from scratch and writes the id into a quoted TOML string without escaping. An id containing " corrupts the manifest. Windows forbids that character in folder names, Linux does not.

So rather than patching the regex, I think the ModId deserves a small spec of its own that is deliberately stricter than the KSA implementation and independent from any filesystem, and everything expressive pushed into the display name (your 2).
What it would need to pin down:

• first and last character rules (no leading dot, no trailing space or dot, e.g. the things the current regex is aiming at but does not enforce)
• a length cap, probably well below the 256 from your list, because the id ends up inside real paths that have limits of their own (I believe that Windows MAX_PATH is 260 unless long paths are enabled; We also have to take Linux and Mac into account.)
• a case policy: keep the author's casing on disk and in display, but make uniqueness in the index case-insensitive, so MyMod and mymod can never both be listed
• reserved names: Windows cannot create folders called CON, NUL, PRN, COM1..., and KSA itself effectively reserves Core (Content/Core, and its manifest entry is marked core and exempt from cleanup)

On 4 (Version):

My thought is to use a standard Major.Minor.Patch[-PreRelease] style

Agreed, and I would enforce it, not just recommend it.
Today nothing does:

• SpaceDock's friendly_version is free text
• a GitHub tag is whatever the author typed

I guess that is exactly why Borea has TryNormalizeModVersion guessing at other people's version strings (and silently truncating a four-part version to three).

I would directly enforece it in the index isntead: a release whose version does not parse gets rejected at publish time, with the error in front of the mod author, instead of surfacing later as a weirdly sorted list in front of users.

I would take SemVer 2.0.0 wholesale, including its pre-release ordering rules (they already give you the -alpha < -beta behavior you describe), rather than writing our own versioning scheme.

I would also build in a version_scheme field with semver as the only allowed value for now, so a later RFC can admit another scheme without a format break (with the caveat that ordering is only defined within one scheme - an author switching schemes mid-life breaks sorting, and Debian's epoch prefix is the classic escape hatch if that ever becomes real).

On 6 (Built For Game Version): this is the one where I disagree, and I opened #17 for exactly this question, so I will keep it short here and we can argue there.

The core of it: KSA shipped roughly thirteen releases a month so far. With equality checks, every mod in the index is marked broken within days of each game update. And the "can be multiple" list has to grow by hand thirteen times a month to keep up.
Thunderstore and Modrinth use per-release version lists just like you propose, and it works for them because their games release rarely. Ours does not.

Your underlying instinct is right though, and #17 agrees with it: the version string as a whole really is not comparable.
From implementing the Game version handling into CKAN however i know that the revision (the 4th component in the KSA versioneing scheme) is comparable and sortable, please see research/ksa-versioning.md. Please push back over on #17.

On 8 (Mod Dependencies):

A list of (ModId, Version) that this mod requires to be installed to work.

An exact pin has the same cadence problem as 6: every release of a dependency invalidates every dependent. You can watch this happening in the existing CKAN index already where StarMap is pinned three different ways across the mods listed there (KSA-NetKAN#6).

I would also allow at minimum min/max bounds instead of a single version.

I would also widen the relationship kinds to at least this:

• hard requirement
• soft requirement - StarMap's Optional = true in [[StarMap.ModDependencies]] already expresses this today
• conflict - nothing in the current list can express "these two cannot coexist" at all
• alternatives, declared by the depending mod - "needs one of A, B, C".
• succession - "this mod is dead, treat Y as its update". The reason is my point on 1: the ModId is the folder name, so a renamed mod is unavoidably a different mod. Without a succession pointer, every rename or continuation fork strands its users on a dead id with no update path.
• recommends
• suggests

On 10 (Forums Post Link): Sounds good :)

I would also have one optional set of more links (homepage, repo, forums, bugtracker, discord, ...).

On 13 (Mod Size): we should derive 2 numbers: download size and install size on disk, since they might be different after compaction etc.

[Maximilian-Nesslauer]

Instead of more prose, here is the current proposal state as concrete files, using my own AdvancedFlightComputer mod as example.

It combines the property list above, my earlier comment, RFC 0017 and RFC 0025, and the direction from #27

Please criticize fields, not abstractions: which field is wrong, missing, or should not exist.

The authored file. Written once by the mod author, changed rarely when the mod's facts change:

spec_version = 1
id = "AdvancedFlightComputer"
type = "mod"
name = "Advanced Flight Computer"
authors = ["Maxi"]
abstract = "Extra maneuver planning tools for Kitten Space Agency."
license = "MIT"
tags = ["control"]

# Where releases appear; the watcher picks new ones up from here.
[releases]
github = "Maximilian-Nesslauer/KSA-AdvancedFlightComputer"

[links]
forums = "https://forums.ahwoo.com/threads/advanced-flight-computer.783/"
repository = "https://github.com/Maximilian-Nesslauer/KSA-AdvancedFlightComputer"
spacedock = "https://spacedock.info/mod/4253/AdvancedFlightComputer"
bugtracker = "https://github.com/Maximilian-Nesslauer/KSA-AdvancedFlightComputer/issues"

# Oldest game version known to work, written the way the game displays it.
# Tooling resolves it to a revision when stamping a release (RFC 0017).
# A month is also accepted: game_min = "2026.7"
# game_max exists too and is optional; above it a client warns instead of blocking.
[compatibility]
game_min = "2026.8.3.5117"

# Only what a bot cannot derive: the loader needs authored version bounds,
# because the [StarMap] section of mod.toml deliberately carries none.
# min and max take SemVer values; max is optional, absent means open.
[[dependencies]]
id = "StarMap"
kind = "required"
min = "0.4.5"
max = "0.4.6"

The generated file. Stamped by the watcher for every release, no human involved:

{
  "spec_version": 1,
  "id": "AdvancedFlightComputer",
  "type": "mod",
  "version": "0.7.0",
  "version_scheme": "semver",
  "release_status": "stable",
  "release_date": "2026-08-02T13:18:41Z",
  "game_min": "2026.8.3.5117",
  "game_min_revision": 5117,
  "download": {
    "url": "https://github.com/Maximilian-Nesslauer/KSA-AdvancedFlightComputer/releases/download/v0.7.0/AdvancedFlightComputer.zip",
    "sha256": "ABC2A72E348AB26960FF59EDD019F160B12844099C30BF00F7D4E4D3D1ED5E74",
    "size": 131042,
    "content_type": "application/zip"
  },
  "install_size": 329449,
  "install": [
    { "from": "AdvancedFlightComputer", "to": "mods", "derived": true }
  ],
  "dependencies": [
    { "id": "StarMap", "kind": "required", "min": "0.4.5", "max": "0.4.6", "source": "authored" },
    { "id": "KittenExtensions", "kind": "optional", "source": "derived" }
  ],
  "changelog": "https://github.com/Maximilian-Nesslauer/KSA-AdvancedFlightComputer/releases/tag/v0.7.0"
}

Things worth noticing, because they answer questions from this thread:

• The KittenExtensions dependency was never authored using additional manual work. The watcher read it out of the archive's mod.toml ([[StarMap.ModDependencies]] with Optional = true). That is the bot-derived baseline from The index: how the catalogue is stored, updated, and fetched #27 working on a real mod: code dependencies come for free per release, and the authored file only carries what a bot cannot know.
• The version is 0.7.0, not v0.7.0. The tag is normalized at stamp time, and a release whose version does not parse as SemVer is rejected in front of the author, not guessed at by clients later.
• game_min_revision makes compatibility evaluable offline with no index lookup, and game_min next to it is what a UI displays (RFC 0017).
• The install directive is derived too, because the archive has the standard layout, a top-level folder containing mod.toml. Only unusual layouts need authoring. That addresses the CKAN pain point that somebody has to hand-write install_to.

And the decisions this example deliberately surfaces instead of hiding:

1. Authored is TOML, generated is JSON. Humans write TOML in this ecosystem already (mod.toml, manifest.toml); machines write and consume JSON, and every generated file is diff-noise anyway. Push back if you would rather have one format for both.
2. Is the loader a plain dependency or its own field? Here it is a dependency like any other. MrJeranimo's property 7 ("which loader, and does it run without one") might justify a dedicated field instead.
3. Should the generated file be fully self-contained like CKAN's (repeats name, license, links, so a client needs exactly one file per release) or minimal like here (per-release data only, client merges it with the authored file)? This decides the fetch contract in The index: how the catalogue is stored, updated, and fetched #27 point 3.
4. Which links are required? The forums link is required in the current list (and The index: how the catalogue is stored, updated, and fetched #27 wants it as an id-dispute tiebreaker); everything else here is optional.

[MrJeranimo]

For both files. is spec_version which version of the metadata specifications the file is using?

For the Authored File, Is the abstract also the description or does the flow go, Display Name, Abstract, Description in terms of level of detail.

Also, for the Dependencies, in the authored file, where you declared specific versions of StarMap, would that not cause issues if StarMap updates, because then the creator would have to re author the file. Furthermore, it is not guaranteed that all versions of the Mod use the same StarMap Versions.

Would it not be better to keep the Loader as a specific field like you mentioned in 2.. This way you can say this mod uses this mod loader, or none at all. As for what version of the mod loader, that can be put inside the specific version as different versions of the Mod may use different versions of the mod loader. For a further use case for a specific mod loader field rather than bunching it in with dependencies is that the indexer will still need to watch what versions of a mod loader there are to make sure the metadata is valid. There is also the case of resolution where if the mod loader is in its own specific field, any dependency resolvers don't have to check each dependency and be like "Is this a mod loader or a mod?". As for how to make sure only mod loaders go in the mod loader field, we just add a metadata type `"mod-loader".

This is more a general topic, for version ranges, instead of min_version and max_version, should we use a version range expression such as >=0.1.0 <0.2.0 or something similar to allow the creator better control over which dependency versions the mod can use?

For the version file in the install field, are the from and to which folder to move from and to. In other words the "from": "AdvancedFlightComputer", "to": "mods" means to take the folder AdvancedFlightComputer in the mods files and move them to the mods folder. My only thought is that this might be a little redundant as the type mod already tells and manager/downloader that it is a mod and following KSA rules, should go into the \mods folder. I think just a standard rootDirectory field which tells which folder is the root for the mod, in case there are multiple folders for whatever reason, should be enough and the manager handles the rest.

1. I originally had intended for all metadata Borea uses to be TOML to reduce the number of packages also since the files size is lower, however since JSON is mor optimized for automation, I think both can be used.
2. Same as what I said in the second paragraph.
3. I think minimal because when you are searching for mods to download you don't need more than the authored info and which versions are available. As for when you download a version, the mod manager can just combine the two files info.
4. For the Forum post, I also think it can be used a psuedo-moderation, such that if the post gets taken down or the creator gets banned/removed, it can make it noticable so that content can be watched if the takedown was not related to the mod/content, and if it was, we can more easily figure out why and take down the mod/content if needed.

[Maximilian-Nesslauer]

For both files. is spec_version which version of the metadata specifications the file is using?

Yes, the version of the metadata format itself.

For the Authored File, Is the abstract also the description or does the flow go, Display Name, Abstract, Description in terms of level of detail.

name is the display name, abstract is the one-or-two-sentence list and search text, and a longer optional description exists on top

Also, for the Dependencies, in the authored file, where you declared specific versions of StarMap, would that not cause issues if StarMap updates, because then the creator would have to re author the file. Furthermore, it is not guaranteed that all versions of the Mod use the same StarMap Versions.

You have a good point and i think it was an bad example on my end.
The recommended default should be a min only with an open upper end, the same philosophy RFC 0017 uses for the game version: an open bound stays valid as the loader moves, and the author tightens it only when a real break is known.
Different mod versions stay correct without re-authoring old releases, because the watcher stamps the bounds that were current at release time into each release's generated file.

Would it not be better to keep the Loader as a specific field like you mentioned in 2. [...] any dependency resolvers don't have to check each dependency and be like "Is this a mod loader or a mod?". As for how to make sure only mod loaders go in the mod loader field, we just add a metadata type "mod-loader".

That makes sense. I agree.

This is more a general topic, for version ranges, instead of min_version and max_version, should we use a version range expression such as >=0.1.0 <0.2.0 or something similar to allow the creator better control over which dependency versions the mod can use?

Here I would stay with structured min/max, both inclusive.

An expression like >=0.1.0 <0.2.0 needs a parser whose edge cases we would have to specify ourselves (npm, cargo, and NuGet ranges all differ subtly), while two typed fields are schema-validatable and map one to one onto what a resolver evaluates.
If disjoint ranges ever become a real need, an expression field can be added later as a format extension without breaking anything.

My only thought is that this might be a little redundant as the type mod already tells and manager/downloader that it is a mod and following KSA rules, should go into the \mods folder. I think just a standard rootDirectory field which tells which folder is the root for the mod, in case there are multiple folders for whatever reason, should be enough and the manager handles the rest.

type already decides the target folder, so the only thing that varies per archive is where the content root sits inside it.

Updated shape: an install object with a single root, derived by the watcher for the standard layout and authored only for unusual archives.

If a real mod ever needs a multi-target install, the object can grow and I would not build that speculatively.

1. I originally had intended for all metadata Borea uses to be TOML [...] however since JSON is mor optimized for automation, I think both can be used.

3. I think minimal because when you are searching for mods to download you don't need more than the authored info and which versions are available. As for when you download a version, the mod manager can just combine the two files info.

Agreed on both, so authored TOML plus generated JSON stands.

4. For the Forum post, I also think it can be used a psuedo-moderation, such that if the post gets taken down or the creator gets banned/removed, it can make it noticable so that content can be watched [...]

Good point, that belongs in #27 point 7 as part of the moderation model, I will carry it over there.

The example deltas. Authored file: the StarMap entry leaves [[dependencies]] and becomes

description = "Optional, longer than the abstract."

[loader]
id = "StarMap"
min = "0.4.5"
# max exists and is optional; the recommended default is leaving it open.

Generated file:

"loader": { "id": "StarMap", "min": "0.4.5", "source": "authored" },
"install": { "root": "AdvancedFlightComputer", "derived": true }

[MrJeranimo]

I just thought of something. Should we add a status field to the authored document that can track if the mod is active (still receiving support) or deprecated (no longer receiving support), so that other content creators and people trying to manually install mods know that the mod won't be worked on in the future. There could be more statuses too.

This is just the last idea I had, because otherwise I think this is looking pretty good for all the fields we may want for now.

[Maximilian-Nesslauer]

I just thought of something. Should we add a status field to the authored document that can track if the mod is active (still receiving support) or deprecated (no longer receiving support), so that other content creators and people trying to manually install mods know that the mod won't be worked on in the future. There could be more statuses too.

This is just the last idea I had, because otherwise I think this is looking pretty good for all the fields we may want for now.

Yes to a status field, i think that is a good idea in the authored file, with boundaries around it:

It should absorb succession instead of sitting next to it.
In my first comment I listed succession as a relationship kind under [[dependencies]] but your proposal might make the following changes make sense:
I would change it: succession does not say "I need X", it says "I am replaced by X", so every resolver would have to filter it back out of the dependency list.

status = "active"

status = "deprecated"
superseded_by = "AdvancedFlightComputerNG"

superseded_by is optional and only meaningful when the status is deprecated, because a mod can be abandoned without a successor.

The id is the folder name (Mod.MakeUsing overwrites whatever the file declares), so a renamed mod is unavoidably a different mod, and without this pointer every rename strands its users on a dead id.

Author status and index status must not be the same field.

status is the author's declaration about their own mod.
Delisted, taken down, or disputed is the index's declaration about a listing.

On more statuses: I would keep the set closed at active and deprecated for spec_version = 1.

Client behaviour: deprecated warns, it does not block, and it surfaces superseded_by when present.
Consistent with the line we have taken everywhere else, an unlisted dependency (#27 point 6) and an untested game version (RFC 0017) also warn rather than block.

---

On the thread as a whole: I think this is converged.

The open items from my last comment all have answers now (loader as its own field with a mod-loader type, structured min/max, install.root, authored TOML plus generated JSON, minimal generated file), so unless someone has a field that is still wrong or missing, I would write this up as the metadata format RFC next, with the pack extension from #16 folded in.