Boring Log Viewer docs

Data format reference

How the data is formatted, which fields are required, which are optional, and what fields are allowed.

A boring log's data is stored as one JSON object. Only layers is required; all other fields are optional. The fields are defined below (the notes on the right aren't part of the JSON):

{
  "schema_version": "1.0",    version of the format (optional; the latest, 1.0, if left out)
  "units":       { ... },     how the numbers are measured
  "metadata":    { ... },     the header: project, boring name, location, drilling...
  "layers":      [ ... ],     strata, top to bottom (required)
  "samples":     [ ... ],     samples and blow counts, each with its lab specimens
  "groundwater": [ ... ],     water level readings
  "depth_notes": [ ... ],     observations at a single depth
  "references":  [ ... ],     where the data came from
  "patterns":    { ... },     your own hatches and sampler symbols
  "layout":      { ... }      the log's columns, widths and headings
}

A complete example: full-example.json. A more complete definition is the JSON Schema, which many editors can use to check your file as you type.

General rules

units

units gives the units the numbers in your data are in. Each is optional; metric is the default. You can display the log in other units using the Display options functionality rather than changing the data and the units the data are in.

FieldValuesDefaultApplies to
length"m", "ft""m"All depths, elevation
unit_weight"kN/m3", "pcf""kN/m3"Total and dry unit weight
diameter"mm", "cm", "m", "in", "ft""mm"Borehole and sampler diameters
"units": { "length": "ft", "unit_weight": "pcf", "diameter": "in" }

metadata

Information shown in the header. All fields are optional; dates and names are free text.

FieldMeaningExample
boring_nameBoring ID, used as the title"B-3"
projectProject name"Harbor Terminal Wharf"
site_nameSite"Berth 12"
latitude, longitudeDecimal degrees (west longitudes are negative)33.74215, -118.26541
elevationGround surface elevation, in the length unit. Adds an elevation column.3.2
datumElevation datum"NAVD88"
start_date, end_dateDrilling dates"2019-06-11"
boring_typeDrilling method"Hollow-stem auger"
rigDrill rig"CME-75"
diameterBorehole diameter, in the diameter unit102
hammerHammer type and weight"Automatic trip, 63.5 kg"
energy_ratioHammer energy ratio, percent82
logged_byLogger"J. Doe"
drillerDrilling contractor"ABC Drilling"
notesAny other notes"Hole backfilled with grout"

layers

The strata, one object per layer. At least one layer is required.

FieldMeaningExample
top, bottomRequired. Depths of the layer's top and bottom4.5, 6.0
descriptionMaterial description, as it should appear on the log"Gray, soft, wet, lean CLAY with sand"
uscsUSCS group symbol, an ASTM D2487 dual symbol (with -), or a borderline symbol (with /). It's checked against the description; see checking recorded symbols"CL", "SP-SM", "CL/CH"
hatchThe graphic log symbol, if you want to choose it: a USCS symbol, a material or rock code, a pair of them, a code from patterns, or "none" for blank"FILL", "SANDSTONE", "SP-FILL"
"layers": [
  { "top": 0,   "bottom": 1.2, "description": "Brown silty SAND (FILL)" },
  { "top": 1.2, "bottom": 4.5, "description": "Gray, soft, wet, lean CLAY", "uscs": "CL" },
  { "top": 4.5, "bottom": 9.0, "description": "SANDSTONE, weathered", "hatch": "SANDSTONE" }
]

The USCS symbols are GW, GP, GM, GC, SW, SP, SM, SC, ML, CL, OL, MH, CH, OH and PT. A value that isn't a possible symbol but contains one, such as GP-GW or SM-G (common in older logs), is accepted with a warning; one with no real symbol in it, such as XX, is an error. The material and rock codes, and how the symbol is chosen when you don't give one, are in Graphic log and soil symbols.

samples

Samples, with their blow counts and the laboratory specimens cut from them. Details and examples: Samples, specimens and tests.

FieldMeaningUnits
top, bottomRequired. Depth interval sampled (for an SPT, the 18 in / 0.45 m drive)length
nameSample nametext, e.g. "S-1"
typeSampler type. Used to pick sampler symbol. See sampler types. Default "Other""SPT", "Shelby", ...
blow_countBlow count as reported: a number, or text for refusal14, "50/5in"
blowsBlows for each increment[6, 8, 10]
energy_ratioHammer energy ratio for this sample, if different from the header%
sampler_diameterSampler outside diameterdiameter
recovery_percentRecovery: the recovered length as a percent of the sample interval; 0 means no recovery. Shown as a note in the remarks%
total_unit_weight, dry_unit_weightUnit weights of the whole sample, for example a tube weighed before it is extruded. Shown level with the sample. Results on specimens go in specimensunit_weight
remarksNotes about the sampletext
specimensThe specimens cut from the sample for laboratory tests, with their results (below)list
uscsUSCS symbol of the sample (kept with the data; not drawn)"SM"
customValues for your own columns, e.g. { "pocket_pen": 1.5 }; see custom columnsas you choose

specimens (in a sample)

Each specimen has its own depth range and results. All fields are optional.

FieldMeaningUnits
nameSpecimen referencetext
top, bottomDepth range of the specimen. Without top, its results are shown level with the sample, with no boxlength
water_contentWater (moisture) content%
total_unit_weightTotal (bulk) unit weightunit_weight
dry_unit_weightDry unit weightunit_weight
specific_gravitySpecific gravity of solids, Gs–
fines_contentPercent passing the No. 200 (75 µm) sieve%
liquid_limit, plastic_limitAtterberg limits%
nonplastictrue for a non-plastic specimen: "NP" in both limit columnstrue/false
uscsUSCS symbol from the laboratory classification of the specimen (its limits and sieve analysis). Shown in the Lab USCS column"CL"
remarksNotes about the specimentext
customValues for your own specimen columns, e.g. { "cu": 45 }as you choose
"samples": [
  { "top": 2.5, "bottom": 4, "name": "S-1", "type": "SPT", "blows": [3, 4, 4], "blow_count": 8,
    "specimens": [ { "name": "S-1a", "top": 2.5, "bottom": 4, "water_content": 14.2, "fines_content": 31 } ] },
  { "top": 12.5, "bottom": 14.5, "name": "T-3", "type": "Shelby", "recovery_percent": 90,
    "specimens": [
      { "name": "T-3a", "top": 12.6, "bottom": 13.1, "water_content": 36.5, "liquid_limit": 44, "plastic_limit": 21 },
      { "name": "T-3b", "top": 13.6, "bottom": 14.1, "water_content": 35.2, "dry_unit_weight": 84.2 }
    ] }
]
Older data

Laboratory results written on the sample itself (water_content, liquid_limit and so on), and a sample description, are still accepted with a warning (unit weights are fine on a sample, without a warning). A recovery given as a length, as in earlier versions, is converted to recovery_percent, with a warning. See results on the sample.

groundwater

Water level readings. Only depth is required. Each reading is drawn as ▽ in the water level column; its date and note are listed in the legend, not beside the symbol.

FieldMeaningExample
depthDepth to water6.5
dateWhen it was measured"2021-03-02"
noteCircumstances"encountered during drilling", "stabilized"
"groundwater": [
  { "depth": 6.5, "date": "2021-03-02", "note": "encountered" },
  { "depth": 5.0, "date": "2021-03-05", "note": "stabilized" }
]

depth_notes

Observations at a single depth within a layer, such as a thin lens, a change in color, or "trace gravel". They're drawn in italics under the layer's description, with a tick at their depth. Both fields are required.

"depth_notes": [
  { "depth": 7.6, "description": "thin clayey sand lens" }
]

references

Where the data came from: the report, paper or database. Listed in the header. text is required. Only an address in url becomes a link (clickable in an SVG; http and https addresses only). It's printed after the text unless the text already contains it. An address typed in text alone is shown as plain text, not linked.

"references": [
  { "text": "Example Geotechnical Consultants (2019). Geotechnical investigation report.",
    "url": "https://example.com/report.pdf" },
  { "text": "Personal communication, J. Doe, 2020" }
]

patterns

Your own graphic log symbols and sampler symbols. This section is usually written for you by the viewer's Hatches… window; see Your own hatches for how it works and how to write one by hand.

"patterns": {
  "SLOPE": {
    "name": "Sloping lines",
    "svg": "<svg viewBox='0 0 40 20'><line x1='0' y1='20' x2='40' y2='0' stroke='black'/></svg>"
  }
}

layout

The log's columns, their order, relative widths and headings, and its width and font size, saved with the data. Without it, the built-in layout is used. It's usually written for you by the viewer's Layout… window; see Columns and layout.

"layout": {
  "width": 1000,
  "columns": [
    "depth", "graphic", { "id": "description", "width": 25, "label": "Soil description" },
    "sample_type", "sample_name", "blow_count",
    { "id": "pp", "source": "sample", "field": "pocket_pen", "label": "PP (tsf)" },
    "remarks"
  ]
}