Changelog¶
All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased¶
1.14.0 - 2026-11-19¶
Added¶
- Video tutorials. The documentation has a
Video tutorials page, and the
Quickstart, Reading files, AGS4 files, conversion, comparison and Browser pages each
open with a short narrated video of that feature. Every video has English captions,
chapters and a full transcript, plays from the docs site itself with no third-party
player or cookies, and is rendered from a script in
docs/tutorials/each time the site is published. The commands shown really run, and a video whose output no longer matches its script stops the build, so the videos cannot fall behind the software. - Follow the video tutorials step by step. Under each video, Try it yourself offers the files the video starts from, exactly as it used them, one by one or as a zip with its SHA-256, and the commands it runs, ready to copy, after a three-line uv setup that pins the pyDIGGS version the video shows. The files are synthetic examples (Apache-2.0). Every docs build runs the commands from the unpacked zip and checks they print what the video shows, so the download is always enough to repeat it.
Changed¶
- The HTTP API refuses a query parameter an endpoint does not take.
/v1/validate,/v1/read,/v1/convert,/v1/ags4/check,/v1/diffand/v1/rulesanswer422 invalid-parameterwitherrors: [{"parameter": "max_change", "problem": "unknown parameter"}]instead of ignoring it, so a misspelt option is an error rather than a silent default. Values are never echoed; at most 20 names are listed. This is what@pydiggs/client's handler already does. The Python library, the CLI and the sidecar already refused unknown options and do not change.
Upgrading: remove the parameter the answer names. To keep the old behaviour for a
while, set ServerSettings(unknown_query="ignore") or PYDIGGS_UNKNOWN_QUERY=ignore.
See Unknown query parameters.
Deprecated¶
ServerSettings(unknown_query="ignore")andPYDIGGS_UNKNOWN_QUERY=ignore: they exist only to ease the upgrade to 1.14, warn when used, and will be removed in pyDIGGS 2.0.
1.13.1 - 2026-11-19¶
Fixed¶
- HTTP: a valid
/v1/convertrequest was refused when a form field overrode a query value. With?to=ags4&ags_version=4.2and the multipart fieldags_version=4.1.1, the server answered 422 "applies only to to=ags4", because it checked the overridden query value without the query'sto. Each overridden query value is now checked on its own in the request the fields complete, as the docs say ("a field wins, but both must be valid"); an invalid one, such as?to=boguswith the fieldto=diggs, is still 422./v1/difffollows the same rule. - Sidecar: a
difffile given by path that is refused now names its side. A refusal (path-not-permitted,input-too-largeorcompressed-input) carrieserrors: [{"param": "new_path", "problem": "is not permitted"}]or the like, as a refusal of an inline file already namedoldornew. The path itself is never included. - The OpenAPI document of
POST /v1/diff.max_changesnow has themaximumthe server reads (18 digits); a longer number was valid by the document but refused. The 200 response now says that running out of time is a 200 withcomplete: falseunder thread isolation, and 504timeoutunder process isolation (create_app's default). - Docs: what a hand-built
Modelneeds fordiff. AModelbuilt by hand must setsource.sha256to a 64-digit lowercase hex digest fordiff.compareto give a valid diggs-diff 1.0 report: the report copies it unchanged. Models frompydiggs.readandpydiggs.convertalways do.
1.13.0 - 2026-11-19¶
Added¶
- Compare two files over HTTP, the sidecar and
@pydiggs/client. The comparisonpydiggs diffmakes is now offered on every surface, each answering the same diggs-diff 1.0 document: - HTTP.
POST /v1/difftakes the two files as multipart partsoldandnew, with the optionsmatch,rel_tol,abs_tol,max_changes,show_reformatted,show_renamed,old_nameandnew_namein the query or the form. Each file is held to the server'smax_body_bytes, the pair runs as one job under its time limit, and an answer larger than four timesmax_body_bytesis 422result-too-large, as for/v1/read. See HTTP API. - Sidecar protocol 1.3. The method
difftakes each file as base64 or as a path;initializereportscapabilities.diffanddiff_schema_url. A session that negotiated protocol 1.0 to 1.2 is refused the method. @pydiggs/client.diff(old, new, options)on the HTTP, browser, Node, pool and hybrid clients, and/v1/diffincreatePydiggsHandler. Requires pyDIGGS 1.13.0 on the server or in the worker.
A refused file is named by its side (old or new); errors never carry a path or the
file's content.
Changed¶
pydiggs.diffis stable, and its report format diggs-diff 1.0 is frozen. A diggs-diff 1.0 document changes only in a major release of the format.to_json()writes"schema_version": "1.0"against diggs-diff-1.0.schema.json; documents written by 1.12 (1.0-beta.1) still read, and the beta schema stays published underschemas/preview/.capabilities()listsdiffas stable.- Two files are also compared on the root element and between records. The root
element's attributes (other than its id and
xsi:schemaLocation) and text before, between or after the top-level members are compared and listed with the document's record, under paths that start withxml.Diggs[1]. - Each edit is listed once. A changed declared type is listed at the column's type, unit labels a result index reads at the index's unit, and a changed link at its links; none is listed again as file content.
- Fewer differences that are only re-export noise. Other
cs/tsseparators, a default separator written out or left out, anddoubledeclared asfloatare reformatted (listed only with--verbose) when every value reads the same. A different decimal mark is still a change, since pyDIGGS reads numbers written with a point. compare(match="gml_id")and--match gml_idare accepted as another spelling ofgml-id.
Fixed¶
- Two result columns that moved and exchanged a declared type of the same kind compared identical. Content that the model does not keep is now paired by what its typed fields hold before file order.
pydiggs validateandpydiggs convertno longer fail with a traceback when the terminal cannot encode the report (for example a non-UTF-8 Windows console); a stdout that cannot be written exits 2, aspydiggs diffdoes.diff.compareraisedOverflowErrorfor a tolerance or time budget given as an integer too large for a float (such asabs_tol=10**400); it now raises the documentedValueErrornaming the option.
1.12.0 - 2026-11-18¶
Added¶
pydiggs.diffandpydiggs diff: what changed between two DIGGS files. The comparison is of what the files describe, not of how they are written: it reads both withpydiggs.readand reports which boreholes, samples, tests and other records were added or removed, and which values changed in the records both files hold. It is a preview in 1.12: the report format and the comparison rules may change in a minor release; the stablepydiggs.diffand diggs-diff 1.0 are planned for 1.13. The new page Comparing two files describes what counts as a change.
from pydiggs import diff
d = diff.compare("site-rev1.xml", "site-rev2.xml")
d.identical # False
d.summary["features"] # {'added': 0, 'removed': 0, 'changed': 1, 'unchanged': 0}
print(d.to_text()) # the report `pydiggs diff` prints
d.to_json(indent=2) # a diggs-diff 1.0-beta.1 document
- Command line.
pydiggs diff OLD NEWprints the report as text or, with--format json, as a diggs-diff document;-o FILEwrites it to a file, in UTF-8. Options:--match auto|gml-id|natural,--rel-tol,--abs-tol,--max-changes,--time-budget,--max-bytes, and--verboseto also list the values that are only written differently and the records whosegml:idchanged. The exit codes are those ofdiff(1): 0 when the files are identical and the comparison finished, 1 when they differ or the comparison is incomplete, 2 on a usage error, a file that cannot be read or is not DIGGS, or a report that cannot be written. - Python.
diff.compare(old, new)takes paths, bytes orModels, in any mix, and returns aDiffof the added, removed and changed nodes and their values. - Compare the files for the full comparison. Given two files (paths or bytes), the
comparison covers what
pydiggs.readputs in a model and, beyond that, what each record holds that a model does not keep: the unit labels, axis labels and dimension of a location, the geometry of a lithology layer, a grid's origin and offsets, the files of a data package, a column's property class, declared type and index, the reason of a null value, the decimal mark and separators of a result set, and values in a result row that no column holds. Such a value is listed under a path that starts withxml.; an element that is renamed, added or removed is listed as a count under a path that ends in#elements, and text after a comment or a child element under one that ends in#tail. Such content stays tied to the typed value of its element, so two names that exchange theircodeSpaceare a difference, and a separator after the last value of a result row is one more value. Given twoModels, or a file and aModel, the comparison is of the two models and can only see what a model holds. - What does not count. Element order, number formatting, provenance and every
gml:id: a record's own, and that of a geometry, a time instant or any other element inside a record. Two exports of the same data with newly generated ids are identical. - Matching. Nodes are paired by
gml:idand element, then by a natural key (a borehole's kind and name; a sample's borehole, name and top; ...), so they stay paired when their ids change. A node paired by natural key whose id differs is renamed, not changed: it is counted inDiff.renamedand listed, with its old and new id, only withshow_renamed=True(--verbose). Withmatch="gml-id"there is no natural key, so such a node is removed and added. A key that more than one node has is never matched and is reported asdiff.ambiguous-match. - References. A local reference (
xlink:href="#x",srsName="#x") is compared by what it points to, not by the text of the id; one that cannot be resolved for certain is compared as text, which errs on the side of reporting a difference. A link to an element inside a record is shown as the record's name and the link (B-1 #p2), and a link to one of two equal elements is compared by its text. Repeated elements that differ only in what their references point to are not taken as equal, also below the 64 levels compared one by one; those that come in another order with new ids are the same data when each still names its target (unless one has agml:idinside). A reference that kept its text and names another element is shown as#a -> #a (another target). - Compare files for the fullest independence from ids. A reference to an element
the model does not keep, such as a borehole's linear referencing system naming its
centre line (
linearElement), is resolved from the files as they are read (by the record holding the element and its path below it, when no element on the path has a same-named sibling), so it needs paths or bytes. Between twoModels that reference, and a link to such an element, are compared as text (the link by its record and its text), so the result may list references whose target could not be established. A site grid that no record keeps is the same grid under a new id only when the file defines no other system with its name and unit, which also takes the files. - Numbers and units. Numbers compare within
rel_tol(default 1e-9, below 1) andabs_tol. The same number written differently is counted as reformatted and listed only withshow_reformatted=True(--verbose). A change of unit is always a change, and nothing is converted. - Result tables align rows by the domain index (depth) when it is unique.
- Limits.
max_changesandtime_budgetbound the work and the list: the result then hascomplete=Falseand adiff.limitordiff.timeoutfinding. The summary counts stay exact unless the time ran out, and a long value such as a coordinate list is compared within the time budget. A result set the reader could not read, and a file with more content outside the model than a file of its size may have, also make the comparison incomplete, so it never ends as identical. - Output.
Diff.to_json()writes a new contract, diggs-diff 1.0-beta.1, with its JSON Schema (diff.diff_schema(), published asdiggs-diff-1.0-beta.1.schema.json). Paths in it are at most 1000 characters. On a terminal whose encoding cannot hold a character, the command line writes it in escaped form.Diff.to_text()escapes every bracket that could openrichmarkup, so no tag can form across two values when the text is printed through arichconsole. - Where it runs. Pure standard library, no new dependency, and
import pydiggsdoes not import it.pydiggs.capabilities()lists the operationdiffaspreview. It also runs in the browser under Pyodide. The HTTP API, the sidecar, the MCP server and@pydiggs/clientdo not offer it yet. - diggs-findings 1.2 adds the step
diffand the rule idsdiff.ambiguous-match,diff.limitanddiff.timeout. It only adds to 1.1, and the 1.0 and 1.1 schema files are packaged and published unchanged. - US survey foot in AGS4, as
ftUS. A value in US survey feet (DIGGS unitft[US], or a CRS such as EPSG:2263 or 6539 whose axes are in US survey feet) was reported asconvert.unmapped-unitand left out when writing AGS4. It is now written as given, in the project-defined unitftUS, and the UNIT group of the file defines it as "US survey foot (1200/3937 m)", as AGS4 requires of a unit it does not list. Plainftstays the international foot. A file that usesftUSreads back toft[US]. Values are never converted. - AGS4 depths in feet are carried into DIGGS. The unit of
LOCA_FDEP(m,ftorftUS) is now the unit of every depth along a feature: of each feature's linear referencing system, of the CPT depth column and of the sample and layer depths, as DIGGSm,ftorft[US]. Before, a depth in feet was reported asconvert.unmapped-unitand left out of the DIGGS file, so a US-unit file lost every depth-keyed value, and the DIGGS to AGS4 to DIGGS round trip of the official US examples lost all its depths. Depths are carried, never converted. A file with no unit onLOCA_FDEPis still read in metres (declared asconvert.assumed). The DIGGS writer names the US survey foot as linear referencing methodOther: trueUSSurveyFootage, as DIGGS 3.0.0 has no name for it.
Changed¶
- The documentation site is versioned.
latest/is the newest release anddev/is master; the site root redirects tolatest/, and every page states the version it describes. The command-line facts page and the operations table in Capabilities are generated from the code, and the Python examples in the guides are run in CI. Every JSON Schema stays at its published URL underschemas/at the site root, which the$schemaof every document pyDIGGS writes names. - Findings documents now declare diggs-findings 1.2 (
schema_versionand$schema), on every surface: the Python API, the command line, the HTTP API, the sidecar and the MCP server. The OpenAPI and OpenRPC documents and the generated@pydiggs/clienttypes follow. Nothing was removed or renamed, and every 1.1 document is a valid 1.2 document. A consumer that checks documents against the 1.1 schema must move to the 1.2 schema, because each schema pins$schemato its own URL; one that comparesschema_versionfor equality should accept any 1.x. - The AGS4 and DIGGS mapping table is 1.2 (
mapping_version; 1.11.0 shipped 1.0), a minor version: it adds the unitftUS, and depths in feet, reported as lost before, are now written. Output for files with depths in metres is unchanged. - A file has one depth unit, that of
LOCA_FDEP. A depth heading in another unit is reported asconvert.unmapped-unit, naming both units, and not written. This changes one case: in a file whoseLOCA_FDEPis in feet while other depth headings are in metres, 1.11 left outLOCA_FDEPand wrote the depths in metres; 1.12 writesLOCA_FDEPand the depths in feet, and reports the ones in metres.
Fixed¶
- The mapping table's JSON Schema is published.
convert-mapping-1.schema.json, shipped in the wheel since 1.11.0, nameshttps://xinp-hub.github.io/pydiggs/schemas/convert-mapping-1.schema.jsonas its$id, but the documentation site did not publish it there. It does now.
1.11.0 - 2026-11-16¶
Added¶
pydiggs.convertis stable, both ways.convert.ags4_to_diggs(the 1.9 and 1.10 preview) is joined byconvert.diggs_to_ags4(source)andconvert.model_to_ags4(model), which write an AGS4 file (4.2 by default, orags_version="4.1.1") from a DIGGS document or aModelin memory, by the same mapping table read the other way. AGS lists 4.2 as the current edition and 4.1.1 as deprecated. As of November 2026 the BGS AGS validator (agsapi.bgs.ac.uk) and python-ags4 1.2.0 accept AGS4 only up to 4.1.1, so passags_version="4.1.1"for files meant for them.TRAN_AGSis written as4.2(the value python-ags4 recognises), static cone tests go to CPTG/CPTT in 4.2 and SCPG/SCPT in 4.1.1, and 4.2 output also gives the CRS as an EPSG code (LOCA_NSRI,LOCA_LLSI). Every value of the model (names, remarks,params, typed fields,extraelements, links that are not structure, result-table cells) is either written into a cell or named by a finding: a value with no AGS4 target is the newconvert.unmapped-elementwarning. A unit comes from the unit table; for a CRS outside the code table it is the EPSG axis unit (metreis written asm,footasft), and a value whose unit cannot be named (a US survey foot, which AGS4's unit table lacks) is reported asconvert.unmapped-unit, never written with an empty unit. A location name that AGS4 cannot hold (a line break) is replaced by the record's id and reported. The output passesags4.check(it carries the source's non-ASCII text unchanged, which Rule 1 reports); without a bundled AGS4 dictionary, each heading's TYPE is the one its values have, and the ABBR, TYPE and UNIT groups list what the file uses. The module adds no top-level name:
from pydiggs import ags4, convert
c = convert.diggs_to_ags4("site.xml") # or convert.model_to_ags4(model)
c.ags4, c.validation.ok, c.losses # the File, ags4.check, what was lost
ags4.write(c.ags4, "site.ags") # or c.save("site.ags")
back = convert.ags4_to_diggs("site.ags")
back.residual # an AGS4 File of what was not converted
Conversion.residual: for AGS4 to DIGGS, an AGS4 File holding exactly the values a
convert finding names, with the key fields of their rows, so the DIGGS output and the
residual file together hold everything the source did. Conversion.ags4 holds the AGS4
output of the other direction, and Conversion.save() writes either.
- Formula-like text in AGS4 output (a value starting with =, +, @, or a - that is
not a number) is written unchanged and reported as ags4.formula-text; the opt-in
formula_guard="prefix" writes such text under a non-key text heading with an
apostrophe in front, and reports it.
- Mapping table 1.0 (convert.MAPPING_VERSION), with the Tier B groups: hole
diameter (HDIA), casing (CDIA), backfill (BKFL), water strikes (WSTG with WSTD), density
(LDEN) and static cone tests (SCPG with SCPT, and CPTG with CPTT, which replace them in
AGS4 4.2; DIGGS to AGS4 writes the pair of the target version). Hole orientation (HORN)
is listed and reported, not converted: AGS4 measures inclination positively down and
DIGGS 3.0.0 plunge positively up, and values are never converted. The table format
gains the feature-component pattern and the group keys role, holder,
holder_role, interval_top and to_ags4_versions (convert-mapping-1.schema.json);
mapping_info() reports the table. All 25 groups are reviewed (owner review against
the AGS4 4.1.1 and 4.2 dictionaries and DIGGS 3.0.0); the generated page is now "AGS4
and DIGGS mapping".
- pydiggs convert --to ags4: DIGGS to AGS4 on the command line.
pydiggs convert site.xml -o site.ags --to ags4 [--ags-version 4.2|4.1.1] writes AGS4,
and pydiggs convert site.ags -o site.xml --residual left.ags also writes the residual
AGS4 file (not written when everything was converted). The direction is never guessed:
AGS4 to DIGGS stays the default, and --diggs-version, --ags-version and
--residual are refused for the other direction. With --fail-on error an output that
fails the AGS4 check exits 1, as one that fails DIGGS validation does.
- HTTP API and sidecar: conversion to AGS4. POST /v1/convert and the sidecar
convert method (protocol 1.2) take to=ags4 with ags_version for a DIGGS document
(a raw HTTP body is application/xml or text/xml) and answer AGS4 as
text/plain; charset=utf-8, validated by ags4.check. ConversionResult gains
ags_version and residual_base64, the residual AGS4 file of an AGS4 to DIGGS
conversion (null when nothing was left over, and for to=ags4). The sidecar's
capabilities.convert lists the targets, the AGS4 versions written and
residual: true. OpenAPI, openrpc.json and the JS types are regenerated.
- pydiggs.capabilities() gains convert.diggs-to-ags4, and both conversions are now
stable (the AGS4 reading, writing and checking operations stay preview).
- The Pyodide smoke converts an AGS4 file to DIGGS and that DIGGS back to AGS4 4.2 and
4.1.1, and compares the outputs and the residual file with CPython's bytes.
- Documentation: the conversion page is now AGS4 and DIGGS
conversion, and the conversion API is in
the Python API reference.
Changed¶
Conversion.xmlis None for a conversion to AGS4 (it was always bytes in the preview).- AGS4 to DIGGS: a GRAT row whose GRAT_TYPE is WS or DS is still written as a sieve
grading, but the code itself is now reported as
convert.unmapped-code(DIGGS does not say whether sieving was wet or dry); a test placed at its sample's top because it gives no depth of its own is reported asconvert.assumed. Mapping table 0.1 becomes 1.0. - What moved since the 1.9.0 and 1.10.0 preview (mapping table 0.1 to 1.0). Conversions of the same AGS4 file give different DIGGS than 1.9.0 and 1.10.0 did:
GEOL_FORM(the geological unit or stratum name) is now the DIGGSunitName;GEOL_GEOL, a project geology code whose meaning is in the file's ABBR group, is reported and no longer written as the unit name.LOCA_LOCA, a grouping of locations by site sub-division, is reported and no longer written as the location's description.- The GRAG fractions (
GRAG_VCRE,GRAV,SAND,SILT,FINE) are not converted either way and are reported: AGS4 uses ISO 14688-1 size limits (63 mm, 2 mm, 63 µm) and the DIGGS properties ASTM limits (75 mm, 4.75 mm, 0.075 mm). A GRAG row with no other result (GRAG_UC,GRAG_CLAY, the newGRAG_CC) cannot be written as a DIGGS test and is reported asconvert.incomplete(an error:pydiggs convertexits 1), and its GRAT readings are then reported too. SAMP_TYPE:WSandSPT, which are not AGS4 sample type codes, are written as text and reported;L,SPTLS,M,TWandEWare added.TWandEWshare their DIGGS code withUTandW, so the AGS4 code is also reported.- Static cone tests whose
SCPG_TYPEorCPTG_TYPEisBALLorT-BARare reported, not written: their resistance is not a cone resistance. LNMC_MCwithLNMC_ISNT= N, andLDEN_BDENandLDEN_MCof aRECOMPACTEDspecimen, are reported instead of being written as DIGGS properties for natural conditions. An SPT N (ISPT_NVAL,ISPT_N60) from a test drive that stopped short of 300 mm (ISPT_PEN3toISPT_PEN6) is reported, not written as blows per foot.- A missing or unreadable
TRAN_DATEis written as<creationDate indeterminatePosition="unknown"/>(stillconvert.assumed), not as 1970-01-01;Model.document.creation_dateis then None. DIGGS to AGS4 leaves the REQUIREDTRAN_DATEempty for such a document and reports it. - AGS4 codes are matched as AGS4 says abbreviations are, not case sensitive, and joined
codes match in either order with the file's
TRAN_RCON(sorc+cpis DIGGS CP-RC). - New:
LOCA_TYPESCP(a Sounding),SNC,VE,VC,AUGH,AUGS,TT;LOCA_GREFOSI; AGS4 4.2LOCA_NSRIandLOCA_LLSIread beforeLOCA_GREFandLOCA_LLZ; a ground level over British National Grid withLOCA_NATDnaming Ordnance Datum Newlyn is written in EPSG:7405 (OSGB36 + ODN height), and any other ground level is reported as having no stated vertical datum;ISPT_N60(n60),GRAG_CC(coef_curvature),WSTG_CAS(bottomCasing), and the cone readingsSCPT_FRR/CPTT_RF(friction_ratio),CPTT_INCX/INCY,SCPT_TEMP/CPTT_TEMP,SCPT_SMP/CPTT_SMPandCPTT_DUR; DIGGS to AGS4 writes NP inLLPL_PLonly. - The internal writer writes the
extraelements of a component (such as a water strike'sbottomCasing) as given, and writes a document with no creation date with an unknown one. - The HTTP problem
invalid-documentis titled "Invalid document" (it was "Not a DIGGS document"), since/v1/convertanswers it for AGS4 input too; the code, status andkindare unchanged. The sidecar's fixed messages forinvalid-documentandresult-too-large(and soopenrpc.json) no longer name DIGGS input orselectonly; the detail of areadthat is too large still suggestsselect. - The plain-language guidance of
convert.unmapped-code,convert.unmapped-unitandconvert.assumedfits both directions of conversion.
Deprecated¶
pydiggs.preview.convertis a deprecated alias ofpydiggs.convert: using one of its names warns with aDeprecationWarning, and it will be removed in pyDIGGS 2.0. Importing it does not warn.
Fixed¶
pydiggs.readread a component'sbottomCasingorbottomHoleas its location when it had no other point, so a water strike that gave only its casing depth came back with that depth as its seal depth. Those two elements now stay in the component'sextra. Only files with such components read differently.- AGS4 to DIGGS no longer drops a unit without saying so. Grid coordinates written with
no CRS whose axes the code table gives a unit for (an empty or unlisted
LOCA_GREF), and values whose DIGGS property has no unit (the%of the LLPL limits), are written as before, and their UNIT is now reported asconvert.unmapped-unit; the residual file keeps those values with their unit.
1.10.0 - 2026-11-14¶
Added¶
pydiggs convert: AGS4 to DIGGS on the command line.pydiggs convert site.ags -o site.xml [--report findings.json] [--format text|json] [--fail-on error|loss] [--force]writes the DIGGS 3.0.0 document of the preview converter (mapping table 0.1) and prints every loss. Exit codes followpydiggs validate: 0, 1 for findings at or above--fail-on(error, the default, includes an output that fails validation;lossadds any loss), 2 for a usage error, an input that cannot be read or is not AGS4, or an output that cannot be written. Outputs are written to a temporary file and moved into place; an existing output is replaced only with--force, and the input is never overwritten.- HTTP API:
POST /v1/convertandPOST /v1/ags4/check./v1/converttakes an AGS4 file (rawapplication/octet-stream,text/plainortext/csv, or multipart) and answers one JSON object,ConversionResult: the DIGGS XML asoutput_base64withmedia_type,output_nameandoutput_sha256, the findingsreportabout the source, thevalidationof the output,complete,lossless,diggs_versionandmapping_version./v1/ags4/checkanswers the diggs-findings 1.1 (or SARIF) report of the AGS4 rules, and takes an optionaldictionarypart, since pyDIGGS bundles no AGS data dictionary. Both have the limits of/v1/read; a file that is not AGS4 is 422invalid-documentwithkindnot-ags4orunsupported-versionfor a conversion, and a finding for a check. The OpenAPI document describes both. - Stdio sidecar protocol 1.2:
convertandags4.check. A host that negotiates 1.2 gets both methods, advertised ascapabilities.convertandcapabilities.ags4_check; 1.0 and 1.1 sessions are unchanged and answermethod-not-foundfor them.convertanswers the sameConversionResultas the HTTP API;ags4.checktakesdictionary_base64ordictionary_path.openrpc.jsondescribes protocol 1.2. - The conversion and the check run in the browser (Pyodide) and give CPython's bytes; the Pyodide smoke now converts an AGS4 file and compares.
- Documentation: AGS4 files and AGS4 to DIGGS.
pydiggs.capabilities(): what this pyDIGGS can do, machine-readable. It returns aCapabilitieswith oneOperationper thing pyDIGGS offers (validate,read,detect,rules.list,rules.explain,ags4.read,ags4.write,ags4.check,convert.ags4-to-diggs,export.pandas,export.polars,gis.transform,export.geodataframe,export.gpkg,export.geoparquet,export.geojson): its stability (stable,previeworexperimental; the AGS4 and conversion operations arepreview), inputs and outputs (diggs-3.0.0,ags4-4.1.1,diggs-findings-1.1,diggs-model-1.0, media types), its options asOptionSpecs (type, default, choices, a plain-language label), the extras itneeds, and whether they areavailablehere. Availability is found without importing anything optional, so the same wheel answers correctly in Pyodide, where only the core is installed. An app can build its menus from it instead of from hand edits per release:
import pydiggs
for op in pydiggs.capabilities().operations:
print(op.id, op.stability, op.available)
Capabilities.to_dict() is a diggs-capabilities 1.0 document, with its JSON
Schema packaged (pydiggs.capabilities_schema(), CAPABILITIES_SCHEMA_VERSION,
CAPABILITIES_SCHEMA_URL) and published beside the findings and model schemas. The
same document is pydiggs capabilities --json on the command line (without --json,
a short table), GET /v1/capabilities on the HTTP server (off, like /v1/versions,
with versions_enabled=False), and the MCP server's new pydiggs://capabilities
resource. Every name is new; nothing existing changes.
- Plain-language rule guidance. Every rule in rule_catalogue() and every id
explain_rule() knows now has RuleInfo.guidance, a new Guidance object (title,
meaning, fix, locale) written for geotechnical and geoenvironmental engineers who
are not DIGGS or XML specialists: explain_rule("dictionary.5").guidance.title is
'Unknown code'. The field defaults to None (an unknown id), so existing code that
builds a RuleInfo is unaffected, and to_dict() gains a guidance key. The common
schema.cvc-* rules have their own text; other family members get their family's. The
HTTP /v1/rules routes, the sidecar's rules.* methods and the MCP explain_rule and
list_rules tools return it too (openapi.json and openrpc.json add the optional
guidance property). Findings documents are unchanged and stay diggs-findings 1.1:
apps look guidance up by rule_id. Only English ships; a test fails if any rule lacks
guidance.
Changed¶
- Validation is about a fifth faster on documents with many Schematron hits (40,000
boreholes: 3.4 s to 2.6 s), with the same findings byte for byte. Placing each
Schematron failure on its element evaluated rule contexts such as
*[local-name()='X'][parent::*[local-name()='Y']]as XPath over the whole document; lxml's tag filter now finds the same elements, in the same order.
Fixed¶
- A correct field plasticity term is no longer an error. The bundled Schematron rule
for
FieldProperties/plasticity, copied from the official DIGGS validation rules, required a number of zero or more, but in DIGGS 2.6 and 3.0 plasticity is a term such aslow,medium,highornon-plastic. Every correct value failed the file and a bare number passed. pyDIGGS drops that rule, soschematron.FieldProperties.plasticityis no longer reported or listed byrule_catalogue(). This is a known difference from the official validator, listed in the bundled Schematron file's header, and has been reported upstream (DIGGSml/validation#2). - Plain-language guidance for the plunge rule says what the official rule gets
wrong.
schematron.AbstractLinearSamplingFeature.plungeaccepts only -45 to -10 degrees, while DIGGS allows -90 to 90, so a vertical hole is outside it. (The rule names the abstract type, so it does not fire on aBorehole.) The guidance now tells users to keep a correct angle. Reported upstream (DIGGSml/validation#3).
1.9.0 - 2026-11-13¶
Added¶
pydiggs.ags4: read and write AGS4 files (the first part of AGS4 and DIGGS conversion).ags4.read(path)andags4.read_bytes(data)return aFileofGrouptables (name,headings,units,types,rows, and for a group that was read the sourcelineof its GROUP row androw_linesof its DATA rows, which take no part in equality), with every value kept as the text the file holds;ags4.dumps(file)andags4.write(file, path)write one back the same way every time (every field quoted, CR LF, groups in the order given), so a file that follows the rules is written back byte for byte.FileandGrouphave public constructors, andags4.AGS_VERSIONSlists the versions read and written (4.0.3 to 4.2). The module is new and nothing at the top level changes:
from pydiggs import ags4
f = ags4.read("site.ags")
f.version # '4.1.1', from TRAN_AGS
f.groups["LOCA"].records() # [{'LOCA_ID': 'BH01', ...}, ...]
f.notes # what reading had to work around, as findings
ags4.write(f, "copy.ags")
Reading is lenient, like pydiggs.read: a file that breaks the AGS4 rules still reads
and each workaround is a note (ags4.rule-4 for a short row, ags4.rule-5 for an
unquoted field, and so on; a missing UNIT or TYPE row is an empty units or types
and an ags4.rule-2b note, never a row invented, and dumps writes no row for it);
DocumentError (kind not-ags4 or unsupported-version) is raised only when no
table can be built. Text is read as UTF-8, and as Windows-1252 with an
ags4.encoding-assumed warning when it is not.
Every file is treated as untrusted: size, groups, headings, rows, cells, value length
and time (max_bytes, time_budget) are limited, a limit gives a partial file with
complete=False, nothing a file names is opened, and there is no network access.
The reader is written for pyDIGGS from the published AGS4 rules, with no new
dependency; no AGS data dictionary or AGS example file is bundled, and pyDIGGS is not
an AGS-approved tool. Conversion follows.
- pydiggs.ags4.check and pydiggs ags4 check: the AGS4 rules as findings.
ags4.check(path_or_file, dictionary=None) returns a Report (format="ags4", step
ags4) with one rule id per rule of section 4.1.1 of the AGS4 specification, Edition
4.2 (ags4.rule-1 to ags4.rule-20, including 2a, 2b, 10a to 10c, 11 to
11c, 16a, 18a, 19a, 19b), each with its line and its place in the file
(Finding.path, such as LOCA/3/LOCA_TYPE), plus ags4.formula-text (warning) for
text a spreadsheet would read as a formula. Messages name groups and headings, never a
value from the file. The rules that need the AGS4 data dictionary (7, 9, 10a, 10b,
10c, 18, and parts of 11c, 13, 14 and 19b) run for what the file's own DICT group
defines, and for standard groups only when you pass your own copy of the dictionary
with dictionary= (--dictionary); none is bundled, and an ags4.dictionary-not-checked
info finding says so. Rule 20's FILE folder is never opened. On the fixtures and the
14 BGS files python-ags4 checks in full, the rules that need no dictionary agree with
it, with two differences: pyDIGGS notes a UTF-8 byte order mark under Rule 1, and
reports a missing part of a combined abbreviation as Rule 16a where python-ags4 says
Rule 16.
$ pydiggs ags4 check site.ags --dictionary Standard_dictionary_v4_1_1.ags
site.ags: not-valid: 1 error(s), 0 warning(s), 0 info
site.ags:77: error ags4.rule-10a [XTST/2]: DATA row 2 of group XTST has the same KEY values as row 1.
The command takes --format text|json|sarif, --output, --fail-on,
--max-findings, --max-bytes and --time-budget, with the exit codes of
pydiggs validate. In SARIF, a finding's place in the file is a logical location
(locations[].logicalLocations[], with fullyQualifiedName such as XTST/2 and
kind element); SARIF for DIGGS files is unchanged. rule_catalogue() and
explain_rule() describe every new id.
- diggs-findings 1.1, which only adds to 1.0: the steps ags4 and convert
(Step.AGS4, Step.CONVERT; validate() never runs them), an optional
location.path for a place in a source that is not XML (Finding.path, for AGS4
GROUP/row/HEADING), and an optional files[].format (Report.format, "ags4" for an
AGS4 file). The new schema is packaged and published as
diggs-findings-1.1.schema.json; the 1.0 schema file is unchanged and still packaged
and published, and every 1.0 document is a valid 1.1 document.
- Preview: AGS4 to DIGGS conversion (pydiggs.preview.convert, outside Semantic
Versioning). convert.ags4_to_diggs(source) reads an AGS4 file (a path, bytes, a
stream or an ags4.File), writes a DIGGS 3.0.0 document and returns a Conversion:
xml, model (the document read back with pydiggs.read_bytes), report (the AGS4
reader's notes and the conversion's findings, as a findings report with format
"ags4"), losses, lossless, validation (the output validated), trace (the AGS4
row each node came from, as Origin(group, row, line)), mapping_version and
complete; save(path) writes the XML:
from pydiggs.preview import convert
c = convert.ags4_to_diggs("site.ags")
c.validation.ok # True: DIGGS 3.0.0 with no error
c.trace["BH01"] # Origin(group='LOCA', row=1, line=60)
for finding in c.losses: # what did not reach the output, or was written by default
print(finding.rule_id, finding.path, finding.message)
It covers the Tier A groups (PROJ, TRAN, the ABBR/UNIT/TYPE/DICT lookups, LOCA, GEOL,
SAMP, ISPT, LLPL, GRAG with GRAT, LNMC). Every non-null value of the source is either
carried into DIGGS or named by a finding of the new convert step:
convert.unmapped-group, unmapped-heading, user-defined, unmapped-code,
unmapped-unit, value-unparsed and assumed (warnings), orphan-row and
incomplete (errors), and value-reformatted (information, not a loss). One finding
is given per group, heading or reason, with a count, and location.path names the
first place as GROUP/row/HEADING. Values are carried as reported: units are renamed
only through the unit table, a measure is written only with a unit DIGGS 3.0.0 allows
for its element, grid coordinates only in the unit of their CRS's axes, and nothing is
converted numerically; codes and grid references are mapped only where the bundled
DIGGS code lists support them; nothing the file names is opened; and the same file
always gives the same bytes. max_bytes limits the AGS4 input only: the DIGGS XML,
often many times larger, is read back and validated whatever its size.
time_budget is seconds for the whole call (reading, converting, validating and
reading back each get what is left). When it runs out, complete is False and the
output is partial (convert.incomplete names what was not converted, or model
holds the members read back so far), except during validation, which gives
validation a structure.timeout error instead. Writing the XML and a running
libxml2 call are not interrupted, so the call can overrun the budget by that much.
- The AGS4 to DIGGS mapping table (version 0.1), data that can be reviewed and
corrected: src/pydiggs/convert/mappings/ (ags4-diggs.toml, units.toml,
codes.toml), with its own JSON Schema (convert-mapping-1.schema.json) and a
generated page, AGS4 to DIGGS mapping.
Every group is a draft; mapping table 1.0 is signed off with pyDIGGS 1.10, when
conversion becomes stable in pydiggs.convert. convert.mapping_info() describes
the table. It holds only AGS4 group and heading names, keys and parents, and no text
from the AGS4 data dictionary.
Changed¶
- Contributions are signed off under the Developer Certificate of Origin. Every commit
in a pull request needs a
Signed-off-byline (git commit -s), checked by a newDCO sign-offjob; there is still no contributor licence agreement. The terms are in the newCONTRIBUTING.md, and pull requests get a short checklist template. - Licensing is now documented file by file. A top-level
NOTICEfile lists the attributions to keep when you redistribute pyDIGGS, including the bundled Energistics, OGC and EPSG material that the licence metadata did not name before. The wheel ships it with the third-party licence texts in.dist-info/licenses/. Every file in the repository has its copyright and licence recorded inREUSE.toml(REUSE 3.3), checked in CI. A new Licence and use page says what you may do, what you must do when you redistribute, and what a pyDIGGS check does and does not tell you about engineering data. The pyDIGGS licence is unchanged (Apache-2.0). - The package's licence metadata now names every licence it contains:
Apache-2.0 AND MPL-2.0 AND MIT AND LicenseRef-Energistics-PLA AND LicenseRef-POSC-LA AND LicenseRef-OGC-2001 AND LicenseRef-EPSG-TOU AND LicenseRef-DIGGS-Unstated AND LicenseRef-OASIS(the container image label likewise, without the test-only OASIS entry). If your SBOM or licence scanner allows only SPDX-listed licences, it will now flag pyDIGGS for review; the terms behind eachLicenseRef-are inLICENSES/and on the Licence and use page, which now has a checklist for products that include pyDIGGS. The units dictionary is now recorded as containing Energistics definitions, as it says itself. - The 26 unused Energistics schemas in DIGGS 2.6's
witsml/2.0/RemovedFromProfile/are no longer bundled: DIGGS 2.6 does not import them, so validation is unchanged, and the Energistics agreement does not allow redistributing them unmodified. pydiggs.previewwarns when one of its deprecated read-API names is used, rather than when it is imported, so thatpydiggs.preview.convertcan be imported without a warning. The deprecated names and their removal in 2.0 are unchanged.- Findings documents now declare diggs-findings 1.1:
$schemais the 1.1 URL andschema_versionis"1.1"(FINDINGS_SCHEMA_URL,FINDINGS_SCHEMA_VERSION,findings_schema(), the HTTP API's OpenAPI document, the sidecar's OpenRPC document and the MCPoutputSchemafollow). Nothing else in a document about DIGGS files changes: the two new fields are written only for AGS4. If you check documents against the 1.0 schema, move to the 1.1 schema, because the 1.0 schema accepts only its own$schemaURL:
jsonschema.validate(document, schema_1_0) # 1.8.0
jsonschema.validate(document, pydiggs.findings_schema()) # 1.9.0
GET /v1/rules?step= and the rule catalogue accept and list the ags4 step.
- Reading into JSON is about a fifth faster (/v1/read, @pydiggs/client): writing a
model out as JSON (Model.to_json) takes half the time, and reading a tenth less,
with the same bytes as before. The JSON encoder looked up each class's fields for
every value it wrote, the decoder spelled out a location string for every field in
case of an error, and the reader made a counter for every element; each now does that
work once.
Fixed¶
- The service layer behind
pydiggs serve --http, the sidecar and@pydiggs/clientno longer imports networking modules on Python 3.14. Hiding install folders in finding texts calledPath.as_uri(), which from 3.14 importsurllib.requestand with ithttp.client,socketandssl; nothing was sent, but the core path promises never to import them, and in a browser they were dead weight. Thefile:spelling is now built directly. - The source distribution holds only the Python package again. The 1.8.0 sdist also
carried the npm package's sources (
js/),.github/scriptsand an example script, because its include patterns matched at any depth. The wheel was not affected.
1.8.0 - 2026-11-11¶
Added¶
- MCP read tools (the
mcpextra):list_features(a page of the document's features, with how many samples and measurements refer to each),get_feature(one feature as diggs-model 1.0, with its samples, measurements and lithology layers),list_measurements(a page of the measurements and other holders of result tables, including those that name no feature; filter by feature or procedure) andget_results(a page of rows of one result table, with its columns described). Each answers typedstructuredContentwhoseoutputSchemais built from the frozen diggs-model 1.0 definitions, and a text summary of counts only. Pages continue with a short opaquenext_cursortied to the document and the request. Every string from the file is cut to 512 characters (node keys at 4,096, so they can be sent back), a result is at most 1 MiB, and the tool descriptions say file text is untrusted. They sharevalidate_diggs's limits (10 MiB, one worker, 60 s); the worker keeps the models it read lately, so the calls after the first do not parse the file again.
Changed¶
pydiggs.framesresultsview: a result column namedposition,top,base,timeorelapsed_timeis now always<name>_value(those names say where a row is). In 1.7.0 a measuredelapsed_time, as in a Lugeon or dissipation test, could be the frame columnelapsed_time; it is nowelapsed_time_value, whatever filters are used:
frame = frames.to_pandas(model, "results", procedure="LugeonTest")
frame["elapsed_time"] # 1.7.0
frame["elapsed_time_value"] # 1.8.0
timeout error text says the file was not checked or read.
Fixed¶
- Stdio sidecar: a session that negotiated protocol 1.0 gets
method-not-foundforread, as documented, instead of an answer. pydiggs.framesresultsview: a result column named like an index column of another table in the same frame (top,position…) no longer shares that column with the places of the other table's rows (see the naming rule under Changed).
1.7.0 - 2026-11-11¶
Added¶
- The read API is stable.
pydiggs.read(),pydiggs.read_bytes(),pydiggs.Model,pydiggs.model_schema(),pydiggs.MODEL_SCHEMA_VERSION,pydiggs.MODEL_SCHEMA_URLandpydiggs.DocumentErrorare top-level, andpydiggs.modelandpydiggs.crsare public modules covered by Semantic Versioning. The model is diggs-model 1.0 (schemas/diggs-model-1.0.schema.jsonon the docs site), frozen: from here it changes only by minor versions that add, as the docs' Versioning section describes. read(..., provenance="field"): every node'sprovenance.fieldssays where each of its values was read (the element's xpath relative to the node, and its line).- Depths along a linear referencing system that names a method in the DIGGS registry
(
lrm.xml#md_ft,#md_m…) get that method's unit. The registry's methods are packaged with pyDIGGS (from DIGGSml/def), so nothing is fetched. - Read note
structure.duplicate-gml-id(warning): two or more elements share onegml:id. Each copy is keyed by its xpath, and a link to the id resolves to the first. pydiggs.crs.SUPPORTED_SRS_FORMS.- Reading has work limits, so a small hostile file cannot produce a huge model: at most
100,000 objects, and as many elements with no typed field, plus one of each per 200
bytes of the file, nested at most 64 deep (real files have a few thousand, over 1,000
bytes apiece and about 10 deep). Reaching one returns what was read with
complete=False, the limit inlimits_hitand astructure.read-limitnote. A namespace URI longer than 1,024 characters is refused (DocumentError, kindnamespace-too-long), asvalidatealready does. - HTTP API:
POST /v1/readreturns the diggs-model document for an uploaded file, with the same limits, isolation and problem responses as/v1/validate. Bytes that are not a DIGGS document are 422invalid-document(withkind). The OpenAPI document carries the model schema asDiggsModel*components. - Stdio sidecar: a
readmethod, in protocol 1.1 (1.0 hosts are answered as before). New errorsinvalid-document(-32010) andresult-too-large(-32011);initializereportsmodel_schema_version,model_schema_url,capabilities.readandlimits.max_result_bytes. - On both,
select({"results": "all" | "none" | [node keys]}) chooses which result tables keep their values, so a host can list a large file first and fetch tables after. Every surface returns the bytespydiggs.read_bytes(...).to_json()gives. - Data frames:
pydiggs.frames.to_pandas()(the newframesextra) andto_polars()(thepolarsextra) give a model's features, samples, lithology layers, measurements or result tables as a data frame, with filters by feature, kind, procedure and measurement, and result values in SI units on request. - GIS:
pydiggs.gis(the newgisextra: geopandas, pyproj, shapely, pyogrio, pyarrow).transform()gives every position in an EPSG or OGC CRS a longitude and latitude in the CRS you choose and records that it did;to_geodataframe()gives the features as points;write()saves them as GeoPackage, GeoParquet or GeoJSON.import pydiggsimports none of these libraries. - Browser (Pyodide):
read_bytesis tested in Pyodide, byte for byte against CPython, and the Web Worker example shows what a file contains after validating it.
Changed¶
- diggs-model documents say
"schema_version": "1.0"(1.6.0 wrote1.0-beta.2; the betas stay published underschemas/preview/). Every node'sprovenancehas afieldsmember,nullunlessprovenance="field"was asked for.
Deprecated¶
pydiggs.preview: importing it warns. Use the same names frompydiggs. It will be removed in 2.0.
Fixed¶
- Reading from several threads at once could, on the first reads in a process, build a model with fields missing; the decoder's setup is now safe to share.
read()rejects atime_budgetthat is not a finite number (NaN or infinity) withValueError, instead of reading with no limit.
1.6.0 - 2026-11-10¶
Added¶
- Read API (preview):
pydiggs.preview.read(path)andread_bytes(data)read a DIGGS 2.5.a, 2.6 or 3.x file into aModel(diggs-model 1.0-beta.2): features, sampling activities, samples, lithology layers, measurements with every result table as typed columns, links between them, a CRS table, and notes on what reading had to work around. Files are parsed one top-level member at a time, nothing is fetched, andModel.to_json()is deterministic and round-trips throughModel.from_json(). The node and value classes are inpydiggs.model, the schema inpydiggs.model.model_schema()and on the docs site. Preview: names may change before 1.7.0 freezes diggs-model 1.0. - Read API coverage (diggs-model 1.0-beta.2):
- Every node and procedure keeps its simple values in
params(aQuantity, aCodeor text), so every test has typed parameters: SPT hammer efficiency and penetration, CPT tip area and area ratio, and the rest. - Nested records are
Componentnodes with their own keys: borehole and well construction (method, casing, backfill, hole diameter, openings, events), water strikes and their readings, SPT drive sets, CPT cones, sieve analyses, lithologies. - A well's
parenthole; a sample's depth, method and recovery from its sampling activity; a lithology layer's classification, colour and geologic unit; a test'sresult_time. - Result tables say where each row is:
domain.indexcolumns for CPT depths, stepped intervals, water-level times and elapsed times, and anextentfor tests measured over one interval. Depths take the unit of the borehole's linear referencing system when the file states it. pydiggs.crs(preview):parse()ansrsName, andepsg()facts (name, type, axis order, unit, datum) from a packaged subset of the EPSG Dataset (owned by IOGP, used under its terms of use). The model'scrstable andgeographicpositions use them.pydiggs.errors.DocumentError(aValueError): raised by the read API when the bytes are not a DIGGS document at all.- Rule
structure.value-unparsed(info), used by read notes. - Documentation: a "Stay updated" page on how to follow new releases (GitHub release notifications, the releases feed, PyPI's feed, and an email list for feature releases).
Security¶
- GitHub releases are immutable from 1.6.0: a published release's files cannot be
changed, and its
v*tag cannot be moved or reused. A release that needs a fix gets a new patch version. - Release tags are signed by a maintainer's key, and the release workflow refuses to
publish from a tag that is unsigned or signed by a key not listed in
.github/release-signerson the default branch (never the copy in the tagged commit). Only a pushed tag publishes to PyPI; a manual run of the workflow stops at TestPyPI. Check a release withgit -c gpg.ssh.allowedSignersFile=.github/release-signers verify-tag vX.Y.Z.
1.5.0 - 2026-11-09¶
Added¶
- Experimental
3.1-devprofile: the unreleased DIGGS 3.1 draft schema from DIGGSml/schema-dev (branch3.1-dev, pinned by commit). Use it withdiggs_version="3.1-dev"or--diggs-version 3.1-dev; it is never auto-detected and never the default, so results for existing files do not change. When the schema step checks a file against it, the report carries a newschema.unreleased-profilewarning. - Four checks adapted from the DIGGS File Inspector, in
validate()findings:geometry.reported-depth-mismatch(atotalMeasuredDepthmore than 2 % off itscenterLinelength, when the file states its axis units),geometry.crs-axis-order-suspect(geographic coordinates that look like longitude, latitude),geometry.crs-unresolvable(ansrsNamethat is not a recognised EPSG or DIGGS reference nor an element in the file) andcontext.xlink-remote-unresolved(info: a link into another document, which pyDIGGS does not fetch). The legacycontext_checkoutput does not change. - Documentation: a draft of diggs-model, the data model the read API will return from
1.6.0, with its JSON Schema and an example under
schemas/preview/on the docs site ("Reading files (draft)"). Nothing in this release reads files into it yet; comments are welcome before it is frozen in 1.7.0. - A conformance corpus in the repository (
conformance/): the DIGGSml examples plus real-world files from the DIGGS File Inspector, pinned by commit and sha256, each with the outcome pyDIGGS gives (expected.toml) and what a reader must produce from it (model.toml). Other DIGGS tools can be checked against the same files withscripts/conformance.py.
Changed¶
version_info().diggs_versionsand thediggs_versionchoices on every surface (Python, command line, HTTP, sidecar, MCP) include3.1-dev.warm_up()with no argument still warms only the released versions.- Each report's
reference_dataalso names the pinned DIGGSml/schema-dev commit.
Fixed¶
- Deprecations introduced in DIGGS 3.1 now apply to the 3.1 profile; a version with a
pre-release suffix such as
3.1-devwas ordered as 3.0.
Security¶
- The container image upgrades zlib1g to the Debian fix for CVE-2026-76844 and CVE-2026-85091; the image build fails if the fixed version is not installed.
1.4.1 - 2026-11-05¶
Added¶
- Documentation site: a Quickstart (install, validate a file, read the findings, use them from Python and CI), an integration chooser that compares the Python API, command line, HTTP API, container, stdio sidecar, MCP server and browser build, and a Python API reference generated from the docstrings.
Changed¶
- Documentation site navigation follows the reader's journey: Get started, Guides, Integrate, Reference and Project tabs, with breadcrumbs, a home page that routes each kind of user to their path, linked Python and command-line tabs, an automatic light or dark theme, and "Edit this page" links.
- Package metadata names the author and maintainer as "Xin Peng" (was "xin.peng"). The README and the Authors page list Xin Peng as project lead and Asitha Senanayake as contributor.
- Container image: built on Python 3.14.10 (was 3.14.8), with uv 0.13.7 in the build stage; the build and runtime stages carry the same Python patch release. The image's locked FastAPI is 0.159.1 and Pydantic 2.14.1.
Fixed¶
- Code blocks on the documentation site no longer show a second, unstyled "Copy" label under the theme's own copy button, and links inside a page work normally again.
- The documentation site no longer shows a cookie consent banner: it sets no cookies that need consent.
- Docstring examples render as highlighted code in the API reference (their headings
are now
Examples:).
1.4.0 - 2026-11-04¶
Added¶
pydiggs --version(or-V) prints the installed version.- MCP server (
pip install 'pydiggs[mcp]', thenpydiggs serve --mcp): AI assistants and other MCP clients can validate a DIGGS document and look up rules over stdio. Four read-only tools:validate_diggs(a base64 document in, a whole diggs-findings document out, equal topydiggs validate --format jsonapart from the path and the limits below),explain_rule,list_rulesandsupported_versions. The text the model reads is a fixed-template summary that never contains text from the file. Limits: 10 MiB, 200 findings, 512-character messages, one validation at a time with a hard 60-second timeout. No path, network access or local dictionary is ever used. See the new "MCP server" page. pydiggs.mcp_server.create_server()returns that server (the official MCP Python SDK'sMCPServer) for embedding and tests.- The
mcpextra:mcp>=2.3.0andpython-multipart>=0.0.31. - Browser support, tested: pydiggs runs in a web page with Pyodide 314.0.7, so a
DIGGS file can be checked without leaving the user's machine. A new example,
examples/browser-worker, validates in a module Web Worker (Pyodide loaded once with an integrity hash or self-hosted, pydiggs installed withdeps=False, 25 MiB limit, findings rendered as text only, a strict Content-Security-Policy). CI now installs every build into that Pyodide and checks its reports are byte-identical to CPython's. See the new "Browser (Pyodide)" page. - Container image
ghcr.io/xinp-hub/pydiggs:X.Y.Z(also:X.Y; there is nolatest) forlinux/amd64andlinux/arm64: the HTTP API on port 8000, built from the exact wheel published to PyPI and the locked[server]dependencies, onpython:3.14-slim-trixie, running as uid 10001 with no package installer inside and a/livezhealth check. SetPYDIGGS_ALLOWED_HOSTSto the names clients use. Each image has a GitHub build provenance attestation (gh attestation verify), BuildKit provenance and an SBOM. A release image is pushed by digest and scanned for vulnerabilities before its tags point at it; the image built from every pull request is scanned too. See the new "Container image" page for the hardened run line, a compose example and memory sizing. constraints-X.Y.Z.txton every GitHub release: the dependency versions the release was tested with, to pass to pip with-c.- The OpenAPI document (
openapi.json) and the sidecar's OpenRPC document (openrpc.json) are published on the documentation site underschemas/, and CI checks both against their official meta-schemas.
Changed¶
pydiggs serve --mcpis listed in--help. Without themcpextra it exits 2 and namespydiggs[mcp], as--httpdoes forpydiggs[server].import pydiggsand validation no longer loadurllib.request,http.client,socketorssl; they are imported only for anallow_network=Truedownload.
Fixed¶
- The documentation's release history now has its 1.2.0 entry.
- The documentation site's "Edit this page" links point at the
masterbranch.
1.3.0 - 2026-11-03¶
Everything here is additive: 1.2.0 code, CLI output and exit codes are unchanged.
Added¶
validate_bytes()checks a DIGGS document held in memory:bytes,bytearray,memoryviewor a binary stream. It applies the same checks and safety limits asvalidate(), never reads local dictionaries, and takes a displayname.time_budget=onvalidate()andvalidate_bytes(): a soft time limit checked between steps. A report that runs out of time has onestructure.timeouterror and its unfinished steps areincomplete, the same shape aspydiggs validate --timeout.warm_up()compiles the bundled validators ahead of the first call.- Findings documents and schema:
Report.to_document(),findings_document(),findings_json(),findings_schema(),FINDINGS_SCHEMA_VERSIONandFINDINGS_SCHEMA_URL. version_info()(VersionInfo): package version, findings schema, DIGGS versions and reference-data commits.rule_catalogue()andexplain_rule()(RuleInfo): every rule id pyDIGGS can emit, with its step, severities and description.- HTTP API,
pydiggs[server].create_app()/create_router()for FastAPI andpydiggs serve --http:POST /v1/validate(raw XML or multipart),GET /v1/versions,GET /v1/rules[/{id}], health probes, RFC 9457 problem details and a committed OpenAPI 3.1 document. By default, validation runs in isolated worker processes with hard timeouts. Request size, admission, Host and cross-site checks are enforced inside the route. See HTTP API. - A request body must arrive within
body_timeout_s(PYDIGGS_BODY_TIMEOUT_S, default 30 s) of admission; otherwise the answer is 408request-timeoutand the admission slot is freed. checksmust match the documentedstep(,step)*pattern of at most 512 characters; blanks, empty items and longer values are 422invalid-parameter.- On SIGTERM or SIGINT,
serve --httpwaits at mosttimeout_splus 5 s for requests in flight, then cancels them and exits. - Worker processes write no core file (POSIX), and
create_router()logs the same thread-isolation warning ascreate_app(). - uvicorn does not time out slow request headers: put any non-loopback deployment behind a reverse proxy with client header and body timeouts.
- Stdio sidecar for native apps,
pydiggs serve --stdio. A JSON-RPC 2.0 protocol over newline-delimited JSON on stdin and stdout, with an OpenRPC description. Any desktop or native host (Tauri, Electron, Qt, .NET, Java, Swift…) can drive pyDIGGS as a child process. Files are sent as content by default; reading by path works only inside folders the host grants with--allow-path. Uses the standard library only. See Stdio sidecar and Host integration. - A path that, as spelled, is not under a root (given or canonical spelling) is refused before it is opened. Hard links into a root are not contained.
--max-bytes, when given, is also the by-path limit (100 MiB otherwise).- JSON nested deeper than 64 levels is a parse error on every Python version.
pydiggs serve --mcpis reserved for the MCP server planned for 1.4.0: it is hidden from--helpand exits 2. There is no[mcp]extra in this release.python -m pydiggsruns the CLI.
Changed¶
import pydiggsno longer imports rich; the CLI loads it when it prints. rich is still a dependency.pydiggs validate --timeoutruns files on a supervised worker process, which is replaced after a timeout or crash. Output and exit codes are unchanged.- The SARIF short description of
structure.timeoutis now "Validation did not finish within its time limit".
Fixed¶
- SARIF
file:URIs (--absolute-paths) no longer usePurePath.as_uri(), which is deprecated in Python 3.14; the URIs are unchanged.
1.2.0 - 2026-10-23¶
Upgrade note: some files that passed under 1.1.1 now fail, and the reverse.
- Dictionary check 5. The bundled DIGGS dictionaries are now exact copies of
diggsml.org/def. pyDIGGS 1.1.1 and earlier had added eight codes to its copies of
properties.xmlandroles.xml(areaRatio,cloudCover,coneDiameter,depthToWater,geotechnicalEngineer,obstructionType,pushRate,siteName) that the official dictionaries do not define. Files using them now faildictionary_check(), as they do in the official DIGGS validator. - DIGGS 2.6 schema. Upstream corrected the required element
samplingFeatiureReftosamplingFeatureRefinGeophysics.xsd. 2.6 files that spell it the old way now failschema_check(), and files with the corrected spelling now pass.
Changed¶
- Dictionary checks 8 to 12 name a property with several names by its first name in the dictionary; they used Python set order, so the text could change between runs. No example in the test corpus is affected.
pydiggs --helpnow points topydiggs validate --help. The legacy subcommands, their console output, exit codes and log files are unchanged (checked byte for byte against 1.1.1 by a golden test suite).- Re-synced the bundled reference data to DIGGSml/schemas
15ce278(9 October 2026) and DIGGSml/def2d76ba6(8 October 2026): - 2.6
Geophysics.xsd: upstream fixed the element namesamplingFeatiureReftosamplingFeatureRef. - Dictionaries: 57 more code lists (83 in all) are available offline, including the
pile and rigid-inclusion lists; the existing lists now declare the DIGGS 3
namespace, and
properties.xmlandDiggsUomDictionary.xmlfollow upstream. mwd_properties.xmlandpil_properties.xmlare now the official copies rather than local supplements.- Upstream directory-listing pages (
index.html) and.gitignorefiles no longer ship in the wheel.
Added¶
- Machine-readable findings.
pydiggs.validate(path)runs every native check on one file and returns aReportofFindings, each with a stable rule id (schema.cvc-complex-type.2.4,dictionary.5,schematron.Borehole.totalMeasuredDepth, ...), aSeverity, aStep, the line, the official DIGGS XPath and the nearestgml:id. It prints nothing and writes no files, and raises onlyInstanceReadError,ResourceError(bothPydiggsErrors) andValueError; XML that is not well-formed is a finding. New public names:Finding,Report,Severity,Step,validate,PydiggsError,InstanceReadError,ResourceError. pydiggs validate PATH...with--format text|json|sarif,--output,--checks,--fail-on error|warning,--snippets,--absolute-pathsand--allow-network. Directories are searched for*.xml; exit codes 0 (clean), 1 (findings), 2 (usage error or unreadable input).- The diggs-findings 1.0 JSON format, with its JSON Schema shipped in the package and published at https://xinp-hub.github.io/pydiggs/schemas/diggs-findings-1.0.schema.json, and SARIF 2.1.0 output for code-scanning tools. Output is deterministic, has no timestamps, and by default carries no source snippets and no absolute paths.
- Limits for
validate(): at most 10,000 findings per file by default (max_findings,--max-findings; the overflow is counted in onestructure.findings-truncatedfinding and the affected steps areincomplete), and instances up to 100 MiB by default (max_bytes; the legacyvalidatorkeeps 1 GiB).--max-bytessets the size limit from the command line. Each finding's message and xpath are capped at 4,096 characters, and a report's findings at about 16 MiB. validate(local_dictionaries="instance-dir" | "off")and--local-dictionaries: by default a dictionary named by a relative orfile:codeSpace is read only from inside the instance's folder (no working-directory fallback, no escape through..or symlinks).dictionary_check()is unchanged.- In
validate(), local dictionaries are read once per file however their path is spelled, undermax_bytes, only if they are regular files, and at most 16 per instance, within one byte budget shared with the instance. - Fail closed: a step that cannot finish (a libxml2/libxslt limit, a deprecation XPath
that cannot be evaluated, or a file with more than 9,900,000 elements) is
incompletewith a<step>.incompleteerror, never a pass. pydiggs validate --timeout SECONDS(at most one day) validates each file in its own process and reports a file that does not finish as astructure.timeouterror. With or without it, an unexpected error for one file becomes astructure.internal-errorfor that file (the exception type and a short text, with the file's path scrubbed) and the batch goes on.- In
validate(), the Schematron step (bundled or user rules) is skipped with aschematron.incompleteerror when an element has more than 50,000 child elements, where libxslt can take minutes; the casing diameter rule still runs.schematron_check()is unchanged. - In
validate(), the Schematron step (bundled or user rules) is also skipped with aschematron.incompleteerror when the rules would fire on more than 100,000 elements, counted in linear time before they run: libxslt's time grows with the square of the number of elements the rules fire on, whatever their parents. - In
validate(), dictionary Checks 6 to 8 try each element only against the definition paths that can name it, a Definition may list at most 1,000 paths or names, and path matching may take at most 5,000,000 steps per instance; past either limit the step isincompletewith adictionary.incompleteerror. Check 6 and 8 messages list at most 20 paths. Each Definition is read once per instance (it may have at most 10,000 nodes, and a path at most 64 steps), a property'stypeData,uomandnullValuesiblings are found once per parent, and sibling reads count towards the same budget. Check 13 has one budget of its own (250 million units): every character it reads and every element,index, group, reference, token, field and merged value it examines or keeps is charged, so no Check 13 loop is unbounded and what it keeps stays under 1 GB. The weights are calibrated so that a unit costs about the same time in every loop (scripts/calibrate_check13.py, which exits 1 if any loop costs more than 30 ns a unit on the machine it runs on; on an Apple M3 Max the worst loop is about 25 ns, the median of three runs, so the whole budget is about 6 s there and 13 to 26 s on hardware two to four times slower; data-shaped 10 MB files use 21 to 23 % of it, the densest shape tried 59 %). A propertyindexis parsed once, in the layout pass, and an index longer than 64 characters is not a column. A column's values over a group's ResultSets are merged once for all the group's properties, and eachindexbelongs to its nearest PropertyParameters only, so nested PropertyParameters are not re-read. - In
validate(), a file whose internal-DTD entities make its parsed text more than twice its raw size gets onestructure.entity-expansionerror and no other check runs (human decision). Small text entities such as°still work. - The diggs-findings 1.0 format (not yet released, so changed in place): each file has
a
verdict(valid,valid-with-warnings,not-valid,partly-checked,not-diggs,unreadable); a file whose root is notDiggshas statusnot-diggs,diggs_versionnull and every step butstructureskipped; and a step can bepartial(the dictionary step when a code list could not be fetched offline), so an offline-unchecked step is neverpassed. Text output starts each file's line with its verdict, and a partly checked file gets a line naming its unfinished steps plus itsdictionary.offlinefindings (shown although info findings are not); SARIF carries status and verdict in each artifact's properties. The JSON Schema ties status to verdict (anot-diggsfile has verdictnot-diggsand nodiggs_version), andReportrefuses an unknown status. - In
validate(),geometry.srs-attributesfollows the official geometry module (human decision): it checks the module's nine objects (LinearExtent,MultiPointLocation,MultiCurve,Solid,PointLocation,PlanarObservationRepresentation,PlanarSurface,MultiPlanarSurface,RectifiedGrid) with or without coordinates, and no longergml:Point,LineString,Polygon,Curve,Surface,MultiPointorMultiSurface. No warning when the object or an ancestor declares both attributes, one best-practice warning when only the childgml:pos/gml:posListdoes, and one warning per object otherwise (two before; the official module makes that an error). The rule is one pass over the tree.context_check()is unchanged. - In
validate(), a namespace URI longer than 1,024 characters gives onestructure.namespace-too-longerror and no other check runs (human decision). The 2x expansion check now runs whenever there is an internal DTD, counts UTF-8 bytes, and includes ATTLIST defaults and namespace URIs. - In
validate(), Check 13 keeps no copy of each ResultSet's rows, only the distinct values of the columns its properties ask for. Each ResultSet is read in one streaming pass for all the PropertyParameters it holds (those whose nearest ResultSet it is, at any depth, the same rule that decides where a property's values come from) or cites byxlink:href; the pass collects every column any of them asks for and splits each row no further than the last of those. Column sets are built once per PropertyParameters and shared between ResultSets; dataBlock arity is checked in constant time per (dataBlock, measurement); and a file whose path is not valid UTF-8 is passed to libxml2 as afile:URI. - In
validate(), any unexpected error inside a step is that step'sincompleteerror instead of an exception, and the remaining per-element work in the dictionary checks (candidate paths, Check 13 values and terms, ancestor names, memos) is cached or counted towards the work budget. In the context step, Properties fordataBlockarity are counted in one pass (same messages ascontext_check()). - In
validate(), a/inside a predicate of a definition path (for example[text()="electrical resistivity (ERI/ERT)"]) no longer splits the path. - In
validate(), Check 8 reads//in a definition's conditional paths as "any descendant".dictionary_check()keeps reading it as a direct child, which skips Check 8 under a measurement; the two AtterbergExample files in the test corpus therefore get twodictionary.8errors fromvalidate()only. - In
validate(), a local dictionary with a markup entity in its internal DTD, or one libxml2 refuses for a resource limit, is adictionary.incompleteerror instead of adictionary.3warning. - In
validate(), local dictionaries are limited to 20 MiB in all per instance (a parsed dictionary takes about 35 times its size in memory); a codeSpace not read because of that limit or the 16-dictionary cap makes the dictionary stepincompletewith adictionary.incompleteerror. - Schematron runs without lxml's location strings (
generate-paths=false); pydiggs locates each failed assert from the rule contexts, which bounds memory per failure. validate(dictionary_path=...)uses that dictionary for every properties URL; indictionary_check()the bundledcodes/properties.xmlstill replaces it (1.1 behaviour, unchanged).validate(base_dir=...)and--base-dirreport paths relative to a chosen folder. Without it, paths are bare file names when the working directory is/or an ancestor of the home directory.- In
validate(), a whitelisted remote dictionary that is not bundled is reported asdictionary.offline(info) when network access is off, instead of a Check 3 warning, so--fail-on warningdoes not fail a file just for being checked offline. - Two checks in
validate()only (not indictionary_check()): dictionary Check 13, which requires result values of a property whose definition names avalueCodeSpaceto be terms of that code list, and a deprecation check against the bundled DIGGS deprecation registry (deprecated items warn, removed items fail). Registry entries apply only from the release they name, so its 3.1.0 entries never fire on 3.0.0, 2.6 or 2.5.a files. pydiggs/PROVENANCE.tomlrecords the upstream commit and a sha256 for every vendored file.scripts/sync_reference.pyre-syncs from local clones of the DIGGSml repositories, reading files from the pinned commit's git objects rather than the working tree, refuses unsafe or non-portable file names, and verifies the digests (check, run by the test suite).validate()escapes control, bidi-override and line-separator characters from the instance in every finding's message and in the reported path (as\u202e,\x85), so no output format can show reordered or hidden text, and replaces the home folder with~in messages. SARIF messages escape[,]and\, so text from a file can never become a link in a code-scanning viewer.pydiggscallsmultiprocessing.freeze_support(), so--timeoutworks when pyDIGGS is frozen into an executable (PyInstaller), as in a desktop app.- The DIGGS deprecation registry (
deprecation/DeprecationRegistry.xml) is bundled for the deprecation check above. It lists 94 deprecated items (25 from DIGGS 3.0.0, 69 from 3.1.0) and 56 items removed in 3.1.0. - The DIGGS schemas' MPL-2.0 license ships at
schemas/LICENSE, anddictionaries/NOTICErecords the licence terms for the DIGGSml/def dictionaries. The package licence expression is nowApache-2.0 AND MPL-2.0 AND MIT, matching what the wheel contains.
Performance¶
- The bundled Schematron rules match
*[local-name()='C'][parent::*[local-name()='P']]instead of the equivalent//*[local-name()='P']/*[local-name()='C'], which libxslt evaluated in time growing with the square of the number of siblings (a 1 MB file with 18,000 sibling features took 31 s of CPU; now 0.1 s). Verdicts, failures and theschematron_check()output are unchanged, and the rule ids are the same. libxslt is still quadratic in the number of elements the rules fire on;validate()refuses files where that is over 100,000, or where one element has more than 50,000 children. - Creating a
DictionarySemanticValidatorparses each bundled dictionary once instead of once per URL form, which more than offsets the larger dictionary bundle.
Security¶
validate()andpydiggs validatetreat everything in an instance as data: the element paths in libxml2's schema messages (which can carry the instance's namespace URIs) are checked against a strict grammar and resolved by walking the tree, never evaluated as XPath, and Schematron failures are located from the trusted rule contexts, not from the report's location strings. Only regular files are read (a FIFO cannot block); messages about unreadable files carry no path;--outputcreates new files with mode 0600, keeps an existing file's mode, and never writes through a symlink; text output escapes control and bidi characters. A broken user Schematron file is aResourceError(exit 2).- In
validate(), an instance whose internal DTD declares an entity with markup (<) in its value gets onestructure.markup-entityerror and no other check runs, so an entity cannot multiply the tree past the limits; this holds in every encoding the parser reads, including UTF-32 with a BOM. Entities with plain text still work. The element limit is counted on the parsed tree (an entity or a UTF-7 file cannot hide elements from it). dictionaries/whiteList.xml, which decides whereallow_network=Truemay fetch dictionaries from, is maintained in pyDIGGS and digest-checked rather than synced from upstream, so a data update cannot widen it.
Tests¶
- The official example corpus is synced to DIGGSml/diggs-examples
79da841(4 October 2026). Four examples that upstream fixed now pass every check and moved into the valid corpus (2.6FieldSurveyExample, 2.6ODOT_Example_2_20180702-from25, 3.0Aeromag, 3.0GeophysicalFieldSurveyExamples).PileDrivingExamplemoved toknown_invalid: upstream rewrote it with DIGGSml/schema-dev types while it still declares 3.0.0.
1.1.1 - 2026-10-14¶
First published release of the 1.1 line. 1.1.0 was tagged but never reached PyPI,
because the release workflow failed before upload. 1.1.1 contains everything listed
under 1.1.0 in the changelog,
including the security hardening and the upgrade note: dictionary Check 12 (invalid unit
of measure) is an error again, so files that only warned under 1.0.0 now fail
dictionary_check(). There are no other changes to the package.
Fixed¶
- Release workflow: the post-TestPyPI smoke install used a system Python that does not exist on the runner, so it failed before the PyPI upload.
1.1.0 - 2026-10-14¶
Tagged but not published to PyPI; use 1.1.1.
Upgrade note: dictionary Check 12 is an error again (see Changed). Files that use a
unit of measure outside its quantity class, and only warned under 1.0.0, now fail
dictionary_check().
Security¶
- Every XML input (instances, schemas, Schematron, dictionaries) is parsed with an explicit hardened parser. External entities, external DTDs and network access are refused, and entities declared inside a file still expand, so valid files validate exactly as before. pyDIGGS no longer relies on lxml's defaults. libxml2, the C library under lxml, was declared unmaintained in December 2025.
- Require
lxml>=6.1.3, which stops loading external parameter entities by default (LP#2165901). - Compressed (gzip) XML is refused. libxml2 silently decompressed files it opened by path, so an 11 kB file could expand to hundreds of megabytes. Files over 1 GB are rejected.
- A
codeSpacethat points at a UNC path (file:////host/share/...) is never opened. On Windows, even checking one sends your NTLM credentials to that host. - The dictionary check runs in linear time. A crafted file with 20,000 sibling
codeSpaceelements took 73 s and now takes under 1 s. - Log files are created readable by their owner only and are never written through a symlink in the working directory.
- Added
SECURITY.md: report vulnerabilities privately through GitHub. It also states what pyDIGGS trusts: DIGGS files are untrusted, while custom schema and Schematron files are treated as code.
Changed¶
- Dictionary check 12 (UOM not in its quantity class) is an ERROR again, now that the official example files no longer need the warning-only workaround.
DictionarySemanticValidator(allow_network=True)now really downloads remote dictionaries; with libxml2 2.14 it silently fetched nothing. Downloads are limited to whitelisted http/https URLs (scheme, host, port and path must match, including every redirect), with a 15 s socket timeout, a 60 s overall limit and a 20 MB cap. A URL that fails is not retried. Network access stays off by default.- A relative
codeSpacepath (./,../) is resolved next to the instance file first, then against the working directory as before.
Fixed¶
schema_check()returned a traceback instead of False when libxml2 hit an internal validation error; it now returns False.- A
codeSpacepointing at a local file that is not XML aborted the whole dictionary check; it is now reported as Check 3 (dictionary not accessible). validatoraccepts binary file objects asinstance_pathagain.- Dictionary check 12 treats the DIGGS 2.6 AllUnits spelling
cm2/mascm2/min(Kernel.xsd documents it as square centimeter per minute).
Added¶
pydiggs.dictionaries.supplements: an inventory of MWD and Pile codes required by the DIGGS 3.0 examples and tracked upstream (#221; DIGGSml/def#13 / #14).- Releases are published to PyPI with PEP 740 attestations and attached to GitHub
releases with Sigstore signatures and sha256 digests (see
SECURITY.mdto verify).
1.0.0 - 2026-08-07¶
Stable release of the DIGGS 3.0 + FORGE packaging train first shipped as 1.0.0a1.
Added¶
- Everything from 1.0.0a1, now marked stable.
- Documentation aligned with the public 1.0.0 API (
diggs_versionoverride, Python 3.11+, four validation checks, known limits).
Notes¶
- Dictionary check 12 (UOM not in quantity class) remains a WARNING so official
diggs-examples with known unit/quantity mismatches still pass
dictionary_check(). - Unknown instance namespaces still default to DIGGS profile 3.0.0 (HG2).
1.0.0a1 - 2026-08-07¶
Added¶
- DIGGS 3.0.0 bundled schemas (
schema-dev@3.0.0) and namespace auto-detection (detect_diggs_version); unknown NS defaults to 3.0.0. - Full official diggs-examples corpus under
tests/fixtures/official/(2.5.a / 2.6 / 3.0 goldens + known_invalid pins), covering schema/dictionary/Schematron/context.
Changed¶
- Packaging migrated to FORGE standards:
src/layout, uv + hatchling, PEP 621/639/735. requires-pythonraised to>=3.11.- PyPI publish uses Trusted Publishing (OIDC) on
v*tags; Actions SHA-pinned. - DIGGS 2.5.a auto-detect resolves bundled
Complete.xsd(there is noDiggs.xsdin 2.5.a). - Docs and contributing guide updated for uv / multi-version validation.
- Dictionary validation prefers modern
def/codes/.../properties.xmldefinitions when instances still cite legacyDIGGSTestPropertyDefinitions.xmlURLs; accepts integer-familytypeDataaliases (int/integer/long); maps common legacy fragments (water_depth_calc,pore_water_pressure); allowsmeasurandwhere property dictionary Occurrences only listpropertyClass. - Schematron
weightRetainedassert allows zero (>= 0), matchingpercentRetainedand valid empty-sieve fractions in official grading examples.
Fixed¶
check-wheel-contentsW002 false failures from intentional byte-identical support XSDs across DIGGS profile trees.
Notes¶
- Alpha release toward 1.0.0. Dictionary check 12 (UOM not in quantity class) is a WARNING
so official diggs-examples with known unit/quantity mismatches still pass
dictionary_check()while remaining visible in the log.
0.2.0 - 2026-08-07¶
Added¶
- Semantic
dictionary_check()aligned with DIGGSml/validation. - Bundled lxml-adapted Schematron and
context_check(). - Official diggs-examples curated fixtures.
Fixed¶
- DIGGS 2.5.a/2.6 schema sync; Geophysics element-name libxml2-safe fix.
0.1.5 - 2025-02-02¶
Changed¶
- License Apache-2.0; optional log output CLI control; docs updates.