Skip to content

Enhance BrAPI Schema with examples and improve documentation #685

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BrapiCoordinatorSelby merged 1 commit into from
Sep 8, 2026
Merged

Enhance BrAPI Schema with examples and improve documentation #685

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Specification/BrAPI-Schema/BrAPI-Common/Attribute.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
}
},
"required": [
"attributeDbId",
"attributeName"
]
}
Expand Down
4 changes: 3 additions & 1 deletion Specification/BrAPI-Schema/BrAPI-Common/GeoJSONGeometry.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
{
"$defs": {
"GeoJSONGeometry": {
"nullable": true,
"brapi-metadata": {
"discriminatorPropertyName": "type"
},
"oneOf": [
{
"description": "Copied from RFC 7946 Section 3.1.1\n\nA position is an array of numbers. There MUST be two or more elements. The first two elements are longitude and latitude, or\neasting and northing, precisely in that order and using decimal numbers. Altitude or elevation MAY be included as an optional third element.",
Expand Down
24 changes: 16 additions & 8 deletions Specification/BrAPI-Schema/BrAPI-Common/Variable.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@
"type": [
"null",
"string"
]
],
"example": "Maize"
},
"contextOfUse": {
"description": "Indication of how trait is routinely used. (examples: [\"Trial evaluation\", \"Nursery evaluation\"])",
Expand All @@ -29,15 +30,17 @@
"type": [
"null",
"string"
]
],
"example": "2.0"
},
"documentationURL": {
"description": "A URL to the human readable documentation of an object",
"format": "uri",
"type": [
"null",
"string"
]
],
"example": "https://wiki.brapi.org/documentation.html"
},
"externalReferences": {
"description": "An array of external reference ids. These are references to this piece of data in an external system. Could be a simple string or a URI.",
Expand All @@ -57,21 +60,24 @@
"type": [
"null",
"string"
]
],
"example": "flowering"
},
"institution": {
"description": "Name of institution submitting the variable",
"type": [
"null",
"string"
]
],
"example": "The BrAPI Institute"
},
"language": {
"description": "2 letter ISO 639-1 code for the language of submission of the variable.",
"type": [
"null",
"string"
]
],
"example": "en"
},
"method": {
"description": "A description of the way an Observation should be collected. \n<br>For example, an ObservationVariable might be defined with a Trait of \"plant height\", a Scale of \"meters\", and a Method of \"tape measure\". This variable would be distinct from a variable with the Method \"estimation\" or \"drone image processing\". ",
Expand Down Expand Up @@ -100,14 +106,16 @@
"type": [
"null",
"string"
]
],
"example": "Dr. Bob Robertson"
},
"status": {
"description": "Variable status. (examples: \"recommended\", \"obsolete\", \"legacy\", etc.)",
"type": [
"null",
"string"
]
],
"example": "recommended"
},
"submissionTimestamp": {
"description": "Timestamp when the Variable was added (ISO 8601)",
Expand Down
15 changes: 10 additions & 5 deletions Specification/BrAPI-Schema/BrAPI-Core/List.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,18 +56,21 @@
"type": [
"null",
"string"
]
],
"example": "This is a list of germplasm I would like to investigate next season"
},
"listName": {
"description": "Human readable name of a List",
"type": "string"
"type": "string",
"example": "MyGermplasm_Sept_2020"
},
"listOwnerName": {
"description": "Human readable name of a List Owner. (usually a user or person)",
"type": [
"null",
"string"
]
],
"example": "Bob Robertson"
},
"listOwnerPerson": {
"$ref": "Person.json#/$defs/Person",
Expand All @@ -80,14 +83,16 @@
"type": [
"null",
"integer"
]
],
"example": 53
},
"listSource": {
"description": "The description of where a List originated from",
"type": [
"null",
"string"
]
],
"example": "GeneBank Repository 1.3"
},
"listType": {
"description": "A flag to indicate the type of objects that are referenced in a List",
Expand Down
48 changes: 32 additions & 16 deletions Specification/BrAPI-Schema/BrAPI-Core/Location.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
"type": [
"null",
"string"
]
],
"example": "L1"
},
"additionalInfo": {
"description": "A free space containing any additional information related to a particular object. A data source may provide any JSON object, unrestricted by the BrAPI specification.",
Expand All @@ -19,14 +20,16 @@
"type": [
"null",
"string"
]
],
"example": "North East corner of greenhouse"
},
"coordinateUncertainty": {
"description": "Uncertainty associated with the coordinates in meters. Leave the value empty if the uncertainty is unknown.",
"type": [
"null",
"string"
]
],
"example": "20"
},
"coordinates": {
"description": "One geometry as defined by GeoJSON (RFC 7946). All coordinates are decimal values on the WGS84 geographic coordinate reference system.\n\nCopied from RFC 7946 Section 3.1.1\n\nA position is an array of numbers. There MUST be two or more elements. The first two elements are longitude and latitude, or\neasting and northing, precisely in that order and using decimal numbers. Altitude or elevation MAY be included as an optional third element.",
Expand All @@ -38,36 +41,41 @@
"type": [
"null",
"string"
]
],
"example": "PER"
},
"countryName": {
"description": "The full name of the country where a Location is located\n<br/> MIAPPE V1.1 (DM-17) Geographic location (country) - The country where the experiment took place, either as a full name or preferably as a 2-letter code.",
"type": [
"null",
"string"
]
],
"example": "Peru"
},
"documentationURL": {
"description": "A URL to the human readable documentation of an object",
"format": "uri",
"type": [
"null",
"string"
]
],
"example": "https://brapi.org"
},
"environmentType": {
"description": "Describes the general type of environment of a Location. (ex. forest, field, nursery, etc)",
"type": [
"null",
"string"
]
],
"example": "Nursery"
},
"exposure": {
"description": "Describes the level of protection/exposure for things like sun light and wind at a particular Location",
"type": [
"null",
"string"
]
],
"example": "Structure, no exposure"
},
"externalReferences": {
"description": "An array of external reference ids. These are references to this piece of data in an external system. Could be a simple string or a URI.",
Expand All @@ -87,29 +95,34 @@
"type": [
"null",
"string"
]
],
"example": "123 First Street, Townsville, AB 12345, USA"
},
"instituteName": {
"description": "The full name of the institute at a particular Location\n<br/> MIAPPE V1.1 (DM-16) Contact institution - Name and address of the institution responsible for the study.",
"type": [
"null",
"string"
]
],
"example": "Plant Science Institute"
},
"locationDbId": {
"description": "The unique identifier for a Location",
"type": "string"
"type": "string",
"example": "3cfdd67d"
},
"locationName": {
"description": "A human readable name for a Location\n<br/> MIAPPE V1.1 (DM-18) Experimental site name - The name of the natural site, experimental field, greenhouse, phenotyping facility, etc. where the experiment took place.",
"type": "string"
"type": "string",
"example": "Location 1"
},
"locationType": {
"description": "A short description of a type of Location (ex. Field Station, Breeding Location, Storage Location, etc)",
"type": [
"null",
"string"
]
],
"example": "Field Station"
},
"parentLocation": {
"description": "The unique identifier for a Location\n<br/> The Parent Location defines the encompassing Location that a smaller Location belongs to. \nFor example, an Institution might have multiple Field Stations inside it and each Field Station might have multiple Fields.",
Expand Down Expand Up @@ -157,21 +170,24 @@
"type": [
"null",
"string"
]
],
"example": "Private"
},
"slope": {
"description": "Describes the approximate slope (height/distance) of a Location.",
"type": [
"null",
"string"
]
],
"example": "0"
},
"topography": {
"description": "Describes the topography of the land at a Location. (ex. Plateau, Cirque, Hill, Valley, etc)",
"type": [
"null",
"string"
]
],
"example": "Valley"
},
"seedLots": {
"title": "SeedLots",
Expand Down
34 changes: 18 additions & 16 deletions Specification/BrAPI-Schema/BrAPI-Core/Person.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,16 @@
"type": [
"null",
"string"
]
],
"example": "Bob likes pina coladas and getting caught in the rain."
},
"emailAddress": {
"description": "email address for this person",
"type": [
"null",
"string"
]
],
"example": "bob@bob.com"
},
"externalReferences": {
"description": "An array of external reference ids. These are references to this piece of data in an external system. Could be a simple string or a URI.",
Expand All @@ -39,7 +41,8 @@
"type": [
"null",
"string"
]
],
"example": "Bob"
},
"instituteName": {
"description": "The name of the institution which this person is part of\n\nMIAPPE V1.1 (DM-35) Person affiliation - The institution the person belongs to",
Expand All @@ -53,46 +56,45 @@
"type": [
"null",
"string"
]
],
"example": "Robertson"
},
"mailingAddress": {
"description": "physical address of this person",
"type": [
"null",
"string"
]
],
"example": "123 Street Ave, City, State, Country"
},
"middleName": {
"description": "Persons middle name",
"type": [
"null",
"string"
]
],
"example": "Danger"
},
"personDbId": {
"description": "Unique ID for a person",
"type": "string"
},
"personName": {
"description": "The full name of a person",
"type": [
"null",
"string"
]
"type": "string",
"example": "14340a54"
},
"phoneNumber": {
"description": "phone number of this person",
"type": [
"null",
"string"
]
],
"example": "+1-555-555-5555"
},
"userID": {
"description": "A systems user ID associated with this person. Different from personDbId because you could have a person who is not a user of the system.",
"type": [
"null",
"string"
]
],
"example": "bob-23"
},
"orcid": {
"description": "The Open Researcher and Contributor ID for this person (orcid.org)\n\nMIAPPE V1.1 (DM-33) Person ID - An identifier for the data submitter. If that submitter is an individual, ORCID identifiers are recommended.",
Expand Down
Loading
Loading