docs: document gps_device_capture for FLCRM-20930 - #86
Open
sjperaltas wants to merge 2 commits into
Open
Conversation
Add Records, Query, Data Events, and OpenAPI examples for GPS device capture. OpenSpec change lives in openspec/changes/document-gps-device-capture. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Documents gps_device_capture end-to-end across Records API v2, Query API, and Data Events, and adds OpenAPI examples to help integrators map and query external GPS receiver metadata (FLCRM-20930).
Changes:
- Adds
gps_device_captureto Records API docs (properties + create/update/PATCH examples) and OpenAPI example payloads. - Documents Query API
_gps_device_capture(jsonb) with JSON operator examples (->>and@>). - Updates Data Events
change-geometrydocs to mentionevent.valueGeoJSON and optionalevent.gpsData.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| reference/rest-api.json | Adds request/response examples that include gps_device_capture. |
| reference/RECORDS/records-intro.md | Documents gps_device_capture in the record properties table and adds an example. |
| reference/RECORDS/records-create.md | Adds gps_device_capture to create examples across languages. |
| reference/RECORDS/records-update.md | Adds gps_device_capture to update examples across languages. |
| reference/RECORDS/records-partial-update.md | Adds a PATCH example and notes about clearing via null. |
| reference/QUERY/query-intro.md | Adds _gps_device_capture column doc + SQL JSONB query examples. |
| docs/DATA EVENTS/data-events-reference/index.md | Expands change-geometry docs and includes an example event payload with optional gpsData. |
| docs/DATA EVENTS/data-events-reference/data-events-on.md | Updates change-geometry callback docs to describe event.value and optional event.gpsData. |
| openspec/changes/document-gps-device-capture/* | Adds OpenSpec proposal/design/spec + task checklist for the doc change. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| "With GPS device capture": { | ||
| "value": { | ||
| "record": { | ||
| "form_id": "aa9816b6-ebec-4f14-88df-7v5844c2237d", |
Contributor
Author
There was a problem hiding this comment.
Replaced the invalid form_id aa9816b6-ebec-4f14-88df-7v5844c2237d with aa9816b6-ebec-4f14-88df-775844c2237d in all OpenAPI examples.
| } | ||
| ``` | ||
|
|
||
| A `change-geometry` event uses `value` for the GeoJSON geometry. When external GPS metadata is available, `gpsData` is a top-level sibling of `value`. Keys inside `gpsData` vary by device and client. |
Contributor
Author
There was a problem hiding this comment.
Labeled the JSON as an illustrative example, not a canonical schema, and added a placeholder key so gpsData is not read as a closed key list.
| | horizontal\_accuracy | number | no | yes | Accuracy of the latitude and longitude in meters. | | ||
| | vertical\_accuracy | number | no | yes | Accuracy of the altitude value in meters. | | ||
| | geometry | GeoJSON | no | no | Point, LineString or Polygon of the record. [See below](https://docs.fulcrumapp.com/reference/records-intro#using-the-new-geometry-field) | | ||
| | gps\_device\_capture | object | no | no | Flexible GPS receiver metadata captured with the record. Common keys include `device_name`, `manufacturer`, `fix_type`, `satellite_count`, `hdop`, `vdop`, `pdop`, and `geometry` (GeoJSON). Additional device-specific keys are allowed. Send `null` on create/update to clear the value. | |
Contributor
Author
There was a problem hiding this comment.
Updated the properties table to say send null on write (create/update/PATCH).
Align example coordinates, fix invalid form_id UUID, clarify null-on-write, label gpsData as illustrative, and guard satellite_count SQL casts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Comment on lines
+61
to
+67
| "gpsData": { | ||
| "deviceName": "Trimble R2", | ||
| "fixType": "RTK", | ||
| "satellites": 14, | ||
| "hdop": 0.8, | ||
| "...": "additional device-specific keys" | ||
| } |
| @@ -89,6 +89,26 @@ See the examples below for valid and invalid usages of this endpoint. | |||
| } | |||
| ``` | |||
|
|
|||
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
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?
gps_device_captureon Records API v2 (properties table plus create/update/PATCH examples)_gps_device_captureJSONB filters (->>and@>)change-geometryoptionalevent.gpsDataand point integrators to persistedgps_device_captureWhy?
change-geometrynow includes event data that was undocumentedTesting
cypress:repeatinpackage.jsonwith your spec name, then run./utils/run-against {namespace} repeat.fulcrumapp/api; no Cypress specs were added or changed.reference/, runnpx --yes rdme openapi validate rest-api.json.reference/rest-api.jsonparses as JSON and has noRAW_BODYkeys.gps_device_captureis in the properties table, including thatnullclears the value.gps_device_capturepayload with nested GeoJSONgeometry._gps_device_captureJSONB examples: filter bydevice_namewith->>and byfix_typewith@>.change-geometry/ONdocs and confirmevent.valueis GeoJSON andevent.gpsDatais optional (keys may differ by platform).geometry_matches_capture.change-geometry, and ReadMe rendering ofrest-api.jsonexamples.