Example metadata YAML for JOSS

[arfon]

Rather than posting in manubot/manubot#187, I figured I should post this here...

I've documented the JOSS format in this Gist: https://gist.github.com/arfon/3bd75497358a82812bda60146e11e61e

The two key customizations we have are:

1. A list of affiliations with numerical indexes so they can be referenced by multiple authors.
2. A couple of fields (aas-doi, aas-journal) that we use to cross-link papers that get jointly published together.

For #1, I would argue this is better than Pandoc's current solution, especially as the affiliations can be reused across authors.

For #2, I would like to generalize this in someway if possible. It feels like expressing a relationship to another document in the YAML header is somewhat useful? I believe Crossref metadata supports a IsRelatedTo which could be the right way to express this more generally?

[tarleb]

Ok, I have created and pushed an article-authoring-schema.json draft based on this.

If I understand the code in whedon's author.rb correctly, then we should have the fields given-name, middle-name, and last-name for each author in the output format. Is that correct?

[arfon]

Actually, the author only specifies a name field for JOSS but we split this using the Nameable library. This then results in given-name, middle-name, and last-name.

I'm not opposed to asking JOSS authors to specify the fields (given-name, middle-name, and last-name) separately. We just don't do this currently.

[tarleb]

Oh wow, that's a nice library! The LaTeX template doesn't mention any of these variables, so I guess they are internal only?

The W3C would probably be very disappointed if we were to asked authors for these name fields. On the other hand, citation schemes often seem to assume western names. How do other journals deal with this?

[arfon]

Oh wow, that's a nice library! The LaTeX template doesn't mention any of these variables, so I guess they are internal only?

Yeah, it's a very nice library. Very grateful to the authors!

Not completely. We use them for e.g. the Crossref metadata here and they are needed for the JATS output.

We also extract the last name of the first author for the citation string which is passed to the LaTeX template: https://github.com/openjournals/whedon/blob/a7f2cab555ea56c26022f24b3bd5b28503fb24e5/resources/joss/latex.template#L110

[arfon]

How do other journals deal with this?

My guess would be that many do this manually. They've got to be able to justify those charges somehow

[jcolomb]

If we look at orcid, they have one field for surname and one for first name, I think it is the same for most publishers. middle name is more blurry and not always included.
see https://github.com/JATS4R/JATS4R-Participant-Hub/blob/master/examples/authors_affiliations.md#scielo

[jcolomb]

For affiliation, the two ways to implement it (in the author fields or as a separate field with a link in the author field seem to be both accepted in jats.

Each system has its advantages, and which one is easier to use depends on the use case. For a standard, we want probably to get both possible (as jats is doing), right?

We could have a tool to go from one version to the other, too.