Page MenuHomeSoftware Heritage

Answer IPOL's interrogations on deposit metadata
Closed, ResolvedPublic

Description

IPOL articles use to have several authors, but not all of them are involved in the development of the code.
Which names do I need to include in the 'author' field?

A first remark: you can add as many ‘author’ entries as needed (one entry per author).
As for whom to actually mention as author of the code, we recommend as best practice to add all person that made a significant contribution as author, even if the contribution does not materializes in lines of code: for example, person(s) designing the algorithm and interacting with the person(s) writing the code should probably be mentioned even if they did not actually write the code.
In the article “Attributing and Referencing (Research) Software: Best Practices and Outlook From Inria” (https://dx.doi.org/10.1109/MCSE.2019.2949413, preprint at https://hal.archives-ouvertes.fr/hal-02135891), 9 different roles are identified (each person may have several roles), namely
• Design
• Debugging
• Maintenance
• Coding
• Architecture
• Documentation
• Testing
• Support
• Management
And we have submitted a proposal to add these roles to authors in the CodeMeta vocabulary.
If you want to precisely specify which role had each author, you can do it, here is an example:
First schema.org should be added to entry xmlns like below:

<?xml version="1.0"?>
        <entry xmlns="http://www.w3.org/2005/Atom"
               xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0"
   xmlns:schemaorg=”http://schema.org”>

Now that we added the namespace we can use it to define roles, with its properties roleName, but also startDate and endDate if this information is available.
In the example here, the same person has two roles, you can add as many authors as you want and for each, as many roles as you want.

<schemaorg:author>
    <schemaorg:@type>Role<\schemaorg:@type>
    <schemaorg:roleName>Design<\schemaorg:roleName>
    <schemaorg:author> 
        <schemaorg:@id>http://example.org/~JL-Lisani <\schemaorg:@id>
<schemaorg:name>Jose-Luis Lisani<\schemaorg:name> 
    <schemaorg:affiliation>Universitat Illes Balears, Spain</schemaorg:affiliation>
<\schemaorg:author>
<\schemaorg:author>
 
<schemaorg:author>
    <schemaorg:@type>Role<\schemaorg:@type>
    <schemaorg:roleName>Coding<\schemaorg:roleName>
    <schemaorg:author> 
        <schemaorg:@id>http://example.org/~JL-Lisani <\schemaorg:@id>
<\schemaorg:author>
<\schemaorg:author>
 
<schemaorg:author>
    <schemaorg:@type>Role<\schemaorg:@type>
    <schemaorg:roleName>Support<\schemaorg:roleName>
    <schemaorg:startDate>2002<\schemaorg:startDate>
<schemaorg:endDate>2005 <\schemaorg:endDate>
    <schemaorg:author> 
        <schemaorg:@id>http://example.org/~Jane-Doe <\schemaorg:@id>
<schemaorg:name>Jane Doe<\schemaorg:name> 
    <schemaorg:affiliation>Universitat Illes Balears, Spain</schemaorg:affiliation>
<\schemaorg:author>
<\schemaorg:author>

in the particular case of this deposit, the tar.gz file includes some external code (Eigen libraries),
do I need to include this information somewhere in the metadata file?

A softwareRequirements property can be added, declaring this dependency in the metadata.

also, in many IPOL submissions some auxiliary functions for reading/writing images are written by authors different from the > author of the main functions. How can we include this information in the metadata?

You can add these persons as “contributors” using the property contributor

<codemeta:contributor>
    <codemeta:name> contributor’s name </codemeta:name>
    <codemeta:affiliation> contributor’s affiliation  </codemeta:affiliation>
</codemeta:contributor>

To accept Roles in our current metadata file we need to add schema.org as context.
Otherwise the "@type": "Role" would not be recognized.

This is the pure json-ld form:

{ "@context": ["https://doi.org/doi:10.5063/schema/codemeta-2.0", "http://schema.org"],
  "@type": "SoftwareSourceCode",
  "author": [
{
            "@type": "Role",
            "roleName": "Design",
            "author": {
                "@type Person",
                "@id": "http://example.org/~jdupont",
                "name": "John Dupont",
                      "affiliation": [
                    {
                        "@type": "Organization",
                        "name": "CNRS"
                    },
                    {
                        "@type": "Organization",
                        "name": "Inria"
                    },
                    {
                        "@type": "Organization",
                        "name": "Université de Paris"
                    }
                ]
            }
        },
        {
            "@type": "Role",
            "roleName": "Coding",
            "author": {
                "@id": "http://example.org/~jdupont"
            }
        }
   }]

This is the result that should be visible on SWH when translating xml into json.

  "origin_metadata": {
                "metadata": {
                    "@xmlns": "http://www.w3.org/2005/Atom",
                    "@xmlns:codemeta": "https://doi.org/10.5063/SCHEMA/CODEMETA-2.0",
            "@xmlns:schemaorg": "http://schema.org",
"schemaorg:author": [{
    “schemaorg:@type”: “Role”,
    “schemaorg: roleName”: “Design”,
            “schemaorg:author”: {
        “schemaorg:@type”: “Person”,
        "schemaorg:affiliation": "Universitat Illes Balears, Spain",
"schemaorg:name": "Jose-Luis Lisani",
“schemaorg:@id”: “http://example.org/~JL-Lisani”
}
},
“schemaorg:@type”: “Role”,
    “schemaorg: roleName”: “Coding”,
            “schemaorg:author”: {
“schemaorg:@id”: “http://example.org/~JL-Lisani”
}
},
},

For this result the xml, should look like this:

<?xml version="1.0"?>
        <entry xmlns="http://www.w3.org/2005/Atom"
               xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0"
   xmlns:schemaorg=”http://schema.org”>
 
 
<schemaorg:author>
    <schemaorg:@type>Role<\schemaorg:@type>
    <schemaorg:roleName>Design<\schemaorg:roleName>
    <schemaorg:author> 
        <schemaorg:@id>http://example.org/~JL-Lisani <\schemaorg:@id>
<schemaorg:name>Jose-Luis Lisani<\schemaorg:name> 
    <schemaorg:affiliation>Universitat Illes Balears, Spain</schemaorg:affiliation>
<\schemaorg:author>
<\schemaorg:author>
 
<schemaorg:author>
    <schemaorg:@type>Role<\schemaorg:@type>
    <schemaorg:roleName>Coding<\schemaorg:roleName>
    <schemaorg:author> 
        <schemaorg:@id>http://example.org/~JL-Lisani <\schemaorg:@id>
<\schemaorg:author>
<\schemaorg:author>

Event Timeline

moranegg triaged this task as High priority.May 20 2020, 8:43 PM
moranegg created this task.
rdicosmo updated the task description. (Show Details)May 20 2020, 8:46 PM

I removed the following sentence, that will be confusing for Jose Luis (and btw, here the external library is included so it is technically not a sparse deposit either :-))

This might be a good example for the sparse deposit use case (even if in this specific case, the deposit will include the libraries).

moranegg updated the task description. (Show Details)May 21 2020, 5:44 PM
moranegg updated the task description. (Show Details)

We decided to answer IPOL's question in a conservative way, by using the current metadata.xml approach, without introducing roles for authors, nor the JSON-LD format.

For the future, we want to be able to:

  • support the roles for authors, as proposed in the CodeMeta extension
  • provide a means of including directly in metadata.xml the full JSON-LD metadata file

This will be easier to recommend when the CodeMeta generator will handle author roles.

moranegg closed this task as Resolved.May 21 2020, 5:49 PM