Guide for naming metadata blocks and fields has been published

[ardc-shorn]

Outcome of tech chat with SRO, RLE, STO on 2023-03-10.

As discussed, I've written up a guide for normalising the schema documentation and API implementation: https://github.com/au-research/raid-metadata/blob/main/doc/metadata-block-field-naming.md

It has some weirdness we didn't anticipate in the discussion, particularly related to the repercussions of going down the "duplicate block name by prefixing it onto the field name" route.

For the moment, I've said that

• current field names that duplicate the block name elsewhere in their name need to be renamed
  • e.g. dates.startDate is to be renamed as date.dateStart
    • the alternative being date.dateStartDate? 🤢
• nested field blocks duplicate block names all the way to the root of the metadata
  • e.g. contributors.positions.startDate becomes contributor.contributorPosition.contributorPositionStartDate
  • alternative: contributor.contributorPosition.positionStartDate, based on modelling the "sub-block" type name as Position, instead of its current name of ContributorPosition.
  • and that'll get even worse as we implement further block nesting
    • on the other hand, if you just have field name startDate you don't know what it's for - with contributorPositionStartDate, you know exactly what's going on

Thoughts?