Add "externalURL" field to externalReference model

[aliceboizet]

We would like to be able to add several external urls on a germplasm, (the url could lead to a web page describing the germplasm for example) @cpommier

[BrapiCoordinatorSelby]

The documentation for externalReference.referenceId states

The external reference ID. Could be a simple string or a URI.

Can you describe the problem/use case a little bit more? Why do you need an additional field for the URL? Perhaps we need to expand on the existing documentation to clarify that referenceId can be used for URLs as needed?

[aliceboizet]

Ok, so using referenceId to put the url could work for what we need for now. But to me, referenceId refers to the id of the resource in the external system and the referenceURL would be the link to the web page describing the resource. So I am thinking that it could be useful sometimes to have both information.

[BrapiCoordinatorSelby]

I am pushing back on this a little bit because it seems like the type of thing that is useful for Germplasm and maybe Study, but a lot of concepts in BrAPI don't usually have a descriptive web page to go with them. Adding this field to external references would impact the whole spec, but would only improve a small part of it.

What if we could make it more flexible with something like externalReference.referenceType. Off the top of my head, the different reference types could be 'database ID', 'PUI', 'API link', or 'Documentation link'. Then you could have a response that might look like this:

externalReferences: [{
     referenceSource: "External Database 1",
     referenceType: "Database ID"
     referenceId: "1234ABCD"
   },{
     referenceSource: "External Database 1",
     referenceType: "PUI"
     referenceId: "doi.org/10.1109/5.771073"
   },{
     referenceSource: "External Database 1",
     referenceType: "API Link"
     referenceId: "https://api.example.org/brapi/v2/germplasm/1234ABCD"
   },{
     referenceSource: "External Database 1",
     referenceType: "Documentation link"
     referenceId: "https://example.org/doc/germplasm/GermplasmName123"
   }
]

Does this make sense? Would it handle what you are looking for? You can have a clearly delineated documentation URL, but it also adds functionality to the rest of the spec where a documentation URL doesn't apply.

[cpommier]

I see the interest of generalizing the approach and to handle Study and Germplasm the same way. We should definitly handl both those objects the same way.

Here are my first thought:

There is already the documentationUrl field in study and germplasm. The above proposition could suggest to remove documentationURL and replace it with externalReferences.referenceType:"Documentation link". But this would be a breaking change, therefore non desirable. Furthermore we need a difference between a main documentaitonURL and alternate URLs handled through external links. Which make me think that documentationURL documentation could be updated, see #560.

This could be unpleasant to display, one would need to group by reference source before handling a link (referenceId with referenceType=Database ID). Having something like the following should be easier to implement and handle it seems:

"externalReferences":[
{
"referenceId":"AGPD005",
"referenceSource":"MGIS",
"referenceURL":"https://www.crop-diversity.org/mgis/accession/01IDN150207"
}

]

[BrapiCoordinatorSelby]

@cpommier I think your proposed example is the same as @aliceboizet 's idea?

My problem is that externalReferences is present in every primary object in BrAPI. Modifications like this for Study and Germplasm will impact everything in the rest of the spec. I want to make sure that any modifications to externalReferences are useful to the majority of the spec. I think most BrAPI objects will not have a need for a reference URL along with the Id, but I think most objects will have different types of ex-ref Ids. (My assumptions could be wrong here, please let me know if you have counter examples)

Perhaps another solution would be to simply make documentationURL an array of URLs, or some other data structure added specifically to germplasm and study to handle this use case without impacting the whole spec.

[cpommier]

Hi, yes this example is the same as @aliceboizet 's.

I see your point. In an ideal world, we should use specialisation here. Indeed, I think only germplasm and study will need an aditionnal landing page/URL. Just an idea (I might be the first to say it's a bad idea at the en of the day): External references are added using this piece of code:

        externalReferences: 
          $ref: '#/components/schemas/ExternalReferences'

We could specialise this :

        externalReferences: 
          $ref: '#/components/schemas/ExternalURLReferences'

Idealy by importing ExternalReferences in ExternalURLReferences I don't know if it is doable though