[{"data":1,"prerenderedAt":1414},["ShallowReactive",2],{"page-\u002Fformat\u002Fguides\u002Fwriting-by-hand":3,"navigation":1038},{"collection":4,"page":5},"docs_en",{"id":6,"title":7,"body":8,"description":1029,"extension":1030,"meta":1031,"navigation":1032,"path":1033,"rawbody":1034,"seo":1035,"stem":1036,"__hash__":1037},"docs_en\u002Fformat\u002F3.guides\u002F1.writing-by-hand.md","Writing a .well by hand",{"type":9,"value":10,"toc":1019},"minimark",[11,21,26,39,51,122,127,131,194,198,249,265,281,285,306,321,518,528,532,557,561,564,935,967,971,995,999,1015],[12,13,14,15,20],"p",{},"Most files are written by software, but a hand-written file is often the fastest way to record a single well, prepare test data or fix a detail. This guide collects the habits that keep such a file valid. Start from ",[16,17,19],"a",{"href":18},"\u002Fformat\u002Fgetting-started\u002Ffirst-well-file","Your first .well file"," if you have not written one yet.",[22,23,25],"h2",{"id":24},"start-from-something-valid","Start from something valid",[12,27,28,29,33,34,38],{},"Copy an ",[16,30,32],{"href":31},"\u002Fformat\u002Freference\u002Fexamples","example well"," that resembles yours, or the minimal file from the first-file guide, and change it step by step. Validate after each block you add (see ",[16,35,37],{"href":36},"\u002Fformat\u002Fguides\u002Fvalidating","Validating","): an error is easier to find in ten new lines than in three hundred.",[12,40,41,42,46,47,50],{},"A JSON-aware editor helps. In VS Code, associate the extension with JSON (",[43,44,45],"code",{},"\"files.associations\": { \"*.well\": \"json\" }"," in your settings) and add a ",[43,48,49],{},"$schema"," member at the top of the file. You then get completion and inline errors from the published schema:",[52,53,58],"pre",{"className":54,"code":55,"language":56,"meta":57,"style":57},"language-json shiki shiki-themes material-theme-lighter material-theme material-theme-palenight","{\n  \"$schema\": \"https:\u002F\u002Fwelldot.org\u002Fschema\u002Fv2\u002Fwell.schema.json\",\n  \"version\": \"2.4\"\n}\n","json","",[43,59,60,69,96,116],{"__ignoreMap":57},[61,62,65],"span",{"class":63,"line":64},"line",1,[61,66,68],{"class":67},"sMK4o","{\n",[61,70,72,75,78,81,84,87,91,93],{"class":63,"line":71},2,[61,73,74],{"class":67},"  \"",[61,76,49],{"class":77},"spNyl",[61,79,80],{"class":67},"\"",[61,82,83],{"class":67},":",[61,85,86],{"class":67}," \"",[61,88,90],{"class":89},"sfazB","https:\u002F\u002Fwelldot.org\u002Fschema\u002Fv2\u002Fwell.schema.json",[61,92,80],{"class":67},[61,94,95],{"class":67},",\n",[61,97,99,101,104,106,108,110,113],{"class":63,"line":98},3,[61,100,74],{"class":67},[61,102,103],{"class":77},"version",[61,105,80],{"class":67},[61,107,83],{"class":67},[61,109,86],{"class":67},[61,111,112],{"class":89},"2.4",[61,114,115],{"class":67},"\"\n",[61,117,119],{"class":63,"line":118},4,[61,120,121],{"class":67},"}\n",[12,123,124,126],{},[43,125,49],{}," is an unknown member to the format, so readers keep it; the example wells carry one.",[22,128,130],{"id":129},"keep-the-reports-meaning","Keep the report's meaning",[132,133,134,166,183],"ul",{},[135,136,137,141,142,145,146,145,149,152,153,156,157,160,161,165],"li",{},[138,139,140],"strong",{},"Transcribe, do not interpret."," Free-text fields (",[43,143,144],{},"description",", ",[43,147,148],{},"notes",[43,150,151],{},"obs",") keep the report's own words and language. Open vocabulary fields, such as a casing ",[43,154,155],{},"type",", take the recommended value the report states, or an ",[43,158,159],{},"x-"," value for anything else; an unprefixed custom value is valid but not recommended (",[16,162,164],{"href":163},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#custom-vocabulary-values--x--prefix","custom vocabulary values",").",[135,167,168,171,172,145,175,178,179,165],{},[138,169,170],{},"Leave out what you do not know."," A missing value is omitted, never written as ",[43,173,174],{},"null",[43,176,177],{},"0"," or an empty string (",[16,180,182],{"href":181},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#absent-values-since-v24","absent values",[135,184,185,188,189,193],{},[138,186,187],{},"Convert units once, carefully."," Meters, millimeters and m³\u002Fh only (",[16,190,192],{"href":191},"\u002Fformat\u002Fconcepts\u002Funits-and-precision","Units and precision","). Write the real outer diameter of a casing, not its nominal size.",[22,195,197],{"id":196},"required-fields","Required fields",[12,199,200,202,203,206,207,211,212,145,215,145,218,145,221,145,224,145,227,145,230,145,233,202,236,239,240,243,244,248],{},[43,201,103],{}," and ",[43,204,205],{},"well_type"," are required by the spec (",[16,208,210],{"href":209},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#core-identity","core identity","). ",[43,213,214],{},"bore_hole",[43,216,217],{},"well_case",[43,219,220],{},"reduction",[43,222,223],{},"well_screen",[43,225,226],{},"surface_case",[43,228,229],{},"hole_fill",[43,231,232],{},"lithology",[43,234,235],{},"fractures",[43,237,238],{},"caves"," must be present, even as ",[43,241,242],{},"[]"," (",[16,245,247],{"href":246},"\u002Fformat\u002Freference\u002Fobjects\u002Fwell","Well object","). Every other block can be left out entirely.",[250,251,252],"note",{},[12,253,254,257,258,261,262,264],{},[43,255,256],{},"parseWell"," in ",[43,259,260],{},"@welldot\u002Fcore"," currently accepts a file without ",[43,263,205],{},". Write it anyway: the spec requires it, and other readers may reject the file.",[250,266,267],{},[12,268,269,257,271,261,273,275,276,280],{},[43,270,256],{},[43,272,260],{},[43,274,103],{},". The spec says such a file SHOULD be rejected (",[16,277,279],{"href":278},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#parser-version-handling","parser version handling","), so always write it.",[22,282,284],{"id":283},"ids-and-references","Ids and references",[12,286,287,288,291,292,295,296,299,300,165],{},"Records in the history, tests, permits, meters, production and samples have an ",[43,289,290],{},"id",". Ids are strings, unique within their block. UUIDs are recommended for software; short readable ids such as ",[43,293,294],{},"evt-01"," or ",[43,297,298],{},"am-2025"," are fine by hand (",[16,301,303,305],{"href":302},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#id-field-convention",[43,304,290],{}," field convention",[12,307,308,309,312,313,316,317,165],{},"References use those ids: an analysis lists the tests it used in ",[43,310,311],{},"source_event_ids",", a log entry points to a sample in ",[43,314,315],{},"sample_ids",". Every reference resolves within the same file (",[16,318,320],{"href":319},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#cross-array-references","cross-array references",[52,322,324],{"className":54,"code":323,"language":56,"meta":57,"style":57},"\"hydrodynamic_events\": [\n  { \"id\": \"evt-01\", \"type\": \"constant_rate\", \"datetime\": \"2019-05-20T08:00:00-03:00\", \"static_level\": 3.9 }\n],\n\"aquifer_analysis\": [\n  { \"id\": \"an-01\", \"datetime\": \"2019-06-02T10:00:00-03:00\", \"source_event_ids\": [\"evt-01\"], \"method\": \"cooper_jacob\" }\n]\n",[43,325,326,342,415,422,435,512],{"__ignoreMap":57},[61,327,328,330,333,335,339],{"class":63,"line":64},[61,329,80],{"class":67},[61,331,332],{"class":89},"hydrodynamic_events",[61,334,80],{"class":67},[61,336,338],{"class":337},"sTEyZ",": ",[61,340,341],{"class":67},"[\n",[61,343,344,347,349,351,353,355,357,359,361,364,366,368,370,372,374,377,379,381,383,386,388,390,392,395,397,399,401,404,406,408,412],{"class":63,"line":71},[61,345,346],{"class":67},"  {",[61,348,86],{"class":67},[61,350,290],{"class":77},[61,352,80],{"class":67},[61,354,83],{"class":67},[61,356,86],{"class":67},[61,358,294],{"class":89},[61,360,80],{"class":67},[61,362,363],{"class":67},",",[61,365,86],{"class":67},[61,367,155],{"class":77},[61,369,80],{"class":67},[61,371,83],{"class":67},[61,373,86],{"class":67},[61,375,376],{"class":89},"constant_rate",[61,378,80],{"class":67},[61,380,363],{"class":67},[61,382,86],{"class":67},[61,384,385],{"class":77},"datetime",[61,387,80],{"class":67},[61,389,83],{"class":67},[61,391,86],{"class":67},[61,393,394],{"class":89},"2019-05-20T08:00:00-03:00",[61,396,80],{"class":67},[61,398,363],{"class":67},[61,400,86],{"class":67},[61,402,403],{"class":77},"static_level",[61,405,80],{"class":67},[61,407,83],{"class":67},[61,409,411],{"class":410},"sbssI"," 3.9",[61,413,414],{"class":67}," }\n",[61,416,417,420],{"class":63,"line":98},[61,418,419],{"class":67},"]",[61,421,95],{"class":337},[61,423,424,426,429,431,433],{"class":63,"line":118},[61,425,80],{"class":67},[61,427,428],{"class":89},"aquifer_analysis",[61,430,80],{"class":67},[61,432,338],{"class":337},[61,434,341],{"class":67},[61,436,438,440,442,444,446,448,450,453,455,457,459,461,463,465,467,470,472,474,476,478,480,482,485,487,489,491,494,496,499,501,503,505,508,510],{"class":63,"line":437},5,[61,439,346],{"class":67},[61,441,86],{"class":67},[61,443,290],{"class":77},[61,445,80],{"class":67},[61,447,83],{"class":67},[61,449,86],{"class":67},[61,451,452],{"class":89},"an-01",[61,454,80],{"class":67},[61,456,363],{"class":67},[61,458,86],{"class":67},[61,460,385],{"class":77},[61,462,80],{"class":67},[61,464,83],{"class":67},[61,466,86],{"class":67},[61,468,469],{"class":89},"2019-06-02T10:00:00-03:00",[61,471,80],{"class":67},[61,473,363],{"class":67},[61,475,86],{"class":67},[61,477,311],{"class":77},[61,479,80],{"class":67},[61,481,83],{"class":67},[61,483,484],{"class":67}," [",[61,486,80],{"class":67},[61,488,294],{"class":89},[61,490,80],{"class":67},[61,492,493],{"class":67},"],",[61,495,86],{"class":67},[61,497,498],{"class":77},"method",[61,500,80],{"class":67},[61,502,83],{"class":67},[61,504,86],{"class":67},[61,506,507],{"class":89},"cooper_jacob",[61,509,80],{"class":67},[61,511,414],{"class":67},[61,513,515],{"class":63,"line":514},6,[61,516,517],{"class":67},"]\n",[519,520,521],"warning",{},[12,522,523,524,165],{},"Two records with the same id in one block make the file malformed. Software must not guess which one you meant (",[16,525,527],{"href":526},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#duplicate-ids-within-a-scope","duplicate ids",[22,529,531],{"id":530},"dates-and-times","Dates and times",[132,533,534,541,552],{},[135,535,536,537,540],{},"Construction dates and permit dates are calendar dates: ",[43,538,539],{},"\"2019-05-20\"",".",[135,542,543,544,547,548,165],{},"Everything that was measured or happened at a moment is an instant with its UTC offset: ",[43,545,546],{},"\"2019-05-20T08:00:00-03:00\"",". An instant without an offset is invalid (",[16,549,551],{"href":550},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#datetime-conventions","datetime conventions",[135,553,554,555,540],{},"If the report gives only the day of a test, write the local time you know (often the start of the working day) and say so in ",[43,556,148],{},[22,558,560],{"id":559},"pumping-tests","Pumping tests",[12,562,563],{},"A test is one event. Its readings sit inside steps:",[52,565,567],{"className":54,"code":566,"language":56,"meta":57,"style":57},"{\n  \"id\": \"evt-02\",\n  \"type\": \"constant_rate\",\n  \"datetime\": \"2019-05-20T08:00:00-03:00\",\n  \"static_level\": 3.94,\n  \"steps\": [\n    {\n      \"rate\": 18,\n      \"duration\": 1440,\n      \"readings\": [\n        { \"elapsed\": 1, \"depth\": 9.8 },\n        { \"elapsed\": 60, \"depth\": 14.2 },\n        { \"elapsed\": 1440, \"depth\": 15.1 }\n      ]\n    }\n  ],\n  \"recovery\": {\n    \"readings\": [\n      { \"elapsed\": 1, \"depth\": 10.4 },\n      { \"elapsed\": 120, \"depth\": 4.3 }\n    ]\n  }\n}\n",[43,568,569,573,592,610,628,643,657,663,682,699,713,748,779,809,815,821,827,842,856,887,918,924,930],{"__ignoreMap":57},[61,570,571],{"class":63,"line":64},[61,572,68],{"class":67},[61,574,575,577,579,581,583,585,588,590],{"class":63,"line":71},[61,576,74],{"class":67},[61,578,290],{"class":77},[61,580,80],{"class":67},[61,582,83],{"class":67},[61,584,86],{"class":67},[61,586,587],{"class":89},"evt-02",[61,589,80],{"class":67},[61,591,95],{"class":67},[61,593,594,596,598,600,602,604,606,608],{"class":63,"line":98},[61,595,74],{"class":67},[61,597,155],{"class":77},[61,599,80],{"class":67},[61,601,83],{"class":67},[61,603,86],{"class":67},[61,605,376],{"class":89},[61,607,80],{"class":67},[61,609,95],{"class":67},[61,611,612,614,616,618,620,622,624,626],{"class":63,"line":118},[61,613,74],{"class":67},[61,615,385],{"class":77},[61,617,80],{"class":67},[61,619,83],{"class":67},[61,621,86],{"class":67},[61,623,394],{"class":89},[61,625,80],{"class":67},[61,627,95],{"class":67},[61,629,630,632,634,636,638,641],{"class":63,"line":437},[61,631,74],{"class":67},[61,633,403],{"class":77},[61,635,80],{"class":67},[61,637,83],{"class":67},[61,639,640],{"class":410}," 3.94",[61,642,95],{"class":67},[61,644,645,647,650,652,654],{"class":63,"line":514},[61,646,74],{"class":67},[61,648,649],{"class":77},"steps",[61,651,80],{"class":67},[61,653,83],{"class":67},[61,655,656],{"class":67}," [\n",[61,658,660],{"class":63,"line":659},7,[61,661,662],{"class":67},"    {\n",[61,664,666,669,673,675,677,680],{"class":63,"line":665},8,[61,667,668],{"class":67},"      \"",[61,670,672],{"class":671},"sBMFI","rate",[61,674,80],{"class":67},[61,676,83],{"class":67},[61,678,679],{"class":410}," 18",[61,681,95],{"class":67},[61,683,685,687,690,692,694,697],{"class":63,"line":684},9,[61,686,668],{"class":67},[61,688,689],{"class":671},"duration",[61,691,80],{"class":67},[61,693,83],{"class":67},[61,695,696],{"class":410}," 1440",[61,698,95],{"class":67},[61,700,702,704,707,709,711],{"class":63,"line":701},10,[61,703,668],{"class":67},[61,705,706],{"class":671},"readings",[61,708,80],{"class":67},[61,710,83],{"class":67},[61,712,656],{"class":67},[61,714,716,719,721,724,726,728,731,733,735,738,740,742,745],{"class":63,"line":715},11,[61,717,718],{"class":67},"        {",[61,720,86],{"class":67},[61,722,723],{"class":410},"elapsed",[61,725,80],{"class":67},[61,727,83],{"class":67},[61,729,730],{"class":410}," 1",[61,732,363],{"class":67},[61,734,86],{"class":67},[61,736,737],{"class":410},"depth",[61,739,80],{"class":67},[61,741,83],{"class":67},[61,743,744],{"class":410}," 9.8",[61,746,747],{"class":67}," },\n",[61,749,751,753,755,757,759,761,764,766,768,770,772,774,777],{"class":63,"line":750},12,[61,752,718],{"class":67},[61,754,86],{"class":67},[61,756,723],{"class":410},[61,758,80],{"class":67},[61,760,83],{"class":67},[61,762,763],{"class":410}," 60",[61,765,363],{"class":67},[61,767,86],{"class":67},[61,769,737],{"class":410},[61,771,80],{"class":67},[61,773,83],{"class":67},[61,775,776],{"class":410}," 14.2",[61,778,747],{"class":67},[61,780,782,784,786,788,790,792,794,796,798,800,802,804,807],{"class":63,"line":781},13,[61,783,718],{"class":67},[61,785,86],{"class":67},[61,787,723],{"class":410},[61,789,80],{"class":67},[61,791,83],{"class":67},[61,793,696],{"class":410},[61,795,363],{"class":67},[61,797,86],{"class":67},[61,799,737],{"class":410},[61,801,80],{"class":67},[61,803,83],{"class":67},[61,805,806],{"class":410}," 15.1",[61,808,414],{"class":67},[61,810,812],{"class":63,"line":811},14,[61,813,814],{"class":67},"      ]\n",[61,816,818],{"class":63,"line":817},15,[61,819,820],{"class":67},"    }\n",[61,822,824],{"class":63,"line":823},16,[61,825,826],{"class":67},"  ],\n",[61,828,830,832,835,837,839],{"class":63,"line":829},17,[61,831,74],{"class":67},[61,833,834],{"class":77},"recovery",[61,836,80],{"class":67},[61,838,83],{"class":67},[61,840,841],{"class":67}," {\n",[61,843,845,848,850,852,854],{"class":63,"line":844},18,[61,846,847],{"class":67},"    \"",[61,849,706],{"class":671},[61,851,80],{"class":67},[61,853,83],{"class":67},[61,855,656],{"class":67},[61,857,859,862,864,866,868,870,872,874,876,878,880,882,885],{"class":63,"line":858},19,[61,860,861],{"class":67},"      {",[61,863,86],{"class":67},[61,865,723],{"class":410},[61,867,80],{"class":67},[61,869,83],{"class":67},[61,871,730],{"class":410},[61,873,363],{"class":67},[61,875,86],{"class":67},[61,877,737],{"class":410},[61,879,80],{"class":67},[61,881,83],{"class":67},[61,883,884],{"class":410}," 10.4",[61,886,747],{"class":67},[61,888,890,892,894,896,898,900,903,905,907,909,911,913,916],{"class":63,"line":889},20,[61,891,861],{"class":67},[61,893,86],{"class":67},[61,895,723],{"class":410},[61,897,80],{"class":67},[61,899,83],{"class":67},[61,901,902],{"class":410}," 120",[61,904,363],{"class":67},[61,906,86],{"class":67},[61,908,737],{"class":410},[61,910,80],{"class":67},[61,912,83],{"class":67},[61,914,915],{"class":410}," 4.3",[61,917,414],{"class":67},[61,919,921],{"class":63,"line":920},21,[61,922,923],{"class":67},"    ]\n",[61,925,927],{"class":63,"line":926},22,[61,928,929],{"class":67},"  }\n",[61,931,933],{"class":63,"line":932},23,[61,934,121],{"class":67},[12,936,937,939,940,202,942,944,945,947,948,243,950,954,955,202,961,540],{},[43,938,672],{}," is m³\u002Fh, ",[43,941,689],{},[43,943,723],{}," are minutes from the start of the step, and ",[43,946,737],{}," is the water level in meters below ground. Do not store drawdown, specific capacity or Jacob coefficients on the event: drawdown is derived from the readings, and interpretations go in ",[43,949,428],{},[16,951,953],{"href":952},"\u002Fformat\u002Fspec\u002Fv2\u002Foverview#design-principles","design principles",", \"Derived values are never stored raw\"). The step and reading schemas are ",[16,956,958],{"href":957},"\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas#pumpingstep",[43,959,960],{},"PumpingStep",[16,962,964],{"href":963},"\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas#levelreading",[43,965,966],{},"LevelReading",[22,968,970],{"id":969},"corrections","Corrections",[12,972,973,974,977,978,981,982,145,984,202,987,990,991,165],{},"To correct a measurement after a file has been shared, add a new entry whose ",[43,975,976],{},"corrects"," holds the id of the wrong one, instead of editing it. The old entry stays in the file and drops out of every calculation (",[16,979,969],{"href":980},"\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas#corrections-since-v23","). This applies to ",[43,983,332],{},[43,985,986],{},"production",[43,988,989],{},"water_samples",", the three ledger blocks (",[16,992,994],{"href":993},"\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#block-kinds-since-v23","block kinds",[22,996,998],{"id":997},"when-the-file-grows","When the file grows",[12,1000,1001,1002,1008,1009,1014],{},"Past a few hundred lines, a hand-written file is easier to maintain in the ",[16,1003,1007],{"href":1004,"rel":1005},"https:\u002F\u002Fwelldot.org",[1006],"nofollow","welldot.org"," editor, which opens and saves the same file. For many wells, write a script with ",[16,1010,1012],{"href":1011},"\u002Fcore",[43,1013,260],{}," instead.",[1016,1017,1018],"style",{},"html pre.shiki code .sMK4o, html code.shiki .sMK4o{--shiki-light:#39ADB5;--shiki-default:#89DDFF;--shiki-dark:#89DDFF}html pre.shiki code .spNyl, html code.shiki .spNyl{--shiki-light:#9C3EDA;--shiki-default:#C792EA;--shiki-dark:#C792EA}html pre.shiki code .sfazB, html code.shiki .sfazB{--shiki-light:#91B859;--shiki-default:#C3E88D;--shiki-dark:#C3E88D}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sTEyZ, html code.shiki .sTEyZ{--shiki-light:#90A4AE;--shiki-default:#EEFFFF;--shiki-dark:#BABED8}html pre.shiki code .sbssI, html code.shiki .sbssI{--shiki-light:#F76D47;--shiki-default:#F78C6C;--shiki-dark:#F78C6C}html pre.shiki code .sBMFI, html code.shiki .sBMFI{--shiki-light:#E2931D;--shiki-default:#FFCB6B;--shiki-dark:#FFCB6B}",{"title":57,"searchDepth":71,"depth":71,"links":1020},[1021,1022,1023,1024,1025,1026,1027,1028],{"id":24,"depth":71,"text":25},{"id":129,"depth":71,"text":130},{"id":196,"depth":71,"text":197},{"id":283,"depth":71,"text":284},{"id":530,"depth":71,"text":531},{"id":559,"depth":71,"text":560},{"id":969,"depth":71,"text":970},{"id":997,"depth":71,"text":998},"Habits that keep a hand-written .well file valid and faithful as it grows, from the order of blocks to ids, dates and test readings.","md",{},true,"\u002Fformat\u002Fguides\u002Fwriting-by-hand","---\ntitle: Writing a .well by hand\ndescription: Habits that keep a hand-written .well file valid and faithful as it grows, from the order of blocks to ids, dates and test readings.\n---\n\nMost files are written by software, but a hand-written file is often the fastest way to record a single well, prepare test data or fix a detail. This guide collects the habits that keep such a file valid. Start from [Your first .well file](\u002Fformat\u002Fgetting-started\u002Ffirst-well-file) if you have not written one yet.\n\n## Start from something valid\n\nCopy an [example well](\u002Fformat\u002Freference\u002Fexamples) that resembles yours, or the minimal file from the first-file guide, and change it step by step. Validate after each block you add (see [Validating](\u002Fformat\u002Fguides\u002Fvalidating)): an error is easier to find in ten new lines than in three hundred.\n\nA JSON-aware editor helps. In VS Code, associate the extension with JSON (`\"files.associations\": { \"*.well\": \"json\" }` in your settings) and add a `$schema` member at the top of the file. You then get completion and inline errors from the published schema:\n\n```json\n{\n  \"$schema\": \"https:\u002F\u002Fwelldot.org\u002Fschema\u002Fv2\u002Fwell.schema.json\",\n  \"version\": \"2.4\"\n}\n```\n\n`$schema` is an unknown member to the format, so readers keep it; the example wells carry one.\n\n## Keep the report's meaning\n\n- **Transcribe, do not interpret.** Free-text fields (`description`, `notes`, `obs`) keep the report's own words and language. Open vocabulary fields, such as a casing `type`, take the recommended value the report states, or an `x-` value for anything else; an unprefixed custom value is valid but not recommended ([custom vocabulary values](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#custom-vocabulary-values--x--prefix)).\n- **Leave out what you do not know.** A missing value is omitted, never written as `null`, `0` or an empty string ([absent values](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#absent-values-since-v24)).\n- **Convert units once, carefully.** Meters, millimeters and m³\u002Fh only ([Units and precision](\u002Fformat\u002Fconcepts\u002Funits-and-precision)). Write the real outer diameter of a casing, not its nominal size.\n\n## Required fields\n\n`version` and `well_type` are required by the spec ([core identity](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#core-identity)). `bore_hole`, `well_case`, `reduction`, `well_screen`, `surface_case`, `hole_fill`, `lithology`, `fractures` and `caves` must be present, even as `[]` ([Well object](\u002Fformat\u002Freference\u002Fobjects\u002Fwell)). Every other block can be left out entirely.\n\n::note\n`parseWell` in `@welldot\u002Fcore` currently accepts a file without `well_type`. Write it anyway: the spec requires it, and other readers may reject the file.\n::\n\n::note\n`parseWell` in `@welldot\u002Fcore` currently accepts a file without `version`. The spec says such a file SHOULD be rejected ([parser version handling](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#parser-version-handling)), so always write it.\n::\n\n## Ids and references\n\nRecords in the history, tests, permits, meters, production and samples have an `id`. Ids are strings, unique within their block. UUIDs are recommended for software; short readable ids such as `evt-01` or `am-2025` are fine by hand ([`id` field convention](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#id-field-convention)).\n\nReferences use those ids: an analysis lists the tests it used in `source_event_ids`, a log entry points to a sample in `sample_ids`. Every reference resolves within the same file ([cross-array references](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#cross-array-references)).\n\n```json\n\"hydrodynamic_events\": [\n  { \"id\": \"evt-01\", \"type\": \"constant_rate\", \"datetime\": \"2019-05-20T08:00:00-03:00\", \"static_level\": 3.9 }\n],\n\"aquifer_analysis\": [\n  { \"id\": \"an-01\", \"datetime\": \"2019-06-02T10:00:00-03:00\", \"source_event_ids\": [\"evt-01\"], \"method\": \"cooper_jacob\" }\n]\n```\n\n::warning\nTwo records with the same id in one block make the file malformed. Software must not guess which one you meant ([duplicate ids](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#duplicate-ids-within-a-scope)).\n::\n\n## Dates and times\n\n- Construction dates and permit dates are calendar dates: `\"2019-05-20\"`.\n- Everything that was measured or happened at a moment is an instant with its UTC offset: `\"2019-05-20T08:00:00-03:00\"`. An instant without an offset is invalid ([datetime conventions](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#datetime-conventions)).\n- If the report gives only the day of a test, write the local time you know (often the start of the working day) and say so in `notes`.\n\n## Pumping tests\n\nA test is one event. Its readings sit inside steps:\n\n```json\n{\n  \"id\": \"evt-02\",\n  \"type\": \"constant_rate\",\n  \"datetime\": \"2019-05-20T08:00:00-03:00\",\n  \"static_level\": 3.94,\n  \"steps\": [\n    {\n      \"rate\": 18,\n      \"duration\": 1440,\n      \"readings\": [\n        { \"elapsed\": 1, \"depth\": 9.8 },\n        { \"elapsed\": 60, \"depth\": 14.2 },\n        { \"elapsed\": 1440, \"depth\": 15.1 }\n      ]\n    }\n  ],\n  \"recovery\": {\n    \"readings\": [\n      { \"elapsed\": 1, \"depth\": 10.4 },\n      { \"elapsed\": 120, \"depth\": 4.3 }\n    ]\n  }\n}\n```\n\n`rate` is m³\u002Fh, `duration` and `elapsed` are minutes from the start of the step, and `depth` is the water level in meters below ground. Do not store drawdown, specific capacity or Jacob coefficients on the event: drawdown is derived from the readings, and interpretations go in `aquifer_analysis` ([design principles](\u002Fformat\u002Fspec\u002Fv2\u002Foverview#design-principles), \"Derived values are never stored raw\"). The step and reading schemas are [`PumpingStep`](\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas#pumpingstep) and [`LevelReading`](\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas#levelreading).\n\n## Corrections\n\nTo correct a measurement after a file has been shared, add a new entry whose `corrects` holds the id of the wrong one, instead of editing it. The old entry stays in the file and drops out of every calculation ([corrections](\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas#corrections-since-v23)). This applies to `hydrodynamic_events`, `production` and `water_samples`, the three ledger blocks ([block kinds](\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference#block-kinds-since-v23)).\n\n## When the file grows\n\nPast a few hundred lines, a hand-written file is easier to maintain in the [welldot.org](https:\u002F\u002Fwelldot.org) editor, which opens and saves the same file. For many wells, write a script with [`@welldot\u002Fcore`](\u002Fcore) instead.\n",{"title":7,"description":1029},"format\u002F3.guides\u002F1.writing-by-hand","844Csl9WbDz9NZduDUegVMkAbrlIob2EsHlTvki-bcI",{"docs_en":1039,"spec":1346,"changelogs":1396},[1040,1060,1079,1134,1234,1288],{"title":1041,"path":1042,"stem":1043,"children":1044},"Ai","\u002Fai","ai",[1045,1048,1052,1056],{"title":1046,"path":1042,"stem":1047},"Introduction","ai\u002Findex",{"title":1049,"path":1050,"stem":1051},"Converting reports with an assistant","\u002Fai\u002Fconversion-skill","ai\u002Fconversion-skill",{"title":1053,"path":1054,"stem":1055},"llms.txt and Markdown pages","\u002Fai\u002Fllms","ai\u002Fllms",{"title":1057,"path":1058,"stem":1059},"MCP server","\u002Fai\u002Fmcp","ai\u002Fmcp",{"title":1061,"path":1062,"stem":1063,"children":1064},"Contributing","\u002Fcontributing","contributing",[1065,1067,1071,1075],{"title":1046,"path":1062,"stem":1066},"contributing\u002Findex",{"title":1068,"path":1069,"stem":1070},"Writing docs","\u002Fcontributing\u002Fwriting-docs","contributing\u002F1.writing-docs",{"title":1072,"path":1073,"stem":1074},"Update rules","\u002Fcontributing\u002Fupdate-rules","contributing\u002F2.update-rules",{"title":1076,"path":1077,"stem":1078},"Content components","\u002Fcontributing\u002Fcomponents","contributing\u002Fcomponents",{"title":1080,"path":1011,"stem":1081,"children":1082},"Core","core",[1083,1085,1099,1128],{"title":1046,"path":1011,"stem":1084},"core\u002Findex",{"title":1086,"path":1087,"stem":1088,"children":1089,"page":1098},"Getting Started","\u002Fcore\u002Fgetting-started","core\u002F1.getting-started",[1090,1094],{"title":1091,"path":1092,"stem":1093},"Installation","\u002Fcore\u002Fgetting-started\u002Finstallation","core\u002F1.getting-started\u002F1.installation",{"title":1095,"path":1096,"stem":1097},"First use","\u002Fcore\u002Fgetting-started\u002Ffirst-use","core\u002F1.getting-started\u002F2.first-use",false,{"title":1100,"path":1101,"stem":1102,"children":1103,"page":1098},"Guides","\u002Fcore\u002Fguides","core\u002F2.guides",[1104,1108,1112,1116,1120,1124],{"title":1105,"path":1106,"stem":1107},"Parsing and validating","\u002Fcore\u002Fguides\u002Fparsing-and-validating","core\u002F2.guides\u002F1.parsing-and-validating",{"title":1109,"path":1110,"stem":1111},"Serializing and sharing","\u002Fcore\u002Fguides\u002Fserializing-and-sharing","core\u002F2.guides\u002F2.serializing-and-sharing",{"title":1113,"path":1114,"stem":1115},"Unit conversion","\u002Fcore\u002Fguides\u002Funit-conversion","core\u002F2.guides\u002F3.unit-conversion",{"title":1117,"path":1118,"stem":1119},"Vocabularies and textures","\u002Fcore\u002Fguides\u002Fvocabularies-and-textures","core\u002F2.guides\u002F4.vocabularies-and-textures",{"title":1121,"path":1122,"stem":1123},"Water quality vocabulary","\u002Fcore\u002Fguides\u002Fwater-quality-vocabulary","core\u002F2.guides\u002F5.water-quality-vocabulary",{"title":1125,"path":1126,"stem":1127},"Versions and time zones","\u002Fcore\u002Fguides\u002Fversions-and-time-zones","core\u002F2.guides\u002F6.versions-and-time-zones",{"title":1129,"path":1130,"stem":1131,"children":1132},"API reference","\u002Fcore\u002Fapi","core\u002Fapi\u002Findex",[1133],{"title":1129,"path":1130,"stem":1131},{"title":1135,"path":1136,"stem":1137,"children":1138},"Format","\u002Fformat","format",[1139,1141,1159,1186,1205,1224,1230],{"title":1046,"path":1136,"stem":1140},"format\u002Findex",{"title":1086,"path":1142,"stem":1143,"children":1144,"page":1098},"\u002Fformat\u002Fgetting-started","format\u002F1.getting-started",[1145,1149,1153,1157],{"title":1146,"path":1147,"stem":1148},"What is .well?","\u002Fformat\u002Fgetting-started\u002Fwhat-is-well","format\u002F1.getting-started\u002F1.what-is-well",{"title":1150,"path":1151,"stem":1152},"For geologists","\u002Fformat\u002Fgetting-started\u002Ffor-geologists","format\u002F1.getting-started\u002F2.for-geologists",{"title":1154,"path":1155,"stem":1156},"For developers","\u002Fformat\u002Fgetting-started\u002Ffor-developers","format\u002F1.getting-started\u002F3.for-developers",{"title":19,"path":18,"stem":1158},"format\u002F1.getting-started\u002F4.first-well-file",{"title":1160,"path":1161,"stem":1162,"children":1163,"page":1098},"Concepts","\u002Fformat\u002Fconcepts","format\u002F2.concepts",[1164,1168,1170,1174,1178,1182],{"title":1165,"path":1166,"stem":1167},"Depths and intervals","\u002Fformat\u002Fconcepts\u002Fdepths-and-intervals","format\u002F2.concepts\u002F1.depths-and-intervals",{"title":192,"path":191,"stem":1169},"format\u002F2.concepts\u002F2.units-and-precision",{"title":1171,"path":1172,"stem":1173},"Vocabularies","\u002Fformat\u002Fconcepts\u002Fvocabularies","format\u002F2.concepts\u002F3.vocabularies",{"title":1175,"path":1176,"stem":1177},"Profiles","\u002Fformat\u002Fconcepts\u002Fprofiles","format\u002F2.concepts\u002F4.profiles",{"title":1179,"path":1180,"stem":1181},"Versions and deprecation","\u002Fformat\u002Fconcepts\u002Fversions-and-deprecation","format\u002F2.concepts\u002F5.versions-and-deprecation",{"title":1183,"path":1184,"stem":1185},"Extensibility","\u002Fformat\u002Fconcepts\u002Fextensibility","format\u002F2.concepts\u002F6.extensibility",{"title":1100,"path":1187,"stem":1188,"children":1189,"page":1098},"\u002Fformat\u002Fguides","format\u002F3.guides",[1190,1191,1195,1197,1201],{"title":7,"path":1033,"stem":1036},{"title":1192,"path":1193,"stem":1194},"Converting a report","\u002Fformat\u002Fguides\u002Fconverting-a-report","format\u002F3.guides\u002F2.converting-a-report",{"title":37,"path":36,"stem":1196},"format\u002F3.guides\u002F3.validating",{"title":1198,"path":1199,"stem":1200},"Extending for your own needs","\u002Fformat\u002Fguides\u002Fextending","format\u002F3.guides\u002F4.extending",{"title":1202,"path":1203,"stem":1204},"Building an editor or database on .well","\u002Fformat\u002Fguides\u002Fbuilding-on-well","format\u002F3.guides\u002F5.building-on-well",{"title":1206,"path":1207,"stem":1208,"children":1209},"Overview","\u002Fformat\u002Freference","format\u002F4.reference\u002Findex",[1210,1211,1215,1218],{"title":1206,"path":1207,"stem":1208},{"title":1212,"path":1213,"stem":1214},"JSON Schema","\u002Fformat\u002Freference\u002Fjson-schema","format\u002F4.reference\u002F1.json-schema",{"title":1216,"path":31,"stem":1217},"Example wells","format\u002F4.reference\u002F2.examples",{"title":1219,"path":1220,"stem":1221,"children":1222},"Object reference","\u002Fformat\u002Freference\u002Fobjects","format\u002Freference\u002Fobjects\u002Findex",[1223],{"title":1219,"path":1220,"stem":1221},{"title":1225,"path":1226,"stem":1227,"children":1228},"About the spec","\u002Fformat\u002Fspec","format\u002F5.spec\u002Findex",[1229],{"title":1225,"path":1226,"stem":1227},{"title":1231,"path":1232,"stem":1233},"Changelog","\u002Fformat\u002Fchangelog","format\u002F6.changelog",{"title":1235,"path":1236,"stem":1237,"children":1238},"Render","\u002Frender","render",[1239,1241,1251,1283],{"title":1046,"path":1236,"stem":1240},"render\u002Findex",{"title":1086,"path":1242,"stem":1243,"children":1244,"page":1098},"\u002Frender\u002Fgetting-started","render\u002F1.getting-started",[1245,1248],{"title":1091,"path":1246,"stem":1247},"\u002Frender\u002Fgetting-started\u002Finstallation","render\u002F1.getting-started\u002F1.installation",{"title":1095,"path":1249,"stem":1250},"\u002Frender\u002Fgetting-started\u002Ffirst-use","render\u002F1.getting-started\u002F2.first-use",{"title":1100,"path":1252,"stem":1253,"children":1254,"page":1098},"\u002Frender\u002Fguides","render\u002F2.guides",[1255,1259,1263,1267,1271,1275,1279],{"title":1256,"path":1257,"stem":1258},"Panels and layout","\u002Frender\u002Fguides\u002Fpanels-and-layout","render\u002F2.guides\u002F1.panels-and-layout",{"title":1260,"path":1261,"stem":1262},"Layers and labels","\u002Frender\u002Fguides\u002Flayers-and-labels","render\u002F2.guides\u002F2.layers-and-labels",{"title":1264,"path":1265,"stem":1266},"Theming","\u002Frender\u002Fguides\u002Ftheming","render\u002F2.guides\u002F3.theming",{"title":1268,"path":1269,"stem":1270},"Locale and units","\u002Frender\u002Fguides\u002Flocale-and-units","render\u002F2.guides\u002F4.locale-and-units",{"title":1272,"path":1273,"stem":1274},"Legends","\u002Frender\u002Fguides\u002Flegends","render\u002F2.guides\u002F5.legends",{"title":1276,"path":1277,"stem":1278},"Zoom, pan and highlights","\u002Frender\u002Fguides\u002Finteraction","render\u002F2.guides\u002F6.interaction",{"title":1280,"path":1281,"stem":1282},"Using it in a framework","\u002Frender\u002Fguides\u002Fframeworks","render\u002F2.guides\u002F7.frameworks",{"title":1129,"path":1284,"stem":1285,"children":1286},"\u002Frender\u002Fapi","render\u002Fapi\u002Findex",[1287],{"title":1129,"path":1284,"stem":1285},{"title":1289,"path":1290,"stem":1291,"children":1292},"Utils","\u002Futils","utils",[1293,1295,1305,1341],{"title":1046,"path":1290,"stem":1294},"utils\u002Findex",{"title":1086,"path":1296,"stem":1297,"children":1298,"page":1098},"\u002Futils\u002Fgetting-started","utils\u002F1.getting-started",[1299,1302],{"title":1091,"path":1300,"stem":1301},"\u002Futils\u002Fgetting-started\u002Finstallation","utils\u002F1.getting-started\u002F1.installation",{"title":1095,"path":1303,"stem":1304},"\u002Futils\u002Fgetting-started\u002Ffirst-use","utils\u002F1.getting-started\u002F2.first-use",{"title":1100,"path":1306,"stem":1307,"children":1308,"page":1098},"\u002Futils\u002Fguides","utils\u002F2.guides",[1309,1313,1317,1321,1325,1329,1333,1337],{"title":1310,"path":1311,"stem":1312},"Geometry and volumes","\u002Futils\u002Fguides\u002Fgeometry-and-volumes","utils\u002F2.guides\u002F1.geometry-and-volumes",{"title":1314,"path":1315,"stem":1316},"Water levels and pumping tests","\u002Futils\u002Fguides\u002Fpumping-tests","utils\u002F2.guides\u002F2.pumping-tests",{"title":1318,"path":1319,"stem":1320},"Permits","\u002Futils\u002Fguides\u002Fpermits","utils\u002F2.guides\u002F3.permits",{"title":1322,"path":1323,"stem":1324},"Operation and production","\u002Futils\u002Fguides\u002Foperation","utils\u002F2.guides\u002F4.operation",{"title":1326,"path":1327,"stem":1328},"Water quality","\u002Futils\u002Fguides\u002Fwater-quality","utils\u002F2.guides\u002F5.water-quality",{"title":1330,"path":1331,"stem":1332},"Logger import","\u002Futils\u002Fguides\u002Flogger-import","utils\u002F2.guides\u002F6.logger-import",{"title":1334,"path":1335,"stem":1336},"SIAGAS import","\u002Futils\u002Fguides\u002Fsiagas-import","utils\u002F2.guides\u002F7.siagas-import",{"title":1338,"path":1339,"stem":1340},"Formatting","\u002Futils\u002Fguides\u002Fformatting","utils\u002F2.guides\u002F8.formatting",{"title":1129,"path":1342,"stem":1343,"children":1344},"\u002Futils\u002Fapi","utils\u002Fapi\u002Findex",[1345],{"title":1129,"path":1342,"stem":1343},[1347],{"title":1135,"path":1136,"stem":1137,"children":1348,"page":1098},[1349],{"title":1350,"path":1226,"stem":1351,"children":1352,"page":1098},"Spec","format\u002Fspec",[1353,1362,1371],{"title":1354,"path":1355,"stem":1356,"children":1357,"page":1098},"Reference","\u002Fformat\u002Fspec\u002Freference","format\u002Fspec\u002Freference",[1358],{"title":1359,"path":1360,"stem":1361},"FGDC Texture Patterns Reference","\u002Fformat\u002Fspec\u002Freference\u002Ffgdc-textures","format\u002Fspec\u002Freference\u002Ffgdc-textures",{"title":1363,"path":1364,"stem":1365,"children":1366,"page":1098},"V1","\u002Fformat\u002Fspec\u002Fv1","format\u002Fspec\u002Fv1",[1367],{"title":1368,"path":1369,"stem":1370},".well File Format Specification","\u002Fformat\u002Fspec\u002Fv1\u002Fwell-format","format\u002Fspec\u002Fv1\u002Fwell-format",{"title":1372,"path":1373,"stem":1374,"children":1375,"page":1098},"V2","\u002Fformat\u002Fspec\u002Fv2","format\u002Fspec\u002Fv2",[1376,1380,1384,1388,1392],{"title":1377,"path":1378,"stem":1379},".well File Format Specification — Version 2.4: Format Reference","\u002Fformat\u002Fspec\u002Fv2\u002Fformat-reference","format\u002Fspec\u002Fv2\u002Fformat-reference",{"title":1381,"path":1382,"stem":1383},".well File Format Specification — Version 2.4: Interoperability","\u002Fformat\u002Fspec\u002Fv2\u002Finteroperability","format\u002Fspec\u002Fv2\u002Finteroperability",{"title":1385,"path":1386,"stem":1387},".well File Format Specification — Version 2.4: Object Schemas","\u002Fformat\u002Fspec\u002Fv2\u002Fobject-schemas","format\u002Fspec\u002Fv2\u002Fobject-schemas",{"title":1389,"path":1390,"stem":1391},".well File Format Specification — Version 2.4: Overview","\u002Fformat\u002Fspec\u002Fv2\u002Foverview","format\u002Fspec\u002Fv2\u002Foverview",{"title":1393,"path":1394,"stem":1395},".well File Format Specification — Version 2.4: Water Quality","\u002Fformat\u002Fspec\u002Fv2\u002Fwater-quality","format\u002Fspec\u002Fv2\u002Fwater-quality",[1397,1402,1408],{"title":1080,"path":1011,"stem":1081,"children":1398,"page":1098},[1399],{"title":260,"path":1400,"stem":1401},"\u002Fcore\u002Fchangelog","core\u002FCHANGELOG",{"title":1235,"path":1236,"stem":1237,"children":1403,"page":1098},[1404],{"title":1405,"path":1406,"stem":1407},"@welldot\u002Frender","\u002Frender\u002Fchangelog","render\u002FCHANGELOG",{"title":1289,"path":1290,"stem":1291,"children":1409,"page":1098},[1410],{"title":1411,"path":1412,"stem":1413},"@welldot\u002Futils","\u002Futils\u002Fchangelog","utils\u002FCHANGELOG",1793050495877]