Discussion: Refining Citation Field Requirements in Model Specs (cite)

[cfusterbarcelo]

Discussion: Refining Citation Field Requirements in Model Specs (cite)

Current Specification:

The cite field in the BioImage.IO model spec allows multiple citations with three components:

• Text (Required): Free-text description
• DOI (Optional, default: null): Digital Object Identifier (^10\.[0-9]{4}.+$)
• URL (Optional, default: null): Reference URL

Issues:

1. Missing Mandatory DOI or URL

   • Currently, only text is required, allowing citations without a DOI or URL.
   • Should we require at least one of doi or url to ensure proper referencing?

2. Ambiguity in text Field Usage

   • Some users treat text as a citation (APA, Chicago), while others use it for context (e.g., "This paper describes the model architecture.").
   • Should we rename text to description?
   • Should we add a formatted_citation field for structured citations?

Proposed Discussion Points:

• Require doi or url?
• Rename text to description?
• Introduce formatted_citation?
• Standardize citation formats?

Looking forward to hear your thoughts!

[FynnBe]

Thanks for the nice write-up!

One minor clarification:

Currently, only text is required, allowing citations without a DOI or URL.
Should we require at least one of doi or url to ensure proper referencing

Yes, but this is already the case. If neither is specified the error "Either 'doi' or 'url' is required" is returned.
I see how we should improve the documentation on this though: https://bioimage-io.github.io/spec-bioimage-io/bioimageio/spec/generic/v0_3.html#CiteEntry.url

And some thoughts:

Should we add a formatted_citation field for structured citations?

If we want to include actual metadata of the citation the BibTex format would probably be the most powerful choice and we could even make suggestions for provided DOIs via https://www.doi2bib.org/ (access is heavily rate-limited though).

Should we rename text to description?

maybe, but then we would need to manually review more... Now with text and us effectively having accepted content following either interpretation no one has to manually review that.

How about we just emphasize in the documentation that we intend it to be a description of why this citation is listed?
But if folks really want to provide an APA string or a bibtex string we could add those as optional fields, of course, their content probably wouldn't get reviewed though.

Curious to read more opinions on this!

[FynnBe]

quick follow-up: I improved the CiteEntry documentation in fd479c4