search

plantbreeding / BrAPI

Repository for version control of the BrAPI specifications
https://brapi.org
MIT License
57 stars 32 forks source link

update documentaitonURL documentation #560

Open cpommier opened 2 years ago

cpommier commented 2 years ago

Curently in study and germplasm the documentation url field is described as : 

documentationURL:
          description: A URL to the human readable documentation of an object
          format: uri
          type: string
          example: https://wiki.brapi.org

It should be updated as : germplasm

documentationURL:
          description: A URL to the human readable description of a germplasm, such as a genebank web page
          format: uri
          type: string
          example: https://urgi.versailles.inrae.fr/faidare/germplasm?id=aHR0cHM6Ly9kb2kub3JnLzEwLjE1NDU0L1Y4V1JIWQ%3D%3D or https://www.crop-diversity.org/mgis/accession/01IDN150207

study

documentationURL:
          description: A URL to the human readable documentation of a study
          format: uri
          type: string
          example: https://urgi.versailles.inra.fr/ephesis/ephesis/viewer.do#trialCard/trialId=241
cpommier commented 2 years ago

what do you think @BrapiCoordinatorSelby ?

BrapiCoordinatorSelby commented 2 years ago

I like the new example URLs

Regarding the descriptions, there are two conflicting schools of thought here. One idea, coming from controlled vocabulary/ontology/linked-data types of work, says that if two thing have the same name, they should have the same definition. If we want the descriptions to vary, then the terms need to be different ie germplasmDocumentationURL and studyDocumentationURL The other idea is to make it as easy as possible to understand and use the specification, like you are suggesting. The definitions should make sense in context and be as helpful and descriptive as possible.

I'm happy to add these new descriptions to the spec because I do think it will make it easier to use. But we need to acknowledge that we are making the choice to have two not identical definitions for the same term. We could add the germplasm... and study... prefixes, but that would be structural change that would have to wait until V2.2. I can change the descriptions and examples now because it doesn't impact any implementation of the spec.