Hey, designing a file format or network protocol? Let me give you one tip that I keep hearing people call unnecessary, and I keep coming to projects and having to work around it:
Add a simple SemVer version number.
Somewhere right at the start of the file, in the first message, or included in every JSON endpoint's response.
Nothing fancy, just a major and minor number. If the major is bigger than your client's, tell the user to update. Remember to increment the minor with each change.
@justkwin I've found it easier to get the build system to bump the minor version, but agreed, if people change the schema and your version number doesn't get bumped (or worse, make an incompatible change without that), then this of course doesn't fix things either.
But IMO, just having a version number that gets bumped most of the time helps a lot. Not having it doesn't help at all.
@uliwitness @justkwin To us, I have found the best way is to have the app platform and build number in the user-agent.
The build number will always be updated with a new version. It is really rare that we have to use it but when we do it is a solid way to distinguish.
It is not pretty. A “protocol version” seems better, more clean, “correct”, but the build number more fool-proof in the rare case it is necessary.
Uli Kusterer (Not a kitteh)
Quinn “The Eskimo!”
Nicolai Henriksen