Strabospot Interchange Model

[amyfromandi]

Spots ↔ FieldSites ↔ Checkins Conversion API

code changes can be view in this PR #251

Base URL: http://dev.macrostrat.org/api/v3/dev

Endpoint: POST /convert/field-site?in=<spot|fieldsite|checkin>&out=<spot|fieldsite|checkin>

---

Purpose

• This endpoint converts payloads between StraboSpot, FieldSite, and Rockd Checkin formats.
• Conversions are selected using the in and out query params.

---

Supported Conversions

• in=spot&out=fieldsite returns list[FieldSite].
• in=spot&out=checkin returns list[checkin].
• in=fieldsite&out=checkin returns list[checkin].
• in=fieldsite&out=spot returns a GeoJSON FeatureCollection.
• in=checkin&out=fieldsite returns list[FieldSite].
• in=checkin&out=spot returns a GeoJSON FeatureCollection.
• Any other in/out pair returns 400 with a string detail.
• Unsupported conversions return 400 with detail as a string.
• Successful conversions may return an empty list (for example, if all Spot features are skipped).
• Invalid items inside a list are silently skipped rather than returning an error.

---

Input Shapes

• Spot input may be a FeatureCollection, a single Feature, or a list of FeatureCollection|Feature.
• Checkin input may be a single dict or a list of dicts.
• FieldSite input may be a single FieldSite dictionaries or a list of FieldSite dictionaries.

---

Spot → FieldSite (in=spot&out=fieldsite)

• Only GeoJSON features with geometry.type == "Point" are converted.
• Any feature with properties.image_basemap (image-annotation points) is skipped.
• Any feature missing properties.id is skipped.
• Any feature with invalid coordinates is skipped.
• Coordinates use properties.lat/lng if present, otherwise they are read from geometry.coordinates as [lng, lat].
• created is parsed from properties.time or properties.date, otherwise it defaults to “now” in UTC.
• updated is parsed from properties.modified_timestamp (milliseconds), otherwise it falls back to created.
• notes comes from properties.notes.
• If properties.images exists, only the first image is mapped to photos[0] as rockd://photo/<id>.
• If properties.orientation_data contains a planar orientation, only the first valid {strike, dip} is mapped to observations[0].data.
• The planar facing is always set to "upright".

---

Spot → Checkin (in=spot&out=checkin)

• This path uses Spot → FieldSite → Checkin.
• If the payload is already a converted FieldSite, it skips Spot parsing and converts directly to checkins.
• fieldsite.location assumes there is only one fieldsite object in the request. fieldsite[i].location assumes there are i fieldsite objects in the request body.

---

FieldSite → Checkin (in=fieldsite&out=checkin)

• If the request body is a list, the response is a list of checkins.
• If the request body is a single dict, the response is a list of one checkin.
• Each output checkin includes both checkin_id and spot_id, and both are set to FieldSite.id.
• lat/lng are taken from FieldSite.location.latitude/longitude.
• created and added are formatted as strings like "October 19, 2023".
• If photos exists, only photos[0].id is mapped to photo.
• If a planar observation exists, only the first planar is mapped to observations = [{"orientation": {"strike": ..., "dip": ...}}].
• If no planar exists, observations is an empty list.

---

FieldSite → Spot (in=fieldsite&out=spot)

• The response is always a GeoJSON FeatureCollection.
• A single FieldSite input returns a FeatureCollection with one Feature.
• A list of FieldSites returns a FeatureCollection with one Feature per FieldSite.
• Each feature is a Point with coordinates [longitude, latitude].
• properties.id is set to FieldSite.id.
• properties.time and properties.date are emitted as ISO strings ending in Z.
• properties.modified_timestamp is emitted in milliseconds from updated.
• properties.lat/lng are also included.
• If photos exists, only the first photo is mapped into properties.images[0].
• If a planar observation exists, only the first planar is mapped into properties.orientation_data[0].

---

Checkin → FieldSite (in=checkin&out=fieldsite)

• A single checkin dict returns a list of one FieldSite.
• A list of checkins returns a list of FieldSites.
• FieldSite.id is set from checkin.checkin_id.
• Location is set from checkin.lat and checkin.lng.
• created is parsed from checkin.created and accepts ISO strings or "Month DD, YYYY", otherwise it defaults to “now” in UTC.
• updated is parsed from checkin.added, otherwise it falls back to created.
• notes comes from checkin.notes.
• If photo is an int, it becomes photos[0] with a rockd://photo/<id> URL.
• If observations contains an orientation with numeric strike/dip, only the first valid one becomes [observations[0].data.]
• The planar facing is always set to "upright".

---

Checkin → Spot (in=checkin&out=spot)

• This path uses Checkin → FieldSite → Spot.
• If one checkin is provided, the output FeatureCollection contains one feature.
• If multiple checkins are provided, the output FeatureCollection contains multiple features, matching the Strabospot data structure.

[amyfromandi]

Next steps!

TODO

• Include all images instead of only the first image. Map image data structures according to the separate Strabospot and Rockd api''s.

  • Spot → FieldSite
  • FieldSite → Checkin
  • FieldSite → Spot
  • Checkin → FieldSite

• Include all planar strike/dip observations instead of only the first planar in:

  • Spot → FieldSite
  • FieldSite → Checkin
  • FieldSite → Spot
  • Checkin → FieldSite

• Ensure single object inputs return single object outputs consistently across all conversions.

• Ensure multiple object inputs return multiple object outputs consistently across all conversions.

• Ensure a separate spot_id and checkin_id generation so that spot_id comes from FieldSite.id and checkin_id is generated by the checkin creation (to be developed) route.

  • FieldSite → Checkin
  • Checkin → FieldSite

[amyfromandi]

Created an /protected/interchange-checkin route modelled off of the POST /protected/checkin rockd api route (create-edit-checkin.ts). We can integrate these routes into one in the future.

Next, I'm creating a Postman collection test using pre-scripts and post-scripts to simulate the entire workflow:

• Authenticate a Strabospot account with a Rockd account.
  • This will share jwt's and store them across both systems.
• Create a spot in Strabospot
  • This spot is tied to a test dataset and test project.
• Convert the spot to a Fieldsite
  • There will be post-script verification that the output is correct or not.
• Convert the Fieldsite to a checkin
  • There will be a post-script verification that this checkin response is correct or not.
• Post the checkin to the new /protected/interchange-checkin route in Rockd
  • I will have a local test to check whether all valid fields of the checkin are uploaded into the database.
• Post all relevant images to the /protected/photo route in Rockd.
  • TODO

[amyfromandi]

• Updated planar-orientation extraction to collect all valid planar measurements (strike/dip) instead of only the first one:

  • Renamed helpers: _first_planar_from_spot/checkin/fieldsite → _all_planars_from_spot/checkin/fieldsite
  • Return type changed from Optional[PlanarOrientation] to list[PlanarOrientation] (returns [] when none)

• Updated conversions to preserve multiple planar observations end-to-end:

  • spot_to_fieldsite: builds observations from all planars in properties.orientation_data
  • checkin_to_fieldsite: builds observations from all planars in checkin["observations"]
  • fieldsite_to_rockd_checkin: outputs observations list for every planar in FieldSite.observations (no longer single-item)
  • fieldsite_to_spot: outputs properties.orientation_data list for every planar in FieldSite.observations (no longer single-item)