Add a note on what "deprecation" means in the spec

[sappelhoff]

For a separate PR: Might be good to have a note on deprecation in the spec itself. Something like:

DEPRECATED - A "deprecated" entity or metadata field SHOULD NOT be used in the generation of new datasets. It remains in the standard in order to preserve the interpretability of existing datasets. Validating software SHOULD warn when deprecated practices are detected and provide a suggestion for updating the dataset to preserve the curator's intent.

Originally posted by @effigies in #605 (comment)

[tsalo]

#508 and #424 use the term "legacy" for suffixes that fit this description. Should that be replaced with "deprecated"?

[effigies]

Well, I think "DEPRECATED" only appears once. I think we could just as easily go with "LEGACY".

[tsalo]

Deprecation has a more standardized meaning though, right? In BEP001 it looks like "legacy" is actually used as a precursor to "deprecation", which is a nuance I missed when I initially responded. That said, I don't think it's a distinction worth making since deprecation means that the element will be removed at a later date, not that it has been removed. As such, I'm not sure that have a pre-deprecation term (i.e., legacy) buys us anything. WDYT?

[sappelhoff]

As such, I'm not sure that have a pre-deprecation term (i.e., legacy) buys us anything. WDYT?

+1, no sense in a pre-deprecation term --> either we fully support something or we tell people to please not use it anymore (but keep it for backward compatibility)

regarding "legacy" vs. "deprecation", I like deprecation better, but I am not going to die on that hill :-) I think Chris' definition from the original post is nice and should be used.

[tsalo]

That works for me. I'm happy to update #424 and comment on #508 about switching to "deprecation" once there's a merged PR.

[sappelhoff]

That works for me. I'm happy to update #424 and comment on #508 about switching to "deprecation" once there's a merged PR.

thanks!

[effigies]

Sounds good to move forward with "deprecated". Looking at our current case, though, I'm unclear on what suggestion a validator should be making.

(Deprecated) Manufacturer’s designation of the software of the device that created this Hardcopy Image (the printer). Corresponds to DICOM Tag 0018, 101A Hardcopy Device Software Version

Neither "hardcopy" nor "printer" show up elsewhere. It may just be that it didn't seem meaningful. I think to be explicit, we should add "There is no recommended alternative for this DEPRECATED key." so validator writers don't waste their time.

[tsalo]

I think to be explicit, we should add "There is no recommended alternative for this DEPRECATED key." so validator writers don't waste their time.

I agree. I also think we should clarify at the initial definition that deprecated items will be removed at the next major release (i.e., BIDS 2.0), just so users know that it's not happening at the next patch or minor release.