Enhance community classification GET endpoint #174
Merged
Conversation
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
Previously, we returned a record for each community _interpretation_ in the community classification GET endpoint, with redundant top level community classification columns across all interpretations for the same method. Now we aggregate the community interpretation details in a nested field, while also adding a new nested field with potentially multiple classification _contributors_. Clients can control whether to include these fields using the `with_nested` query parameter, and can choose between minimal vs full details about the nested interpretations using the `details` query parameter.
DarianGill
approved these changes
Nov 21, 2025
DarianGill
left a comment
DarianGill
left a comment
There was a problem hiding this comment.
Looks like a good implementation of what we discussed. Thanks!
RWShelton
approved these changes
Nov 21, 2025
Contributor
RWShelton
left a comment
RWShelton
left a comment
There was a problem hiding this comment.
This format is a much better representation of the data, looks great!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
What
This PR changes the community classification GET endpoint to return exactly one record per comm classification record in VegBank, with a new nested field for the (possibly many) community interpretation records associated with this classification event.
It also adds a nested field for classification contributors (not previously returned by this endpoint), of which there can also be many.
Why
The new behavior makes the endpoint consistent with other endpoints, and more predictable. It also disambiguates "classification" vs "interpretation" details ... which in practice are largely intertwined, but there's a reason that these are two tables with a
1:manyrelationship in the VegBank data model!How
Updated the Community Classification operator as follows:
interpretationscolumn with a nested array of community interpretation recordscontributorscolumn with a nested area of classification contributor recordswith_nestedparameter for clients to turn these columnsonandoff(default)detailparameter to control whether the nested interpretation records contain all externally documented columns from the comminterpretation table (detail=full, default), or just a slim subset of columns (detail=minimal); this does not affect other columnsDemo
Note: All requests and responses below are for the same community classification record.
Old behavior -- notice 2 records returned for this classification
$ http GET 'https://api-dev.vegbank.org/community-classifications/cl.71944'{ "count": 2, "data": [ { "cc_code": "cc.45377", "cl_code": "cl.71944", "class_confidence": "High", "class_fit": "Understandable but wrong", "class_notes": null, "class_start_date": "Mon, 05 Jun 2006 07:00:00 GMT", "class_stop_date": null, "comm_authority_rf_code": null, "comm_code": null, "comm_framework": null, "comm_level": null, "comm_name": "Chamaedaphne calyculata / Carex striata - Woodwardia virginica Wet Dwarf-shrubland", "emb_comm_class": 0, "emb_comm_interpretation": 0, "expert_system": "0", "inspection": false, "interpretation_nomenclatural_type": false, "interpretation_notes": null, "interpretation_type": false, "multivariate_analysis": false, "ob_code": "ob.81027", "table_analysis": false }, { "cc_code": "cc.45166", "cl_code": "cl.71944", "class_confidence": "High", "class_fit": "Absolutely correct", "class_notes": null, "class_start_date": "Mon, 05 Jun 2006 07:00:00 GMT", "class_stop_date": null, "comm_authority_rf_code": null, "comm_code": null, "comm_framework": null, "comm_level": null, "comm_name": "Cyrilla racemiflora - Zenobia pulverulenta Wet Shrubland", "emb_comm_class": 0, "emb_comm_interpretation": 0, "expert_system": "0", "inspection": false, "interpretation_nomenclatural_type": false, "interpretation_notes": null, "interpretation_type": false, "multivariate_analysis": false, "ob_code": "ob.81027", "table_analysis": false } ] }New behavior -- no nesting -- just has classification fields
$ http GET 'http://127.0.0.1/community-classifications/cl.71944'{ "count": 1, "data": [ { "cl_code": "cl.71944", "class_notes": null, "class_publication_rf_code": null, "class_publication_rf_label": null, "class_start_date": "Mon, 05 Jun 2006 07:00:00 GMT", "class_stop_date": null, "expert_system": "0", "inspection": false, "multivariate_analysis": false, "ob_code": "ob.81027", "table_analysis": false } ] }New behavior -- nesting with minimal detail
http GET 'http://127.0.0.1/community-classifications/cl.71944?with_nested=true&detail=minimal'{ "count": 1, "data": [ { "cl_code": "cl.71944", "class_notes": null, "class_publication_rf_code": null, "class_publication_rf_label": null, "class_start_date": "Mon, 05 Jun 2006 07:00:00 GMT", "class_stop_date": null, "contributors": [ { "party": "Peet, Robert", "py_code": "py.191310", "role": null }, { "party": "Schafale, Mike", "py_code": "py.191469", "role": null } ], "expert_system": "0", "inspection": false, "interpretations": [ { "cc_code": "cc.45377", "ci_code": "ci.71554", "comm_code": null, "comm_name": "Chamaedaphne calyculata / Carex striata var. striata - Woodwardia virginica Dwarf-shrubland" }, { "cc_code": "cc.45166", "ci_code": "ci.71553", "comm_code": null, "comm_name": "Cyrilla racemiflora - Zenobia pulverulenta Shrubland" } ], "multivariate_analysis": false, "ob_code": "ob.81027", "table_analysis": false } ] }New behavior -- nesting with full detail (default)
http GET 'http://127.0.0.1/community-classifications/cl.71944?with_nested=true'{ "count": 1, "data": [ { "cl_code": "cl.71944", "class_notes": null, "class_publication_rf_code": null, "class_publication_rf_label": null, "class_start_date": "Mon, 05 Jun 2006 07:00:00 GMT", "class_stop_date": null, "contributors": [ { "party": "Peet, Robert", "py_code": "py.191310", "role": null }, { "party": "Schafale, Mike", "py_code": "py.191469", "role": null } ], "expert_system": "0", "inspection": false, "interpretations": [ { "cc_code": "cc.45377", "ci_code": "ci.71554", "class_confidence": "High", "class_fit": "Understandable but wrong", "comm_authority_name": null, "comm_authority_rf_code": null, "comm_code": null, "comm_name": "Chamaedaphne calyculata / Carex striata var. striata - Woodwardia virginica Dwarf-shrubland", "nomenclatural_type": false, "notes": null, "type": false }, { "cc_code": "cc.45166", "ci_code": "ci.71553", "class_confidence": "High", "class_fit": "Absolutely correct", "comm_authority_name": null, "comm_authority_rf_code": null, "comm_code": null, "comm_name": "Cyrilla racemiflora - Zenobia pulverulenta Shrubland", "nomenclatural_type": false, "notes": null, "type": false } ], "multivariate_analysis": false, "ob_code": "ob.81027", "table_analysis": false } ] }