Explanation
One of the things that feel very missing, is a proper system for versions. At the moment, we don't handle versions much, it just sets a version and that's it. Most of the heavy work is given to mod developers.
A lot of this should be enabled by using SemVer https://semver.org/
Let's say you have mod B and that depends on mod A which is version 2.3.4, you could write ^2.3.4 which would match any version from 2.3.4 up to, not including 3.0.0.
For explanation of how ranges works in SemVer go here - https://www.npmjs.com/package/semver#ranges
So in the case of MWS, you'd just use the API as such: https://api.modworkshop.net/mods/123/files?range=^2.0.0 and that would return any file of mod 123 that matches said range.
This should pave the way for a more powerful dependencies system with the upcoming ModWorkshop Manager.
What about the mod version?
The mod version should be kept, but possibly having it automated with the main download could work well. This can be equivalent to latest version.
What about different iterations of the mod?
This one is a bit more tricky. I think we could possibly have some kind of value like an identifier that would allow for you to have multiple iterations. Like let's say the game has 2 frameworks and you made 2 different iterations each supporting different frameworks, you'd want to update both, but now https://api.modworkshop.net/mods/123/files?range=^2.0.0 will return you versions of the framework you don't use too, so instead we'd do: https://api.modworkshop.net/mods/123/files?range=^2.0.0&key=FrameworkA
What about file IDs?
I generally want to move away from them. It's enough that you have to deal with mod IDs that are pretty much hardcoded and once lost (unless forced) are lost. I temporarily solved this by allowing you to change the file and adding a dialog before deletion, but I think having something like the above mentioned identification value, could be a better alternative to file IDs.
But that's what I have for now, I'd love to hear from modders about ideas on how this should be implemented. In the next version of the site (3.5) the limit on files(and links) is going to be removed, allowing you to potentially store many versions of the mod (as long as you are under the allowed storage). This is a thing I feel mws is very lacking on right now.
You link to semver, but your examples are wrong. 2.0 is not a semver, 2.0.0 is. ^2.0 means >=2.0.0 <3.0.0 i.e. versions 2.0.x, 2.1.x, 2.2.x, ..., not "only version 2.0". (There's a draft specification of ranges here: https://github.com/semver/semver/blob/efcff2c838c9945f79bfd21c1df0073271bcc29c/ranges.md and a slightly more accessible explanation here: https://www.npmjs.com/package/semver#ranges)
It makes little sense to depend on an unbounded number of major versions; by definition major version bumps make breaking API changes, so you must manually review dependents to ensure compatibility. If the 3.0.0 release is entirely compatible w/ things that use the 2.x.y API, it shouldn't have been a major version increment; if the dependent does happen to be compatible w/ both, it should probably ask for versions 2-3 aka >=2.0.0 <4.0.0. (Also, I suspect you meant >=2, not >2; an exclusive lower bound is a bit odd here since it would exclude 2.0.0 but allow 2.0.1.)
Thanks for the explanation. I'll update it.
That's the thing, many times people make major versions despite full compatibility just because it feels right. Many times libraries bump major versions and still have full backwards compatibility. Plus in the context of a modding site I feel like people won't fully adhere to this and just do whatever they want.
A great example is BeardLib in payday 2, despite major versions over the years, most old mods should still work.
There's also the thing that unlike NPM packages, you are likely going to have a single version of everything with mods (I think at least that's how it works, I might be wrong)