Knowledge Base

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
===== FAIR metadata, interoperability, and export to external platforms =====

High-quality metadata is the main mechanism that makes your research outputs FAIR (Findable, Accessible, Interoperable, Reusable). In HORTUS, metadata formats (metadata sets) let you describe resources in a structured way, so the same description can be reused across different systems (repositories, registries, community infrastructures, project portals) without re-entering everything.
Interoperability is not something you do only at the end (when you click an Export button). It starts earlier: you first decide where your resource should be published, deposited, or indexed, and then you align your metadata to the expectations of those target platforms.


**Start from your dissemination targets (choose the platforms first) **

Before selecting a metadata format or creating a new one, define your target platform(s). Depending on your discipline and the type of output, these can include:
    * General-purpose repositories (e.g., Zenodo).
    * Discipline/community infrastructures (e.g., CLARIN, SSHOC, or other domain repositories).
    * Institutional repositories (your university or institute repository).
    * Publication venues (journal/publisher platforms, conference proceedings portals).
    * Code and workflow hosting (e.g., GitHub/GitLab for software, notebooks, pipelines).
    * Scholarly dissemination platforms (e.g., ResearchGate and similar services).

For each target platform, answer the following questions (even briefly):
  1.What exactly will be deposited/published there (publication, dataset, software, audio/video, image collection, 3D model, etc.)?
  2.Which metadata fields are mandatory for that platform (e.g., title, creators, date, license, keywords, resource type)?
  3. Does the platform require or recommend controlled vocabularies or constrained values (e.g., licenses, languages, resource types)?
  4.Which identifiers matter most (DOI for outputs, ORCID for people, stable URLs for organisations, projects, and referenced resources)?
  5.How will HORTUS metadata be reused there (automated export, manual copy/paste, or external mapping)?


This short checklist becomes your interoperability compass: it tells you which metadata set to select in HORTUS and what to prioritise when you fill the fields.

----


**Choose or design the right metadata format in HORTUS **

Once you know your dissemination targets, choose the metadata format that best matches them:

    * Prefer a Standard metadata format whenever possible: it is designed for broad interoperability and is usually the best starting point when you plan to export or align metadata with external platforms.
    * Use a Community metadata format when your discipline needs specific fields, terminology, or conventions that are not covered by standard formats.
    * Use a Personal metadata format when you need a customised template for your own workflow. Whenever possible, create it by duplicating an existing Standard or Community format and then extending it (instead of inventing a completely new structure).

If your planned metadata format is relevant beyond your personal use (e.g., it would benefit a research group or a discipline), you can propose it for community use through the moderation workflow described in this guide.

**Build a FAIR core description (what to prioritise in every record) **

Even when a metadata format contains many fields, interoperability usually depends on a stable set of core descriptive elements. As a rule, treat the mandatory fields of your target platform(s) as mandatory for you as well, even if they are optional in HORTUS.
 
A practical FAIR core typically includes:
    * Title
    * Creators / contributors (preferably with ORCID where possible)
    * Description / abstract (what the resource is and why it matters)
    * Keywords / subjects
    * Dates (e.g., creation date and/or publication date)
    * Resource type (publication, dataset, software, image, etc.)
    * License and rights statement (explicit, unambiguous)
    * Related identifiers and links (DOI, project page, related resources, documentation)


**Practical interoperability tips (before you export or reuse metadata elsewhere) **

Use the following tips to make your HORTUS metadata easier to map and reuse across platforms:

    * Use persistent identifiers whenever possible (DOI for outputs when available, ORCID for people, stable URLs for organisations/projects).
    * Provide explicit rights and licensing information: missing or unclear licenses often block reuse or create legal ambiguity.
    * Prefer controlled vocabularies and stable values when available (e.g., language codes, resource types, licenses) to avoid spelling variants and improve machine readability.
    * Keep a consistent meaning for each field: do not use “Description” for internal notes, and do not use “Title” for filenames. If a value is internal-only, store it in an internal field or personal notes, not in core descriptive metadata.
    * Design for more than one target when needed: build a strong core description first, then add additional fields only where they bring clear value for a specific community or repository.

** Dissemination options** 

{{:hortus:fair:diseminationexport.jpg?600|}}

^ Dissemination route ^ What it is for ^ Typical user reason ^
| **Local export** | Download the entity or attached file to your own machine. | Keep a local copy, circulate a stable file, or continue work outside the browser. |
| **PDF or packaged export** | Generate a distributable representation of a resource record or associated content. | Share a stable version with colleagues, reviewers, or external stakeholders. |
| **Zenodo handoff** | Route a publish-ready output into an external repository workflow when enabled. | Increase openness, repository visibility, and long-term citability. |
| **Share dialog / copied link** | Create a reusable URL for email, chat, newsletters, or social channels. | Increase visibility without forcing others to repeat discovery steps. |
| **Project-level dissemination** | Keep related outputs visible together through a project page. | Show the output inside its wider scholarly context.|


----

==== Export to Zenodo (optional Marketplace feature) ====

If Zenodo is one of your dissemination targets, some Marketplace records provide an Export to Zenodo action. This lets you reuse the HORTUS record and metadata to start a Zenodo deposition.

Typical workflow:
  1.Open your resource detail page in the Marketplace.
  2.In the Actions panel, select Export to Zenodo.
  3.If this is your first export, you may be redirected to Zenodo to authorise the Marketplace application to deposit on your behalf.
  4.After authorisation, Zenodo opens a deposition draft populated with the exported metadata.
  5.Review and complete any required fields in Zenodo, then publish the deposition when ready.




{{:hortus:fair:zenodo_export1.jpg?600|}}

{{:hortus:fair:zenodoauthorization.jpg?600|}}


**Note**: the exact behaviour of the export depends on the current platform configuration (e.g., Zenodo sandbox vs production). Always review the metadata on Zenodo before final publication.


==== Common misconceptions and pitfalls ====

A few reminders that often help avoid confusion:
    * “FAIR = Open.” Not necessarily. Restricted access can still be FAIR if the access conditions are clear and the metadata remains meaningful.
    * “FAIR is only for datasets.” FAIR applies to many research outputs: publications, software, multimedia, workflows, and collections.
    * “Metadata is bureaucratic.” Good metadata is a practical investment: it saves time later, improves visibility, and increases trust and reuse.

**In short**: interoperability works best when you start from your dissemination plan, then choose/design the metadata format accordingly, and finally fill a strong FAIR core description.

==== Best practices for designing and using metadata formats ====

This section provides practical guidance to keep metadata entry consistent and to make your formats reusable by others.

** Naming conventions for fields ** 

A field name should be understandable without reading documentation, and stable enough to be reused across many records.
    * Prefer clear, descriptive names (e.g., “recording_date” rather than “date”).
    * Avoid duplicates and synonyms (do not create both “creator” and “author” unless you have a clear semantic distinction).
    * Keep naming consistent within a format (choose one style such as snake_case, and use it everywhere).
    * Where possible, align names with known standards (e.g., Dublin Core: title, creator, subject, description, publisher, date, language, rights).
    * Use singular names for single values and plural only when the field is explicitly multi-valued (e.g., “keywords”).

**Writing good field descriptions **

Field descriptions are your main pedagogical tool. They reduce ambiguity and make data entry faster.
    * Define the meaning of the field in one sentence.
    * Specify the expected format 
    * Add at least one example value.
    * If the field is optional, explain when to fill it (e.g., “Only for 3D models”).
    * If the field is mandatory, explain why it matters (e.g., needed for citation/export).

** When to use controlled vocabularies (lists of values) **

Use controlled vocabularies when you want to avoid spelling variants and make filtering reliable. This is especially useful for:
    * Licenses (CC BY, CC BY-SA, etc.).
    * Languages (use standard language names/codes).
    * Resource subtypes (e.g., “article”, “book chapter”, “report”).
    * Workflow or status fields (e.g., “draft”, “reviewed”, “final”) when you manage internal processes.

Avoid controlled vocabularies for fields that legitimately require free text (e.g., Abstract), unless you are encoding a very specific controlled terminology.


** Mandatory vs optional fields ** 

Making many fields mandatory may reduce completeness because users may abandon the form. A good approach is:
    * Keep the mandatory set small (only what is needed for discovery, citation, and reuse).
    * Make domain-specific technical fields optional unless they are essential for reuse.
    * If you require a field, explain it in the field description so users understand the purpose.

** Change management and versioning **

Once a format is used in many records, changing field meaning or removing fields can break interoperability. Consider these practices:
    * Prefer additive changes (add a new field) rather than breaking changes (rename or delete a field).
    * If a format needs major changes, create a new version (e.g., “MyFormat v2”) and keep the old one for legacy records.
    * Before proposing a format to the community, test it on a small sample of real resources.

** Quick checklist before publishing a resource or sharing a format **

    * Have I selected the most interoperable format available (or duplicated from a standard)?
    * Are Title, Description/Abstract, Creators, Date, License, Keywords and Resource type complete?
    * Do my field names avoid ambiguity and duplicates?
    * Do field descriptions include definition + expected format + example?
    * Are controlled vocabularies used where filtering and consistency matter?
    * Have I tested the format on at least one real resource?