About This Application

Digital Keys to Soil Taxonomy is an interactive, offline-first Progressive Web App for USDA soil classification following the Keys to Soil Taxonomy (13th Edition, 2022).

The application guides you through the official USDA dichotomous key by progressively revealing classification criteria. Check the criteria that match your soil properties, and the app determines the taxonomic classification: Order → Suborder → Great Group → Subgroup.

No internet connection is required after the first visit. The entire application — code, data, and glossary — is cached locally by the Service Worker.

Data Summary

This dataset includes decision criteria organized across the USDA soil taxonomy hierarchy:

The glossary includes soil taxonomy terms — diagnostic quantities, features, properties, and related concepts used in the taxonomic system.

JSON Data Schema v1.0.0

The application is powered by data/dst-data.json, a ~3.5 MB file generated from USDA source data. The file contains five top-level sections:

Section	Description
navigation.criteria	Array of decision criteria with clause hierarchy, AND/OR logic, and pre-linkified glossary terms
outcomes	Object keyed by taxonomic code — each is a classification result (depth -1)
glossary	Object keyed by term ID — soil science terms with definitions
order_names	Single-letter code → Order name (e.g., A → Gelisols)
code_names	Full code → taxon name at all levels (e.g., AA → Histels)

Criterion Fields

Field	Type	Description
crit	string	Hierarchical code (A–L Orders, AA–LL Suborders, AAA+ deeper)
clause	number	Numeric clause ID within the group
parent_clause	number|""	Parent clause reference (empty for roots)
logic	string	OR or AND — how this node's children relate
depth	number	0=Order, 1=Suborder, 2=Great Group, 3=Subgroup
content	string	Plain text criterion description
content_html	string	Content with glossary terms pre-linkified

DSTCore Engine

scripts/dst-core.js is a standalone, framework-agnostic logic engine with no DOM dependencies. It works identically in the browser (window.DSTCore) and Node.js (require()).

Satisfaction Algorithm

Each parent criterion's logic field determines how its children are evaluated:

• AND — ALL children must be satisfied
• OR — at least ONE child must be satisfied
• Leaf nodes (no children) — satisfied when checked by the user

Evaluation is recursive with per-mutation cache invalidation.

Key API Methods

Method	Returns	Description
DSTCore.create(data)	engine	Create engine instance from parsed JSON
engine.check(id)	—	Check a criterion (auto-invalidates caches)
engine.toggle(id)	—	Toggle check state
engine.reset()	—	Clear all checks
engine.isClauseSatisfied(c)	boolean	Recursive satisfaction check (cached)
engine.isGroupSatisfied(code)	boolean	Is an entire taxonomic group satisfied?
engine.getVisibleGroups()	array	Groups to display at current level
engine.getClassificationPath()	array	Current taxonomy path (Order → Subgroup)
engine.getCurrentClassification()	string	Name of deepest satisfied taxon
engine.onChange(fn)	unsubscribe	Register state change listener

Technology Stack

Frontend: Alpine.js v3.13.3 (loaded via CDN), CSS with custom properties for light/dark theming

Engine: Standalone JavaScript logic engine (scripts/dst-core.js) with no dependencies. Works identically in browser and Node.js.

Data: Python preprocessing pipeline generates optimized JSON from USDA source files. Service Worker enables offline-first caching.

Testing: Custom test harness with Node.js and browser execution modes.

Resources

• Soil Knowledge Base — Official NCSS taxonomy data repository
• USDA Keys to Soil Taxonomy — Official classification guide

Source & License

• Code: MIT License
• Taxonomy Data: Derived from USDA Keys to Soil Taxonomy — public domain
• USDA Source: nrcs.usda.gov
• Source Data: SoilKnowledgeBase (GitHub)