Docs: data provenance, ecological indicator scales, and the CORS story - #40
Merged
Conversation
…ORS story Follows the 2.1.0 release and the answer given on trefle-api#90. - New 'Data provenance' page documenting GET /species/:id/facts, the evidence_type/status vocabulary, how to read a disagreement between sources, the ingestion guards and what completion_ratio measures. - plants-fields/complete-data: light, atmospheric_humidity, soil_humidity, soil_nutriments and soil_salinity are Ellenberg-style ecological indicators from Baseflor, describing the species' habitats rather than measured tolerance. Explains why they legitimately disagree with the USDA classes, that they are calibrated for the temperate European flora, and that 0 is a value rather than 'unknown'. - client-side-apps: reads are now cross-origin, so the page no longer claims the browser can't query the API. States what CORS covers (reads plus the claim call, not writes) and why the JWT claim must still be made server-side. - getting-started: the Plant/Species example listed a subspecies that is neither in the database nor accepted (Abies lasiocarpa is a species of its own). Replaced with the two varieties actually served, and added a note on the Plant/Species vocabulary.
The bulk import pipelines still write directly to the models, so facts today come from accepted corrections and the automated checks only. Say so rather than implying every value carries provenance.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents what shipped in 2.1.0, and makes good on the answer given to the reporter of trefle-api#90.
New: Data provenance page
Documents
GET /api/v1/species/{id}/facts— theevidence_typeandstatusvocabulary, how to tell that two sources disagree, the plausibility guards at ingestion, and whatcompletion_ratioactually measures.The ecological indicator scales (trefle-api#90)
light,atmospheric_humidity,soil_humidity,soil_nutrimentsandsoil_salinityare Ellenberg-style indicators from Baseflor: they describe where the species grows in the wild, not what an individual plant tolerates. The page now says so, explains why they legitimately disagree with the USDA tolerance classes (the reporter's exact confusion), notes they are calibrated for the temperate European flora, and states that0is a value rather than missing data. Field descriptions reworded accordingly on both field pages.CORS
client-side-appsopened with "you can't make queries from the browser", which stopped being true in 2.1.0. It now states what CORS actually covers — reads anywhere under/apiplusPOST /api/auth/claim, not writes — while keeping the JWT claim flow as the recommendation, with an explicit warning that the claim call must stay server-side.Factual fix in getting-started
The Plant/Species example listed
Abies balsamea ssp. lasiocarpaas a subspecies of the balsam fir. That taxon is not in the database and is not accepted — Abies lasiocarpa is a species of its own. Replaced with the two varieties the API actually serves (verified against the dataset), plus a note on the Plant/Species vocabulary and on not inferring relationships from names.Build verified locally: green, new page and cross-links resolve, no new broken anchors.