Validation Rules Reference

This page documents every validation rule used by the BS 5930 Soil Description Checker and the AGS Quality Checker.

Rules are grouped by category. Each rule has a code (e.g. GEOL_003), a severity level, and a BS 5930 reference where applicable. Results are advisory - engineering judgment should always take priority.

Severity Levels

BS 5930 Description Rules

These rules validate geological descriptions against BS 5930:2015+A1:2020.

Tier 1: Critical Errors

GEOL_003: Invalid Soil Combination

Severity: Error | BS 5930: S33.4.4.4

Flags two types of invalid soil combinations:

1. Self-referencing modifiers - a soil cannot be modified by a term derived from itself.

2. Inappropriate fine-on-fine subdivisions - when the main soil is fine (CLAY or SILT) and the modifier is also fine, using "slightly" or "very" qualifiers is not appropriate per BS 5930.

GEOL_005: Invalid Density/Consistency

Severity: Error | BS 5930: Tables 8, 10

Wrong strength term type for the soil classification.

• Fine soils (CLAY, SILT) use consistency terms: very soft, soft, firm, stiff, very stiff
• Coarse soils (SAND, GRAVEL) use density terms: very loose, loose, medium dense, dense, very dense

GEOL_013: Fractions Exceed 100%

Severity: Error | BS 5930: S33.4.4.5 NOTE 2

Flags descriptions where implied proportions are mathematically impossible.

GEOL_020: Missing Primary Material Type

Severity: Error | BS 5930: S33.4.4.1

Every geological description must include a primary material in CAPITALS.

Valid primary materials include: CLAY, SILT, SAND, GRAVEL, COBBLES, BOULDERS (soils); SANDSTONE, LIMESTONE, CHALK, MUDSTONE, GRANITE etc. (rocks); CONCRETE, TARMAC, BRICK, MADE GROUND (anthropogenic); PEAT, TOPSOIL (organic).

Tier 2: Warnings

GEOL_001: Legend Code Mismatch

Severity: Warning (wrong primary material) / Info (more specific code available) | BS 5930: S33.5

Validates that the geological description matches the assigned legend code using AGS dictionary mappings. The result depends on what differs:

• Wrong primary material (e.g. a CLAY code on a SAND or SILT description) is a warning - the material itself is misrepresented.
• Correct primary but different secondary modifiers (e.g. a plain CLAY code on a "silty CLAY") is info only - the code is right for the material, just less specific than it could be. The message suggests a more specific code rather than flagging an error.

Note: Only applies to AGS data with legend codes. Not checked in single description mode.

GEOL_002: Incorrect Modifier Order

Severity: Warning | BS 5930: S33.4.4.5

Secondary fractions should be ordered with coarse modifiers before fine modifiers.

Correct order: sandy/gravelly/cobble/boulder then silty/clayey

GEOL_004: Invalid Test for Soil Type

Severity: Warning | BS 5930: Table 33

Pocket penetrometer and hand vane tests are only valid for fine soils.

Only applies to AGS data with IPEN/IVAN tables.

GEOL_007: Consistency on Coarse Soil

Severity: Warning | BS 5930: Tables 8, 10

Consistency terms (soft, firm, stiff) used on SAND or GRAVEL.

GEOL_008: Density on Fine Soil

Severity: Warning | BS 5930: Tables 8, 10

Density terms (loose, dense) used on CLAY or SILT.

GEOL_009: Invalid Consistency Term

Severity: Warning | BS 5930: Table 8

Detects non-standard consistency terms on fine soils.

Valid terms: very soft, soft, firm, stiff, very stiff

GEOL_010: Invalid Density Term

Severity: Warning | BS 5930: Table 10

Detects non-standard density terms on coarse soils.

Valid terms: very loose, loose, medium dense, dense, very dense

GEOL_011: Invalid Coarse Secondary Term

Severity: Warning | BS 5930: Table 16

Cross-references description terms against PSD lab data for coarse soils. Checks whether the quantifier (slightly/unqualified/very) matches the measured proportion.

Only applies to AGS data with GRAG/GRAT lab data.

GEOL_012: Invalid Fine Secondary Term

Severity: Warning | BS 5930: Table 17

Same as GEOL_011 but for fine modifiers (clayey, silty) on coarse soils. Uses total fines content (clay% + silt%) to validate the quantifier.

Only applies to AGS data with GRAG/GRAT lab data.

GEOL_014: Invalid Angularity Term

Severity: Warning | BS 5930: S33.4.3, Figure 7

Valid terms: very angular, angular, subangular, subrounded, rounded, well rounded

GEOL_017: Invalid Discontinuity Spacing

Severity: Warning | BS 5930: Table 7

Cross-references spacing terms with FRAC table measurements.

Only applies to AGS data with FRAC table.

GEOL_022: Invalid Organic Term

Severity: Warning | BS 5930: Table 22

Valid terms: slightly organic, organic, very organic

GEOL_023: Invalid Carbonate Term

Severity: Warning | BS 5930: S33.4.4.6

Valid terms: slightly calcareous, calcareous, highly calcareous

GEOL_024: Invalid Rock Strength Term

Severity: Warning | BS 5930: Table 25

Valid terms: extremely weak, very weak, weak, moderately weak, medium strong, strong, very strong, extremely strong

GEOL_025: Strength/UCS Mismatch

Severity: Warning | BS 5930: Table 25

Cross-references strength terms with UCS lab data.

Only applies to AGS data with RUCS table.

GEOL_028: Invalid Boulder/Cobble Term

Severity: Warning | BS 5930: Tables 12-15

Valid proportion terms: with occasional (<5%), with some (5-20%), with many (20-50%), with low/medium/high content

GEOL_029: Invalid Weathering Grade

Severity: Warning | BS 5930: Figure 9

Valid terms: fresh, slightly weathered, moderately weathered, highly weathered, completely weathered, residual soil

GEOL_031: Made Ground Indicators

Severity: Warning | BS 5930: S33.7

Flags descriptions containing anthropogenic materials (brick, concrete, tarmac, glass, metal, slag, ash, etc.) when the legend code does not indicate made ground.

Tier 3: Info (Best Practice)

GEOL_006: Missing Angularity

Severity: Info | BS 5930: S33.4.3

GRAVEL, COBBLES, or BOULDERS described without an angularity term.

GEOL_015: Angularity on Fine Soil

Severity: Info | BS 5930: S33.4.3

Angularity terms used on CLAY or SILT (only applicable to gravel and coarser).

GEOL_018: Invalid Colour Hue

Severity: Info | BS 5930: Table 7

Valid hues: red, pink, orange, yellow, cream, brown, green, blue, white, grey, black. Valid prefixes: light, dark, reddish, yellowish, brownish, etc.

GEOL_019: Missing Colour

Severity: Info

Description does not contain any colour term.

GEOL_021: Multiple Primary Types

Severity: Info | BS 5930: S33.4.4.1

Flags two or more non-adjacent primary soil types in CAPITALS that would usually be better written as one principal soil with the others as modifiers (e.g. "CLAY and GRAVEL" -> "gravelly CLAY").

Acceptable composites of adjacent size fractions are not flagged - "SAND and GRAVEL", "GRAVEL, COBBLES and BOULDERS", "CLAY/SILT" are all valid. The rule also ignores soil words that are not the primary: recovered rock fragments ("MUDSTONE excavated as GRAVEL and COBBLES of mudstone") and subordinate inclusions ("SAND with occasional pockets of CLAY", "very gravelly SAND with BOULDERS").

GEOL_027: Invalid Structure for Rock

Severity: Info | BS 5930: Table 27

Bedding terms used on igneous or metamorphic rocks (GRANITE, BASALT, GNEISS, etc.) which do not have bedding.

GEOL_030: Test on Layer Boundary

Severity: Info

Pocket penetrometer or vane test recorded exactly at a geological boundary, making it ambiguous which layer is being tested.

Anthropogenic Materials Rules

These rules check descriptions of made ground (anthropogenic material). They are derived from the AGS guidance note Description of Anthropogenic Materials - A Practitioners' Guide (AGS, 2018). ANTH_001 and ANTH_004 assert something about made ground specifically, so they only fire where the stratum is in a made-ground context and never on natural soils. The two terminology checks, ANTH_002 ("cinders") and ANTH_003 (vague odour), apply to any description - an unhelpful term or an unspecific odour is worth recording properly wherever it appears. Like all rules here, they are advisory - engineering judgment always takes priority.

ANTH_001: Made Ground Described as Peat

Severity: Warning | AGS Anthropogenic Materials (2018): Class 3

Organic made ground should not be described as "peat" or "peaty", to avoid confusion with natural organic deposits - describe it as soft/firm/spongy/plastic organic material instead. Only fires in a made-ground context (a MADE GROUND: classification, legend code 102, or anthropogenic inclusions), so natural PEAT is not flagged.

ANTH_002: Cinders Term Discouraged

Severity: Info | AGS Anthropogenic Materials (2018): S1.2

The term "cinders" is considered unhelpful - describe the composition and size of the part-burnt particles instead, e.g. "fine gravel of part-burnt coal". Applies to any description, not only made ground.

ANTH_003: Odour Without Specific Descriptor

Severity: Info | AGS Anthropogenic Materials (2018): S1.4

An odour is mentioned but no specific type is recorded. A bare "hydrocarbon odour" cannot distinguish, for example, fuel from coal tar or chlorinated solvents. Record a recognised odour type (H2S, mercaptan, naphthalene, solvent, chlorinated solvent, acetic, fuel, mineral oil, creosote/coal tar, putrid, or "organic odour") and its strength (weak/distinct/strong/very strong). "No odour" phrasing is skipped. Applies to any description, not only made ground - contamination is not confined to made ground.

ANTH_004: Possible Reducing Conditions (Colour)

Severity: Info | AGS Anthropogenic Materials (2018): S1.3

Bluish or greenish-grey colouration in made ground indicates iron reduced to the ferrous state - often a sign of reducing conditions from degrading organic or hydrocarbon contamination. Fires only where the reduced grey tone appears alongside a contamination co-signal (odour, staining, organics, or a fuel/tar/solvent term), because bluish/greenish grey is also the natural colour of many unweathered clays. Matches the reduced grey tones only, not bare blue/green material colours (e.g. blue plastic, green glass).

Attribution

The Made Ground checks are derived from AGS Description of Anthropogenic Materials - A Practitioners' Guide (Association of Geotechnical and Geoenvironmental Specialists, 2018), authored by the AGS working party - co-author Chris Swainston.

GIMLabs has implemented a selected subset of the guide's recommendations as automated, advisory description checks. The checks are our interpretation of the guidance for software use; they are not exhaustive, are not a substitute for the guide itself or for professional judgment, and are not endorsed by the AGS unless and until the AGS confirms otherwise. The guidance remains the copyright of the AGS. We are grateful to the authors and the AGS for making the guidance available, and we would welcome the AGS's review of how it has been applied here.

Depth Validation Rules

These rules check for issues with depth values in geotechnical data. Only applies to AGS data.

DEPTH_001: Overlapping Geology Depths

Severity: Error

Two geology records at the same location have depth ranges that overlap.

DEPTH_002: Depth Top Greater Than Base

Severity: Error

A record's top depth is greater than or equal to its base depth.

DEPTH_003: Record Exceeds Final Depth

Severity: Error

A depth-based record extends deeper than the location's recorded final depth (LOCA_FDEP).

DEPTH_004: Backfill Does Not Match Final Depth

Severity: Warning

Deepest backfill record doesn't reach the location's final depth (potential void). Tolerance: 10cm.

DEPTH_005: Geology Does Not Reach Final Depth

Severity: Warning

Geology descriptions don't extend to the location's final depth (missing stratigraphy). Tolerance: 10cm.

DEPTH_006: Gaps in Geology

Severity: Warning

Missing depth ranges between consecutive geology records within a location.

DEPTH_007: SPT Penetration Exceeds Final Depth

Severity: Error

SPT test depth plus penetration (ISPT_TOP + ISPT_NPEN/1000) exceeds the location's final depth.

Spatial Validation Rules

These rules check for issues with location coordinates. Only applies to AGS data.

SPATIAL_001: Missing Coordinates

Severity: Warning

Location has no coordinate data (no easting/northing or latitude/longitude).

SPATIAL_002: Duplicate Location Coordinates

Severity: Warning

Multiple locations share the same coordinates (within 10cm precision). Usually indicates a data entry or copy/paste error.

Date Validation Rules

These rules check for issues with date values. Only applies to AGS data.

DATE_001: End Date Before Start Date

Severity: Error

Location's end date (LOCA_ENDD) is earlier than its start date (LOCA_STAR). Compared by calendar day, so a hole started and finished on the same day is valid.

DATE_002: Future Dates

Severity: Warning

Start or end date is in the future, which usually indicates a data entry error.

Data Quality Rules

These rules check for data consistency issues. Only applies to AGS data.

DATA_001: Suspicious Values

Severity: Warning

Values that appear to be placeholders or errors: null island coordinates (0,0), zero easting/northing, placeholder depths (9999, -999), or unusually deep values (>500m).

DATA_002: Inconsistent Units

Severity: Warning

Depth values that appear to be in millimetres where metres were expected. Detected when average depth > 100 and maximum > 1000.

DATA_003: Spelling Errors

Severity: Warning

Text fields contain possible spelling mistakes. Uses a British English dictionary augmented with 200+ geological and geotechnical terms.

DATA_004: Invisible Characters

Severity: Warning

Text starts or ends with a space, or contains a line break or tab. The trailing space is the costly one: LONDON CLAY and LONDON CLAY group, chart and export as two different strata. Line breaks and tabs additionally break AGS output and PDF layout.

DATA_005: Double Spaces

Severity: Info

Two or more spaces between words. Presentational rather than wrong, but it reads as sloppy on an issued log and often marks text that was assembled or pasted rather than typed.

DATA_006: Space Before Punctuation

Severity: Info

A space before a comma, full stop or semicolon. The colon is deliberately excluded, because a spaced colon is normal in standards citations such as BS EN ISO 22476-3 : 2005.

DATA_007: Doubled Punctuation

Severity: Info

A repeated comma, semicolon or colon, or exactly two full stops. Three or more dots are left alone on purpose: an ellipsis is used deliberately in stratum detail descriptions to mark text continuing from the layer above.

DATA_008: Repeated Words

Severity: Info

The same word twice in a row, such as slightly slightly gravelly. Rare, but almost always a genuine slip.

DATA_009: Joined Words

Severity: Info

Two words run together with the space lost, such as rarefine for rare fine. Found by splitting words the dictionary rejects into two it accepts, so it uses the same dictionary as DATA_003 and takes precedence over it, keeping one defect to one finding.

Shift Rules

These rules check driller shift records: that each shift describes a real period of time, that shifts do not collide, and that logged entries fall inside the shift they belong to. Only applies to configurations using shift-based logging.

SHIFT_001: End of Shift Before Start

Severity: Error

A shift's recorded end is earlier than its recorded start, so the shift describes negative time.

SHIFT_002: Shift Start or End Missing

Severity: Warning

A shift is missing its start or end date and time, so entries cannot be reliably assigned to it.

SHIFT_003: Overlapping Shifts

Severity: Error

Two shifts on the same location claim the same period, leaving entries in that window ambiguous.

SHIFT_004: Entry Outside the Shift Window

Severity: Warning

An entry is logged more than 30 minutes outside its shift's recorded hours.

SHIFT_005: Duplicate Shift Start Times

Severity: Warning

Two shifts on the same location start at the same date and time.

SHIFT_006: Shift Depth Not Continuous

Severity: Warning

A shift's start depth differs from the previous shift's end depth, implying an unrecorded gap or overlap.

SHIFT_007: Implausible Shift Duration

Severity: Error

A shift is recorded as lasting less than 5 minutes or more than 24 hours.

SHIFT_008: Shift Identifier Out of Sequence

Severity: Warning

Shift identifiers do not run in the same order as the shift dates.

SHIFT_009: Entry Missing Its Date

Severity: Warning

A time-indexed entry has no date, so it will not appear under any shift.

Completeness Rules

COMPLETE_001: Missing Required Fields

Severity: Error

Required fields (AGS KEY fields) have empty values. Only applies to AGS data.

Relationship Rules

KEY_001: Duplicate Key Fields

Severity: Error

Multiple records in the same table have identical key field values within a single location. Usually indicates duplicate data entry or copy/paste errors. Records whose key fields are entirely empty are not counted here - that is a completeness issue (see COMPLETE_001), not a duplicate.