Stop using the abbreviation "RDF"

[FynnBe]

To abbreviate Resource Description File as RDF is confusing as RDF already commonly stands for Resource Description Framework, see e.g. https://de.wikipedia.org/wiki/Resource_Description_Framework

I propose to start refering to our yaml resource config files as Resource description YAML file (RDY) instead.

Suggestions for an alternative abbreviation are highly welcome @bioimage-io/spec-dev !

[jmetz]

How about something simple, like just resources.yaml?

Added:

Then the file can be referred to as the resources file?

Disclaimer: I've probably totally missed why it was called RDF file in the first place 😅

[oeway]

In principle, I wouldn't object renaming things, but for this one, I felt it's too late for this type of changes. It will be unnecessary stress more about our already tight schedule, for fixing the uploading, implementing s3, test run etc. And the change will need to also propagate to client software such as deepimagej. We have rdf.yaml hardcoded everywhere.

On the other hand, rdf is not a term we actually widely used, and it's well constrained under the bioimage.io domain. RDF should be the short form of bioimage.io rdf (or bioimage.io model rdf, bioimage.io collection rdf). Not sure what's the point of having a more unique name, it's also common to use just config.yaml or resources.yaml and there we never think about how it can be confused with the config used in other program.

The name rdf is only seen by a bunch of developers in bioimage analysis, it's not even for end users to see or edit. Correct if I am wrong, but I bet it will not be actually confusing for most of us in the bioimage community -- very few people will use RDF as the data structure standard in the field.

[FynnBe]

I think the abbreviation was too heavy in the first place. we often refer to the files in question as "the model yaml" etc. Hence, I like @jmetz suggestion. After some discussion with @k-dominik I'd like to propose a variant of it: a bioimageio.yaml. This is would nicely match the proposed .bioimageio.yaml suffix (see https://github.com/bioimage-io/spec-bioimage-io/issues/522). I checked, and we don't even need a leading dot to register the suffix in json schema store, see https://www.schemastore.org/json/ So we could match (using glob syntax) bioimageio.yaml and *.bioimageio.yaml. Then refering to the file as the bioimageio.yaml file makes a lot of sense.

Yes we do use rdf.yaml and we are even still using model.yaml in some places... This would simpy make rdf.yaml a legacy file name we can keep checking for.

Software switching to the new spec/core releases that are about to be released soon will need a manual update anyhow. I feel this would be a meaningful change making our code more accessible to new developers and more maintainable.

[oeway]

I would not under estimate the difficulty of introducing breaking changes, this is a rather big change should be carefully considered. We had too many distributed parts, many of them are out of our hands

Yes we do use rdf.yaml and we are even still using model.yaml in some places... This would simpy make rdf.yaml a legacy file name we can keep checking for.

This is exactly the reason why we should not add another one. To support all the legacy software, the downloader had to keep both rdf.yaml and model.yaml, now if we introduce another, we will need to do the same. The website and the downloaders need to be updated, there maybe some other places. This is a lot of extra price to pay for getting a more meaningful name.

Giving many other things on the our list, I really think this is not a good time to make such changes. We should prioritize to make the whole system work first, having an easy uploading, bring back the model validation and correctly display the software icons is way more important than change the RDF name. Holding the actual users from uploading or use the models create a lot of pressure.

If you guys want to change it, I'd suggest keep the discussion going and don't touch these until we have new upload, model test run and other important feature, and also resubmit the manuscript.

[FynnBe]

As this is part of our somewhat outward facing API, I'd argue that now --- before the "final/official" publication --- is precisely the time to clean up the naming convention.

The difficulty of dealing with such breaking change will only increase afterwards.

[oeway]

I feel like we need more time to think about this. Long time ago, We decided together to switch from model.yaml to rdf.yaml, and for a long time, no body complain about the name. I introduced the spec to many developers and no body ever tell me that the naming itself is confusing.

Plus, in this thread, only in a few hours, you guys came up with several ideas about the naming, I don't feel like they make a huge difference, it's more like personal taste.

The way forward is clear though, we discuss this tomorrow, and get opinion from other stakeholders. If I am the only one don't like the idea, then ignore me and we move on!

[FynnBe]

Yes, wise not to rush this! 👍 Let's bring it up tomorrow and see if the "larger we" likes it and is up for the change!

just for clarification of the time line, I proposed some name change (for the sake of the suffix on July 31: #522 )

[esgomezm]

Hi there, I agree with Wei that this is quite a critical change that should be carefully discussed in the bioimage model zoo meeting at least with representatives of the different software consuming the models that have the responsability of maintaining the compatibility with the zoo.

I can see the point made by Fynn on that issue from July and the motivation to have a general xxxxx.bioimageio.yaml specs that goes with the entire infrastructure. Also I have mixed feelings because the Java and Python libraries can provide good support for such a change. However, I fully agree with Wei on the many drawbacks that this cosmetic issue will bring + the fact that we already changed its name after a very long endless discussion and quite a mess from deepimagej's side back in the time (which change from config, to model to rdf...) Among many others, note thay it would imply asking external contributors who already did an effort on understanding our format, creating the models, and uploading them, going again through the process of updating the models (this also includes our selves). In some cases we need to ask them to please change their documentation as well. I think that changing this is okeish if its quite well justified. So for example, how staying as it is, causes long term maintenance issues?

[FynnBe]

So for example, how staying as it is, causes long term maintenance issues?

mostly through communication issues.

Among many others, note thay it would imply asking external contributors who already did an effort on understanding our format, creating the models, and uploading them, going again through the process of updating the models (this also includes our selves).

we are planning to switch how we store and serve the collection. It will be under our control, thus we can simply change the file name.

Maybe we can analyze in tomorrows meeting who directly uses the spec and thus would have to do anything due to such a change.

[FynnBe]

We concluded to slowly roll out the file name change while paying specific attention not to break existing tools.