Draft: Repository Reorganisation

The merge requests changes the core organizational goal of this repository from “What you see is what you get” to “Single point of truth”. This applies to the versioning of the standard and its documentation:

Currently, the version of the standard is tracked with git, the version branches, and the schema files for different versions. I propose to simplify this by only using git tags to track the schema versions. The master/main branch will always contain the latest version of the standard. Changes to the standard are staged in a development branch.
This repository contains the standard, its documentation and the governance information. As each may require different release cycles, the repository is split into the docs folder, which contains meta and governance information, and the standard folder, which contains the schema and all information closely coupled to the schema. The site generation was modified, to always show the latest governance information and all standard versions defined by tags. This ensures that meta information can be updated without having to create a new standard version.

Most of the schema documentation currently is not coupled to the schema itself, but duplicates information defined by the schema. This leads to inaccurate and outdated information (e.g. icons, context). Generating the field, icon and context information from the schema itself, consolidates the single source of truth at the schema level. The iFDO schema file was split into the sections, so the documentation can be split into the sections. While this also helps the readability of the schema, the split schema is equivalent to the original schema.

This results in this site structure:

- Introduction:
  - What is FAIR?: 'index.md'
  - What are FAIR marine images?: 'FAIR-marine-images.md'
- iFDOs:
  - Overview:
    - iFDO: 'overview/iFDO-overview.md'
    - iFDO Core: 'overview/iFDO-core.md'
    - iFDO Capture: 'overview/iFDO-capture.md'
    - iFDO Content: 'overview/iFDO-content.md'
  - Standard:
      - "{version}":
          - Documentation:
              - iFDO Structure: 'standard/{version}/documentation/iFDO-structure.md'
              - iFDO Core: 'standard/{version}/documentation/iFDO-core.md'
              - iFDO Capture: 'standard/{version}/documentation/iFDO-capture.md'
              - iFDO Content: 'standard/{version}/documentation/iFDO-content.md'
              - Context: 'standard/{version}/documentation/iFDO_vocabulary-term-mapping.md'
          - Examples:
              - Image Example: 'standard/{version}/examples/ifdo-image-example.json'
              - Video Example: 'standard/{version}/examples/ifdo-video-example.json'
          - Schema:
              - iFDO: 'standard/{version}/schema/ifdo.json'
              - iFDO Core: 'standard/{version}/schema/ifdo-core.json'
              - iFDO Content: 'standard/{version}/schema/ifdo-content.json'
              - iFDO Capture: 'standard/{version}/schema/ifdo-capture.json'
              - Annotation Schema: 'standard/{version}/schema/annotation.json'
              - Provenance Schema: 'standard/{version}/schema/provenance.json'
          - Icons for iFDO fields: 'standard/{version}/iFDO-icons.md'
          - Changelog: 'standard/{version}/changelog.md'
  - Governance: governance.md
- SOPs (Standard operating procedures):
  - Overview: 'sops/sop-overview.md'
  - Folder structure: 'sops/conventions/folder-structure.md'
  - File formats: 'sops/conventions/file-formats.md'
  - Provenance documentation: 'sops/conventions/provenance-documentation.md'
  - Image Curation SOP: 'sops/SOP_image-curation.md'
  - iFDO data collection: 'resources/sheets/Overview-iFDO-metadata-collection.xlsx'
  - iFDO data collection (detailed): 'resources/sheets/Detailed-iFDO-metadata-collection.xlsx'

Changes

Schema Changes

Schema changes are only necessary fixes. The schema is still equivalent to old schema.

• Changed enum fields to anyOf in order to describe options in the schema
• Added option "dm" for "image-pixel-magnitude", as this was described in icons
• Added optional options "CC-0" "CC-BY" to image-license-name to generate icons documentation
• Added missing type information to image-annotations-frames
• Added missing reference to agents in provenance-entities-generated-by

Added Documentation Auto-Generation

• Field documentation
• Required-Fields documentation for documenting the structure
• Icon documentation
• Context documentation
• Change-Log (based on git tags)

Repository Changes

• Mayor reorganisation of the repository (see above)
• Added example for video image items
• Removed html documentation generator and the resulting artefacts (Now solved with hooks and generation to markdown)
• Removed unused icons
• Added tests for generation code
• Added tests for examples/schema (example files are tested against current schema)
• Fixed CI pipeline deploy and build1
• Added tests to CI pipeline

To Discuss

• I disallowed additional fields by setting "unevaluatedProperties": false inside the iFDO-fields definition to test the correctness of the splitting of the schema. This would solve #66
• Do the excel sheets belong to governance information or the standard?
• Structure of SOP part

To Do

• "Merge" schema v2.0.1 and v2.1.0 onto standard/schema/ and create version tags (last thing to do, before merge)