CFF files generated for articles causes GitHub server to crash

[jeyabbalas]

Hello,

I am not sure if this is a GitHub issue or a cffr issue.

I tried to generate a CFF file using the cff_from_bibtex() method in cffr. I follow the example in the manual as below:

if (requireNamespace("bibtex", quietly = TRUE)) {
  x <- c(
    "@article{vaswani2017attention,
  title={Attention is all you need},
  author={Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N and Kaiser, Lukasz and Polosukhin, Illia},
  journal={Advances in neural information processing systems},
  volume={30},
  year={2017}
}"
  )
}

cff_from_bibtex(x)

This generated the following text:

type: article
title: Attention is all you need
authors:
- family-names: Vaswani
  given-names: Ashish
- family-names: Shazeer
  given-names: Noam
- family-names: Parmar
  given-names: Niki
- family-names: Uszkoreit
  given-names: Jakob
- family-names: Jones
  given-names: Llion
- family-names: Gomez
  given-names: Aidan N
- family-names: Kaiser
  given-names: Lukasz
- family-names: Polosukhin
  given-names: Illia
journal: Advances in neural information processing systems
volume: '30'
year: '2017'

I saved it in a CITATION.cff file and pushed it to my GitHub repository. After that, I went to my GitHub repository to view the file and it leads to a server error (status: 500). GitHub is unable to parse this file. When I remove the line type: article from the file, this error goes away. However, now, instead of citing an article, GitHub assumes that this citation is of type software. Could this be a conflict with CFF specification for articles? GitHub's CFF specification wasn't helpful. So, I was hoping this community was familiar with this issue.

Thank you for all your work!

[dieghernan]

Hi,

A CITATION.cff file must follow a minimal structure. Minimum keys are:

• authors
• cff-version
• message
• title

Also, it is most intended for software and datasets. However you can tweak how the citation is displayed on GitHub with the preferred-citation key. So your CITATION.cff file is not valid, see:

library(cffr)

if (requireNamespace("bibtex", quietly = TRUE)) {
  x <- c(
    "@article{vaswani2017attention,
  title={Attention is all you need},
  author={Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N and Kaiser, Lukasz and Polosukhin, Illia},
  journal={Advances in neural information processing systems},
  volume={30},
  year={2017}
}"
  )
}

article <- cff_from_bibtex(x)

cff_validate(article)
#> 
#> cff_validate results-----
#> Oops! This  cff object has the following errors:
#>                 field     message
#> 1 data["cff-version"] is required
#> 2        data.message is required

If you want to have a CITATION.cff file in such a way that the article is displayed as the reference on GitHub you need to create a valid CITATION.cff file first and add the reference to preferred-citation. See how to do in with cffr:

# Create a minimal version
cff_min <- cff()

cff_min
#> authors:
#> - family-names: Doe
#>   given-names: John
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: My Research Software

# Modify fields - use yours
# This override and add keys
cff_valid <- cff_create(cff_min, keys = list(
  message = "My repo",
  title = "My first repo",
  authors = list(cff_parse_person("John Doe")),
  `preferred-citation` = article
))

cff_valid
#> cff-version: 1.2.0
#> message: My repo
#> title: My first repo
#> authors:
#> - family-names: Doe
#>   given-names: John
#> preferred-citation:
#>   type: article
#>   title: Attention is all you need
#>   authors:
#>   - family-names: Vaswani
#>     given-names: Ashish
#>   - family-names: Shazeer
#>     given-names: Noam
#>   - family-names: Parmar
#>     given-names: Niki
#>   - family-names: Uszkoreit
#>     given-names: Jakob
#>   - family-names: Jones
#>     given-names: Llion
#>   - family-names: Gomez
#>     given-names: Aidan N
#>   - family-names: Kaiser
#>     given-names: Lukasz
#>   - family-names: Polosukhin
#>     given-names: Illia
#>   journal: Advances in neural information processing systems
#>   volume: '30'
#>   year: '2017'

# Validate!
cff_validate(cff_valid)
#> 
#> cff_validate results-----
#> Congratulations! This cff object is valid

# Create file
cff_write(cff_valid, "CITATION.cff")
#> CITATION.cff generated
#> 
#> cff_validate results-----
#> Congratulations! This .cff file is valid

# How it would be displayed on GitHub

cff_read("CITATION.cff") |> cff_to_bibtex() |> toBibtex()
#> @Article{vaswanishazeer:2017,
#>   title = {Attention is all you need},
#>   author = {Ashish Vaswani and Noam Shazeer and Niki Parmar and Jakob Uszkoreit and Llion Jones and Aidan N Gomez and Lukasz Kaiser and Illia Polosukhin},
#>   year = {2017},
#>   journal = {Advances in neural information processing systems},
#>   volume = {30},
#> }

^{Created on 2022-12-12 with reprex v2.0.2}

[jeyabbalas]

Thank you so much for elaborating! This is very helpful! I just tested it and it works as promised.

I had found about the mandatory fields but I was not using the preferred-citation fields in conjunction with it correctly.

Thank you again for your efforts with this helpful library! CFF files are quite confusing without such libraries.