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
- Depths are measured down from the ground surface, in the length unit from
units. They can't be negative. For each layer and sample,bottommust be greater thantop. - Order doesn't matter. Layers and samples are sorted by depth before drawing.
nullmeans "not given"."water_content": nullis the same as leaving the field out. Some databases export empty fields as "null", so either is accepted.- Field names are checked. A misspelled name such as
"descripton"is an error ("unknown property"), so typos don't silently lose data. Names are lower case, with underscores. - Gaps and overlaps between layers are allowed but reported as warnings, in case they're mistakes. A gap is left blank in the graphic log.
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.
| Field | Values | Default | Applies 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.
| Field | Meaning | Example |
|---|---|---|
boring_name | Boring ID, used as the title | "B-3" |
project | Project name | "Harbor Terminal Wharf" |
site_name | Site | "Berth 12" |
latitude, longitude | Decimal degrees (west longitudes are negative) | 33.74215, -118.26541 |
elevation | Ground surface elevation, in the length unit. Adds an elevation column. | 3.2 |
datum | Elevation datum | "NAVD88" |
start_date, end_date | Drilling dates | "2019-06-11" |
boring_type | Drilling method | "Hollow-stem auger" |
rig | Drill rig | "CME-75" |
diameter | Borehole diameter, in the diameter unit | 102 |
hammer | Hammer type and weight | "Automatic trip, 63.5 kg" |
energy_ratio | Hammer energy ratio, percent | 82 |
logged_by | Logger | "J. Doe" |
driller | Drilling contractor | "ABC Drilling" |
notes | Any other notes | "Hole backfilled with grout" |
layers
The strata, one object per layer. At least one layer is required.
| Field | Meaning | Example |
|---|---|---|
top, bottom | Required. Depths of the layer's top and bottom | 4.5, 6.0 |
description | Material description, as it should appear on the log | "Gray, soft, wet, lean CLAY with sand" |
uscs | USCS 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" |
hatch | The 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.
| Field | Meaning | Units |
|---|---|---|
top, bottom | Required. Depth interval sampled (for an SPT, the 18 in / 0.45 m drive) | length |
name | Sample name | text, e.g. "S-1" |
type | Sampler type. Used to pick sampler symbol. See sampler types. Default "Other" | "SPT", "Shelby", ... |
blow_count | Blow count as reported: a number, or text for refusal | 14, "50/5in" |
blows | Blows for each increment | [6, 8, 10] |
energy_ratio | Hammer energy ratio for this sample, if different from the header | % |
sampler_diameter | Sampler outside diameter | diameter |
recovery_percent | Recovery: 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_weight | Unit weights of the whole sample, for example a tube weighed before it is extruded. Shown level with the sample. Results on specimens go in specimens | unit_weight |
remarks | Notes about the sample | text |
specimens | The specimens cut from the sample for laboratory tests, with their results (below) | list |
uscs | USCS symbol of the sample (kept with the data; not drawn) | "SM" |
custom | Values for your own columns, e.g. { "pocket_pen": 1.5 }; see custom columns | as you choose |
specimens (in a sample)
Each specimen has its own depth range and results. All fields are optional.
| Field | Meaning | Units |
|---|---|---|
name | Specimen reference | text |
top, bottom | Depth range of the specimen. Without top, its results are shown level with the sample, with no box | length |
water_content | Water (moisture) content | % |
total_unit_weight | Total (bulk) unit weight | unit_weight |
dry_unit_weight | Dry unit weight | unit_weight |
specific_gravity | Specific gravity of solids, Gs | – |
fines_content | Percent passing the No. 200 (75 µm) sieve | % |
liquid_limit, plastic_limit | Atterberg limits | % |
nonplastic | true for a non-plastic specimen: "NP" in both limit columns | true/false |
uscs | USCS symbol from the laboratory classification of the specimen (its limits and sieve analysis). Shown in the Lab USCS column | "CL" |
remarks | Notes about the specimen | text |
custom | Values 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 }
] }
]
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.
| Field | Meaning | Example |
|---|---|---|
depth | Depth to water | 6.5 |
date | When it was measured | "2021-03-02" |
note | Circumstances | "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"
]
}