Inconsistent key names and descriptions relating to email addresses and GitHub handles

[amanda-wein]

Description of the issue

There are some inconsistencies in key names and descriptions relating to contact information for creators of datasets and metadata. These were discovered when using the OEMetaBuilder tool (https://openenergyplatform.org/dataedit/oemetabuilder/) while referencing the OEMetadata schema for additional details on how to properly fill out the fields presented in the tool.

In the OEMetaBuilder form, under the Contributors section, there is a field asking for the contributor's email address. In the metadata schema, this field is titled "email" but the description states that either an email address or a GitHub handle is acceptable.

Elsewhere in the OEMetaBuilder form, in the Context section, it is specified that a field labeled "E-Mail Contact" can accept either an email address or a GitHub handle. This field corresponds to a key called "contact" in the metadata schema.

It is confusing to see the field "E-Mail Contact" that accepts email addresses or GitHub handles, and then later on in the same form, see the field "Email" that only accepts email addresses. This is made more confusing when one looks at the metadata schema and sees that the "Email" field will actually accept a GitHub handle, but the OEMetaBuilder form doesn't state that anywhere.

Is there a preference for one contact method over the other, or are either equally acceptable?

Ideas of solution

To make the intended use of these fields clearer, I would propose the following steps (assuming that there is no preference between having users enter an email address versus a GitHub handle in these fields):

• In the OEMetaBuilder:
  • In the Context section, change the field label "E-Mail Contact" to "Contact"
  • In the Contributors section, change the field label "Email" to "Contact"
  • In the Contributors section, change the description of this field from "E-mail address of the contributor" to "E-mail address or GitHub handle of the contributor."
• In the metadata schema:
  • Change the name of key 14.2 from "email" to "contact."

These changes would make the schema internally consistent, with both key 9.4 and key 14.2 for contact information being clearly labeled and accepting both email addresses and GitHub handles. They also make the respective fields in the OEMetaBuilder form consistent and easier to understand for the user.

Workflow checklist

• I am aware of the workflow in CONTRIBUTING.md

[jh-RLI]

I agree that we need to harmonize the naming and make sure it is appropriate for all use cases (email, GitHub handle or other useful information). I would like to briefly explain the reason why this is different. It's because we don't want to mix the style of the user interface that is visible in the OEMetaBuilder tool on the oeplatform website with the metadata specification. Presentation information is currently not part of the oemetadata specification, which is technically defined in the schema.json for each release version. On the OEP we use this schema.json and add additional information that is only relevant for the tool on the oep website to display certain headings or make some fields read-only. We also added some fields that contain a javascript callback. These fields provide an autocomplete function that we use for ontological annotation to associate the metadata with the terms defined in the OEO. This is also exclusive to the OEMetaData tool.

In order to maintain the interoperability of the oemetadata specification, the motivation was not to keep this type of information separate. I see two possibilities: Either we add an oemetabuilder_schema.json to each version that can be used with the OEMetaBuilder tool, or we add the additional information to the schema.json after all. If we conclude that they have no impact on the use of schema.json in third party use cases. The second option would require further investigation before we can implement it.

[Ludee]

The datapackage 2.0 offers a great solution to this:

"givenName": "Ludwig",
"familyName": "Hülk",
"path": "https://github.com/Ludee",
 "email": null, -> remove / use context/contact!
"roles": ["creator", "contact", "rightsHolder", "dataCurator"]
"organization": "Reiner Lemoine Institut",

[Ludee]

Decide:

"title": "Ludwig Hülk"

"givenName": "Ludwig",
"familyName": "Hülk",