Differences

This shows you the differences between two versions of the page.

--- hortus:fair:interoperability [2026/04/07 14:22] – savino.frisardi
+++ hortus:fair:interoperability [2026/04/07 14:43] (current) – savino.frisardi
@@ Line 27: / Line 27: @@
 ----
-===== Dissemination strategy =====
-Start from your dissemination goals.
+**Choose or design the right metadata format in HORTUS **
-==== Recommended approach ====
+Once you know your dissemination targets, choose the metadata format that best matches them:
-  * identify target platforms first
+    * 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.
-  * design metadata accordingly
+    * Use a Community metadata format when your discipline needs specific fields, terminology, or conventions that are not covered by standard formats.
-  * ensure compatibility with external systems
+    * 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 =====
+**Build a FAIR core description (what to prioritise in every record) **
-Prioritise:
+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)
-  * clarity
-  * completeness
-  * standardisation
-Focus on:
+**Practical interoperability tips (before you export or reuse metadata elsewhere) **
-  * descriptive fields
+Use the following tips to make your HORTUS metadata easier to map and reuse across platforms:
-  * keywords
-  * identifiers
-  * licences
-----
+    * 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.
-===== Interoperability tips =====
+** Dissemination options**
-Before exporting data:
+{{: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.|
-  * verify metadata completeness
-  * check format compatibility
-  * align with external standards
-  * avoid custom fields that break compatibility
 ----
-===== Dissemination options =====
+==== 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:
+.Open your resource detail page in the Marketplace.
+.In the Actions panel, select Export to Zenodo.
+.If this is your first export, you may be redirected to Zenodo to authorise the Marketplace application to deposit on your behalf.
+.After authorisation, Zenodo opens a deposition draft populated with the exported metadata.
+.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?
-HORTUS allows:
-  * internal discovery (Marketplace)
-  * linking to projects and events
-  * sharing across users
-  * exporting to external platforms
-----