Differences

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

--- hortus:fair:interoperability [2026/04/07 14:36] – savino.frisardi
+++ hortus:fair:interoperability [2026/04/07 14:43] (current) – savino.frisardi
@@ Line 89: / Line 89: @@
-**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.
 {{:hortus:fair:zenodo_export1.jpg?600|}}
@@ Line 95: / Line 95: @@
 {{: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?