Canonical data model¶
The first canonical model centers on a soil observation while retaining structures needed for profiles, horizons, methods, locations, and sources.
Soil observation¶
A property value tied to unit, depth, data kind, method, source, location, uncertainty, license, transformations, warnings, and provider-specific context. One response can contain several observations for components and horizons at the same query point.
Soil profile and horizon¶
A profile is a vertical sequence at a described location. A horizon is a layer with top and bottom boundaries and related observations. SSURGO map-unit components include representative horizons; they are not sampled profiles at the query coordinate.
Soil property¶
A canonical concept such as ph, clay, or bulk_density. It has a display name, standard unit, aliases, conversion notes, method warning, and support status. The original provider column is always retained with an observation.
Measurement method¶
The preparation, extraction, instrument, model, or survey procedure that gives a value meaning. It can be null when the provider response does not identify one. Missing method metadata limits comparison.
Depth interval¶
Two numeric centimeter boundaries: top_cm and bottom_cm. The API queries horizons that overlap the requested interval; it does not clip, average, or interpolate them.
Location¶
WGS84 latitude and longitude echoed from the query plus horizontal accuracy when known. For mapped survey records, this is the lookup point, not the location of a laboratory observation.
Source, citation, and license¶
Source records identify provider, organization, provider record key, retrieval timestamp, original value fields, citation, URL, and spatial resolution. License name and URL remain nullable until verified for the specific provider and product. A null license does not mean unrestricted use.
Transformation¶
An ordered record of an operation, original unit, resulting unit, and formula. Identity mappings have no transformation. The first release approves only explicit mass-fraction conversion between g/kg and percent; it does not use that rule in the USDA SDA adapter because SDA values are already returned in target units.
Uncertainty and warning¶
Numeric lower/upper uncertainty and method are returned when available. Warnings carry scientific and operational limitations that cannot be represented as numeric uncertainty.
Data-kind enum¶
observed, modeled, mapped_survey, derived, and user_supplied remain distinct throughout normalization.