Quickstart¶
Validate your first DIGGS file in about five minutes. You need Python 3.11 or later and
a DIGGS instance file (any .xml file in DIGGS 2.5.a, 2.6 or 3.0.0).
Transcript
Validate a file. This terminal holds a DIGGS 3.0 file called site dot X M L. We type pydiggs validate and the file name. pyDIGGS runs every check: structure, schema, dictionary, Schematron rules, geometry and context. The last line reads valid, with no errors and no warnings.
Read the findings. Now we validate broken dot X M L, where a borehole depth was typed as a word. The verdict is not valid, with two errors. Each finding gives the line number, the rule that failed, and what is wrong: the schema expects a number, and the Schematron rule says the depth must be positive.
Write a report for CI. For continuous integration, ask for SARIF and write it to a file. The command exits with a non-zero status when the file is not valid, so a pipeline stops. Listing the report shows results dot sarriff on its own line, ready for GitHub code scanning or any SARIF viewer.
Try it yourself
The files this video starts from, exactly as it used them: validate-files.zip (6.5 KB, SHA-256 189983aa689bcec5a325ea20b033fae7e33ebf164bdae510da126286340503a5), or one by one: site.xml, broken.xml. They are synthetic examples, Apache-2.0.
Set up a folder with uv and the version the video shows, put the files in it, and run each command there (on Windows, activate with .venv\Scripts\activate):
1. Install¶
Check it worked:
More options, including the optional extras, are on Installation.
2. Validate a file¶
pyDIGGS detects the DIGGS version from the file's namespace and runs every check: structure, schema, dictionary, Schematron, geometry, deprecation and context. The first line is the verdict; each line after it is one finding with its line number, severity and rule id:
BH-01.xml: not-valid: 2 error(s), 29 warning(s), 20 info
BH-01.xml:12: error schema.cvc-complex-type.2.4: Element '{http://diggsml.org/schemas/2.6}businessAssociate': This element is not expected. ...
BH-01.xml:121: warning geometry.srs-attributes: Geometry: <PointLocation> has no srsName and srsDimension itself; ...
The exit status tells scripts what happened:
| Exit | Meaning |
|---|---|
0 |
no errors (warnings and notes are allowed) |
1 |
at least one error |
2 |
a usage problem, or a file that could not be read |
Validate a whole folder
Pass a directory and pyDIGGS checks every *.xml file in it, recursively:
pydiggs validate data/.
3. Look up a finding¶
Every finding has a stable rule id, such as schema.cvc-complex-type.2.4 or
dictionary.5. The rule ids section says what each family
means and how severe it is; the same ids appear in every output format, so you can
filter or suppress them reliably.
4. Use it from Python¶
uv tool install keeps pyDIGGS in its own environment, so your Python cannot import
it. Add it to the environment your code runs in first:
Then:
import pydiggs
report = pydiggs.validate("BH-01.xml") # prints nothing, writes no files
print(report.ok, report.counts) # False {'error': 2, 'warning': 29, 'info': 20}
for finding in report.findings:
print(finding.line, finding.severity, finding.rule_id, finding.message)
For an upload or any other document already in memory, use
pydiggs.validate_bytes(data). Both are described in the
Python API reference.
5. Add it to CI¶
Write SARIF and code-scanning tools (GitHub, GitLab, Azure DevOps) show each finding on the line it refers to:
Or write the diggs-findings 1.2 JSON document for your own tooling:
Next steps¶
-
Understand the checks
What each step checks, how to pin a DIGGS version, and the known limits.
-
Work with findings
The JSON and SARIF formats, rule ids, limits and privacy defaults.
-
Integrate pyDIGGS
A web service, a desktop app, an AI assistant or the browser.