LzLang
commented
9 months ago Request for uniforming the way relationships/associations are implemented.
Almost all schemes use a uniform format for the associations, for example observationVariables from Study.json:
{
"$defs": {
"Study": {
"properties": {
"observationVariables": {
"description": "The list of Observation Variables being used in this study. \n\nThis list is intended to be the wishlist of variables to collect in this study. It may or may not match the set of variables used in the collected observation records. ",
"items": {
"$ref": "ObservationVariable.json#/$defs/ObservationVariable"
},
"referencedAttribute": "studies",
"relationshipType": "many-to-many",
"type": "array"
}
}
},
"$id": "https://brapi.org/Specification/BrAPI-Schema/BrAPI-Core/Study.json",
"$schema": "http://json-schema.org/draft/2020-12/schema"
}As you can see the the association is a property itself therefore there is no problem in automatic converting the relationships. While working on associations I noticed that in all 3 associations are defined differently than all others, these are:
parentGermplasmin PedigreeNode.jsonprogenyGermplasmin PedigreeNode.jsonsiblingGermplasmin PedigreeNode.json
All of these three associations are defined differently than the others.
They are not defined as own property but rather as a nested property, as example: parentGermplasm:
{
"$defs": {
"PedigreeNode": {
"properties": {
"parents": {
"description": "A list of parent germplasm references in the pedigree tree for this germplasm. These represent edges in the tree, connecting to other nodes.\n<br/> Typically, this array should only have one parent (clonal or self) or two parents (cross). In some special cases, there may be more parents, usually when the exact parent is not known. \n<br/> If the parameter 'includeParents' is set to false, then this array should be empty, null, or not present in the response.",
"items": {
"properties": {
"parentGermplasm": {
"$ref": "Germplasm.json#/$defs/Germplasm",
"description": "The ID which uniquely identifies a parent germplasm",
"referencedAttribute": "progenyPedigreeNodes",
"relationshipType": "many-to-one"
},
"parentType": {
"description": "The type of parent used during crossing. Accepted values for this field are 'MALE', 'FEMALE', 'SELF', 'POPULATION', and 'CLONAL'. \n\nIn a pedigree record, the 'parentType' describes each parent of a particular germplasm. \n\nIn a progeny record, the 'parentType' is used to describe how this germplasm was crossed to generate a particular progeny. \nFor example, given a record for germplasm A, having a progeny B and C. The 'parentType' field for progeny B item refers \nto the 'parentType' of A toward B. The 'parentType' field for progeny C item refers to the 'parentType' of A toward C.\nIn this way, A could be a male parent to B, but a female parent to C. ",
"enum": [
"MALE",
"FEMALE",
"SELF",
"POPULATION",
"CLONAL"
],
"type": "string"
}
},
"required": [
"germplasmDbId",
"parentType"
],
"type": "object"
},
"type": [
"null",
"array"
]
}
}
},
"$id": "https://brapi.org/Specification/BrAPI-Schema/BrAPI-Germplasm/PedigreeNode.json",
"$schema": "http://json-schema.org/draft/2020-12/schema"
}As you can the the association is here defined as a nested property of the property parents.
The converter ignores nested properties therefore is the association also ignored.
Is there a possibility to uniform the format of the associations and define them as individual property? This would be very helpful!
BrapiCoordinatorSelby
asishallab
Open Questions
When parsing and reading through the ISA JSON Model a few questions arose. They are listed here.
How to treat properties of type
objectIn some cases BrApi JSON data models have properties of type
object. We can model them in Zendro in a number of ways.one-to-manyassociation.Probably this should be decided on a case-by-case level?
Example:
additionalInfoandadditionalPropertiese.g. inPerson.json.Structure of
additionalInfoThe definition taken from
Person.jsonsays:So, according to this specification, a person can have additional info. But, what is the structure of this object? The object
additionalInfocan have a number ofadditionalPropertiesthat are of typestring?additionalPropertiesa collection ofkeyandvaluepairs that can store any information? In that case, we cannot provide a schema, but must use serialized JSON.Reply from meeting with the BrApi group
additionalInfoshould be the only case, where we see non formatted data. In the BrApi test server we serialize and store this object as JSON.How to model
externalReferences?The array of external references is found in the Person model:
There are several question about this specification:
referenceIdandreferenceSourceare marked as required, but in theirtypespecificationnullis allowed.Response from the BrApi development team
ExternalReferencereferenceIdcan be e.g. a DOI URLPage & Holmes 2012, Inferring Phylogenies(actually this example does not exist)Another example would be the field-book-App:
field-bookValidation
Zendro has the capability to use any validation function on provided data. The Zendro framework can validate both data formats (syntactically) and data values (semantically). However, if the database has to be queried, we should consider whether this might be a performance bottleneck.
Example taken from
Sample.json:Questions:
Relationships / Associations
For some associations we see the foreign keys implemented in the JSON Specs, e.g. in
Sample.json:Here, we can conclude from the name of the foreign key and its existence:
many-to-[one|many, i.e. many samples belong to probably many (not one) germplasm)Germplasm).However a formal specification of all relationships would be extremely helpful and resolve open questions.
To be excluded properties
In some data models foreign keys are stated. Also, to spare the user to send another request to the RESTful API some of the properties of the associated (relationship) models are stored, too. See this example taken from
Sample.json:Using GraphQL these properties are not required. GraphQL specifically allows to fetch within a single HTTP-Request all data the user wants, including properties of related (associated) data models. Furthermore, given we at some point have a formal description of relationships between data models, foreign keys would ideally no longer be listed among data model definitions. Is there a way, we can recognize these "to be excluded" properties and not include them in the final GraphQL data model definitions. An easy quick and dirty solution would be a simple exclusion list?
Response from the GraphQL development group
DbIdis either a primary or a foreign key.