Metadata guidelines

These guidelines include recommendations on metadata fields to be used while creating and/or reviewing an item entry in the SSH Open Marketplace.

The first subsection presents the fields that are mandatory and recommended depending on the type of items you want to create. A second section gives some explanations about the fields themselves - in case the title is not self-explanatory - how to fill in a field if you create an item and what you should check if you are a moderator.

• Mandatory fields are clearly indicated in the edit forms and you won’t be able to submit an item if these fields are empty
• Recommended fields are present by default in the forms, depending on the item types you want to create (i.e. if you want to create a publication, all the bibliographic metadata are included by default in the edit forms).
• Optional fields can be added via the edit forms.
• There are also hidden properties that are used by the moderation team in the process of curation, and these are only visible to moderators that have logged in.

Property Field	Tools & Services	Training Material	Publication	Datasets	Workflows	Steps (of a workflow)
Generic Metadata
label	mandatory
description	mandatory
actor	recommended
accessibleAt	recommended
externalID	recommended
media	recommended
thumbnail	recommended
relatedItems	recommended
Categorisation metadata
activity	recommended
keyword	recommended
discipline	recommended
language	recommended
mode-of-use	recommended
object-format
extent
IntendedAudience		recommended
standard					recommended
resource-category	recommended
Context metadata
see-also	recommended
usermanual-url
helpdesk-url	recommended
service-level-url
Access metadata
license	recommended
termsofuse-url
terms-of-use
accesspolicy-url
geographical-availabilities
privacypolicy-url
authentication
Bibliographic metadata
publication-type			recommended
publisher			recommended
publication-place			recommended
year		recommended
journal			recommended
conference			recommended
volume			recommended
issue			recommended
pages			recommended
Technical metadata
life-cycle-status
technical-readiness-level	recommended
version

Property Field’s name	How to fill in? Some recommendations for contributors	Quality checks: what and how moderators can validate content “Dashboard”1
Accessible at = “Go to…” button	URL of the resource. Landing page of the resource which could be the persistent identifier. Ideally, only one URL should be added as accessibleAt. For other URLs, see “externalID”.	Check that link is working (=> dashboard)
Access Policy URL	URL pointing to information about the access policy that applies to the Resource. Follows EOSC Portal Providers Documentation. Related to Authentication	Moderators will check for coherence of access policy url with linked Marketplace entry. (=> manually) Check that link is working (=> dashboard)
Activity	Contributors will select a term, drawn from the controlled vocabulary TaDIRAH, that describes the activities you can perform using the resource showcased in the SSH Open Marketplace Entry.	Moderators will check for consistency between activity selected and the resource described. (=> manually)
Actors	An Actor is a person or an organisation who contributed in some way to the creation of the linked resource described in the SSH Open Marketplace. Name of an actor is mandatory: while creating an actor, you need at least to add a name.	Moderators will ensure the consistency of the actors database (=> dashboard): one actor should only be registered once.
	Define role as one of: contributor, author, reviewer, director, programmer, editor, provider, contact, funder, helpdesk. By default, the Actor’s role is contributor. Add ExternalID for actors: ORCID, recommended. Add ROR IDs for research organisation.	It is recommended that the Actor(s) be identified by an externalID (esp. ORCID). Anything that can help to identify the contributor is recommended
Authentication	Describe the conditions or restrictions for a user to access the resource: “yes” when an authentication is needed, “no” when the resource is accessible without authentication. Related to Access Policy URL which provides more details about access to the resource.	Moderators will check for coherence of authentication with linked MP entry. (=> manually)
Conference	If the publication concerns a paper presented during a Conference, specify the name of the Conference	Moderators will check for coherence of conference selected with linked Marketplace entry. (=> manually)
Description	Check the original resource, and if possible, reuse the text description of the source. This description should be short (3 sentences recommended) and should aim at raising interest. Example: “Gephi is a Photoshop alternative for the humanities….“! Workflows specificities: longer descriptions may be needed for a workflow and its steps. ~1500 characters are recommended. Description field supports Markdown, although to include links we recommend using the see also property.	Ensure that description corresponds to and is up to date with the Marketplace entry described (=>manually) Every entry in the Marketplace should have a description between 25 and 1500 characters (=> dashboard)
Discipline	Contributors will select a term, drawn from the controlled vocabulary Austrian Fields of Science and Technology Classification 2012, that describes the discipline covered by the resource showcased in the MP. If a given resource is pertinent to too many disciplines, use the top-level concepts (such as “social sciences” or “humanities”. If the resource is discipline-agnostic or too generic, then leave blank.	Moderator will check for consistency between discipline selected and the resource described. (=> manually)
Extent	If an item covers other sub-items, use extent to describe the granularity. Example: you create an item for a training-material course that has 50 lessons (extent = 50 lessons)	Moderator will check for consistency between extent indicated and the resource described. (=> manually)
external ID	External identifiers (or labeled URLs) can be added to any items. At the moment, Wikidata, Github and DOIs identifiers can be added to the Marketplace items. These external identifiers are also used for actors (see actors recommendations) and ORCID iD, Wikidata or DBLP identifiers can be added to an actor’s profile.	Check that link is working (=> dashboard)
Geographical Availability	Locations where the Resource is offered to be chosen among the list of controlled values coming from the EOSC Resource Geographical Availability. Follows EOSC Portal Providers Documentation
Helpdesk URL	The URL to a webpage to ask more information from the Provider about this Resource. Link to the helpdesk where users with incidents and requests will be directed. It should allow private communication with providers (not a public forum). Follows EOSC Portal Providers Documentation	Moderators will check for coherence of helpdesk url with linked Marketplace entry. (=> manually) Check that link is working (=> dashboard)
Intended audience	Contributors will select a term, drawn from a controlled vocabulary, that describes the intended audience targeted by the resource showcased in the MP.	Moderators will check for coherence of audience selected with linked Marketplace entry. (=> manually)
Issue	A particular published issue of a journal, one or more of which will constitute a volume of the journal.	Moderators will check for coherence of issue selected with linked Marketplace entry. (=> manually)
Journal	The journal or magazine the work was published in. Please use ExternalID to add a PID (persistent identifier) for the journal, such as an ISSN.	Moderators will check for coherence of journal selected with linked Marketplace entry. (=> manually)
Keyword	Contributors will select an existing keyword or create concepts/terms for categorizing items to be used only if the concept does not fit in the TADIRAH activities used in the activity field. The recommended number of tags per item is 5.	Moderator will check for consistency between keywords selected and the resource described. (=> manually) Need to check for duplicates of terms regularly (=> dashboard & vocabulary manager)
Label	Name of the MP entry, ideally using the original name, spelling and case sensitivity. Multilinguality supported. No line break. Max length recommended 255 characters	Go to website “accessibleAt” and compare label with the name of the tool on the website (=> manually) Is label already used by another MP entry (=> dashboard duplication & merging of entries)
Language	Language(s) of content of a resource, or language in which an interface or a resource is available. Contributors will select a term, drawn from the controlled vocabulary ISO 639-3.	Regular checks for non-English content (=> dashboard) Moderator will check for consistency between language(s) selected and the resource described. (=> manually)
License	Contributors will select a license, drawn from the controlled vocabulary SPDX License List. If no matching, leave empty and fill in the terms of use.	Moderator will check for consistency between the license selected and the resource described. (=> manually)
Life Cycle Status	Status of the Resource life-cycle. List of controlled values coming from the EOSC Resource Life Cycle Status. Follows EOSC Portal Providers Documentation	Moderators will check for coherence of life-cycle-status with linked MP entry (=> manually).
Media	Media can be images or videos. Some recommendations: Images: 1. Look for freely available screenshots or visualisations of a tool (CC licence or similar). 2. If that doesn’t yield good results, look for material available on the original website. 3. Consider making own screenshots. 4. NOTE: You can add the URL of an image, if you choose to upload, image must be 1MB or smaller in size. Format supported: JPG, TIFF, PNG, GIF. Videos: 1. If on YouTube or Vimeo: just deliver the URL (title/caption of the video might be retrieved automatically). 2. If elsewhere: provide link to video and descriptive caption. Media-caption: every media should include a descriptive caption, i.e verbose information mentioning license and credits about the media used.	Automatic checks will determine presence or not of media (=> dashboard).Moderators will check for coherence of media with linked MP entry. (=> manually) More media-sources can be added by moderators using the API call: /api/media-sources. More information in the moderators guidelines.
Mode of use	Contributors will select a mode of use type, drawn from an open controlled vocabulary. Examples: desktop; client (install locally); browser-based; mobile app; programming library; API; (REST-API). New concepts can be suggested to the vocabulary if needed.	Moderators will check for coherence of mode of use with linked MP entry. (=> manually)
Object format	File format of the linked resource. Choose from the controlled vocabulary IANA Media Types.	Moderators will check for coherence of format selected with linked MP entry. (=> manually)
Pages	Page numbers, separated either by commas or double-hyphens.	Moderators will check for coherence of pages selected with linked MP entry. (=> manually)
Privacy policy URL	Link to the privacy policy applicable to the Resource. A Privacy Policy is a document that explains how and for what purposes the linked tool or service will utilize, disseminate, and stock user’s data. Follows EOSC Portal Providers Documentation	Moderators will check for coherence of privacy policy url with linked MP entry. (=> manually) Check that link is working (=> dashboard)
Publication type	Contributors will select a publication type, drawn from the controlled vocabulary Bibliographic Ontology BIBO.	Moderators will check for coherence of publication type selected with linked MP entry. (=> manually)
Publication Place	The place of publication	Moderators will check for coherence of publication-place selected with linked MP entry. (=> manually)
Publisher	An entity responsible for making the resource available.	Moderators will check for coherence of publisher selected with linked MP entry. (=> manually)
Related items	Relations between SSH Open Marketplace items help to create context. If you know about a training material describing or citing a tool or service for example, use this to provide more context. To relate to items external to the Marketplace, use the See also property.	Relations between items are central to ensure contextualisation and quality of the Marketplace entries! Check the coherence of the relations suggested (=> manually) Automatic checks will determine presence or not and numbers of relations (=> dashboard).
	Relation type: relates-to/is-related-to: to mark a simple relation between items; documents/is-documented-by: use the document relation when a resource provides information on another; mentions/is-mentioned-in: when one resource refers to another. By default, the relation-type is “related-to”
Resource category	Contributors will select a resource category type, drawn from the EOSC categories controlled vocabulary. This helps refining the resource’s nature and function. Follows EOSC Portal Providers Documentation	Moderator will check for consistency between categories added and the resource described. (=> manually)
See also	This is a URL-based field. It references additional materials linked to the resource, but external to the SSH Open Marketplace. These are interesting resources we don’t want to add as entries in the MP, but that can be useful for the users. For relations between MP entries, see related items.	Moderator will check for consistency between references added and the resource described. (=> manually) Automatic checks with other URLs-based fields (=> dashboard) Check that link is working (=> dashboard)
Service Level URL	Webpage with the information about the levels of performance of the Resource that a Provider is expected to deliver. For example, link to a Service Level Agreement (SLA) or Service Level Specification (SLS) applicable to the Resource. Follows EOSC Portal Providers Documentation	Moderators will check for coherence of service level url with linked MP entry. (=> manually) Check that link is working (=> dashboard)
Standard	Contributors will select a standard used by the tool or service, drawn from a controlled vocabulary built within the PARTHENOS project. If there is no match in the list of concepts provided, contributors can suggest a new standard.	Moderators will check for coherence of the standard selected with linked MP entry. (=> manually)
Technology Readiness Level	The Technology Readiness Level of the Resource. List of controlled values from the EOSC Resource TRL. Follows EOSC Portal Providers Documentation	Moderators will check for coherence of TRL level with linked MP entry. (=> manually)
Terms Of Use	If the license is not known among the choices provided by the controlled vocabulary, Terms Of Use provides a free text field to describe the type of use (terms of use, copyright…)	Field to check regularly and change into license if matches are identified. Need to check for duplicates of terms regularly (=> dashboard & vocabulary manager)
Terms of Use URL	Webpage describing the rules, resource conditions and usage policy which one must agree to abide by in order to use the resource. Follows EOSC Portal Providers Documentation	Moderators will check for coherence of Terms of use url with linked MP entry. (=> manually) Check that link is working (=> dashboard)
Thumbnail	Please try to provide a logo related to the MP Entry, if we are authorized to use it. If no logo is submitted, a generic icon is automatically provided. Recommendations in terms of quality: 200x200 pixel.	Moderator will check for consistency between image added and the resource described, and for quality of the image chosen. (=> manually)
Tool Family	This field can be used to further define the type of tool, or if the tool belongs to a suite of tools for example.	Moderators will check for coherence of the tool family indicated with linked MP entry. (=> manually)
User Manual URL	Link to the Resource user manual, documentation, or other basic user instructional information about the Resource. Follows EOSC Portal Providers Documentation	Moderators will check for coherence of user manual url with linked MP entry. (=> manually) Check that link is working (=> dashboard)
Version	This refers to the version of the tool or service that is referenced in the Marketplace. This refers to the names, often in the form of numbers (e.g. 1.2), that describe unique states of a tool or service. Recommendations in case of several versions: creating a new item or updating version field?
Volume	The volume of a journal or multivolume book.	Moderators will check for coherence of volume selected with linked MP entry. (=> manually)
Year	The year of publication (or, if unpublished, the year of creation)	Moderators will check for coherence of year selected with linked MP entry. (=> manually)

property	vocabulary	type of vocabulary
geographical- availability	EOSC Geographical Availability List	closed
life-cycle-status	EOSC Life Cycle Status List	closed
resource-category	EOSC Resource Category List	closed
intended-audience	audience	closed
mode-of-use	Invocation types	closed
language	ISO 639-3 Language Codes	closed
keyword	Keywords from SSHOC MP	open
object-format	Media Types from IANA	closed
discipline	ÖFOS 2012. Austrian Fields of Science and Technology Classification 2012	closed
license	Software License from SPDX	closed
standard	SSK Standards List	closed
activity	TaDiRAH 2	closed
publication-type	The Bibliographic Ontology Concept Scheme	closed

#

Footnotes

1. Problematic items are automatically flagged and prioritised for curation within the editorial dashboard “Manually”. Moderator has to assess coherence and relevance of the info ↩