Skip to content

ADR 004 — NCSS Lab Data Mart through fixed SDA laboratory queries

  • Status: accepted
  • Date: 2026-08-02

Context

OpenSoil needs observed measurements that are scientifically distinct from SSURGO's representative mapped attributes. USDA publishes NCSS Soil Characterization laboratory tables through Soil Data Access and distributes whole-database SQLite/GeoPackage files. Companion morphological pedon data are a separate distribution and are not available through the SDA lab-table interface.

The provider exposes many method-specific fields, incomplete analytical suites, coordinates of varying accuracy, and sometimes censored reported values. A “nearest pedon” abstraction would invite users to misrepresent a sampled point as a field measurement.

Decision

Add ncss_lab_data_mart as an experimental provider using server-authored, fixed-shape SDA queries. Expose:

  • a bounded GeoJSON pedon search with an explicit result limit and truncation flag;
  • a pedon-key detail endpoint for overlapping sampled layers and allowlisted properties;
  • a raw detail route that uses the identical cached upstream query;
  • method codes, original reported strings, depths, provider keys, citations, and warnings;
  • explicit less-than/greater-than qualifiers with null canonical values and separate reporting limits.

Do not expose caller SQL, silently join companion morphology, claim numeric coordinate accuracy, select a “nearest representative” pedon, convert methods, or encode an unverified dataset license.

Consequences

Developers can build bounded D3 point maps and inspect observed horizon measurements. The API now contains two adapter families—mapped location and laboratory pedon—because forcing both through one point-location response would erase scientific differences.

The application still needs no database credentials: bounded SDA requests use the existing timestamped cache. National extraction, durable spatial indexes, companion morphology, and larger map services remain separate future decisions.