Version Tag
tathey1 opened this issue · comments
@fcollman 's idea - add a version tag so the standard can be easily referenced.
Good idea, the current version is now tagged as https://swc-specification.readthedocs.io/en/v1.0.0/
We will continue to tag versions as we do changes.
I think this is good... but what i was suggesting though in the call was that there is a standard place, probably in the header where this version is written. The reason for this is that then readers can be sure that the file that follows uses that standard, and if the standard moves, then the reader can dynamically change it's code appropriately to follow the new standard. Let's say this version is 1.0. During the call, people were expressing opinions for example that the sequential constraints should be dropped. Let's say for argument that's adopted, and 2.0 does not have this constraint. Then 1.0 readers can raise warnings that they don't yet support reading 2.0 files. If readers want to write a fresh implementation for the 2.0 reading without erasing the known good functional 1.0 reader, they can direct the parsing of 1.0 files to the old implementation and only push the 2.0 files through the new one.
I think part of the difficulty the community faces when dealing with SWCs is just that there is not sufficient information advertised within the file itself about what the file contains. This specification addresses that, but if that information isn't actually encoded in some way, then consumers can't make use of it. As you heard on the call getting adoption is not going to be instant or universal, so one needs a way to telegraph conformity to the interface.
Thank you for your input, Forrest. Giorgio and I have discussed it and we think this is a good idea, and we agree that this should be part of the standard. We have had some thoughts on how to express metadata, and we suggest doing it in JSON format at the very start of the file. We would like to keep the first version of the standard minimalistic to make it as broadly adopted as possible and at this point will not like to add any further format requirements or guidelines for metadata. However, we would suggest including a keyword tag for the version to be "swc-version". The very first row of a file would thus look like:
# "swc-version": "1.0.0"
This would be optional, in the same way as, for example, an XML file can be wellformed without including the XML declaration. Before adding this to the standard, we would however welcome feedback from the community, including of course yours.
Please let us know what you think, and anyone else, please feel free to join the discussion.