Validation checks¶
pyDIGGS validates DIGGS instance files offline against:
- XSD schema: the bundled DIGGS 2.5.a, 2.6 or 3.0.0 schema, chosen from
the file's namespace (
detect_diggs_version). Unknown namespaces use 3.0.0. The unreleased DIGGS 3.1 draft is available as the experimental3.1-devprofile, only when asked for. - Dictionary and codeSpace semantics: progressive checks aligned with DIGGSml/validation (steps 1–13), against the bundled DIGGS Standard dictionaries from diggsml.org/def.
- Schematron: the bundled DIGGS business rules, adapted for lxml. The online Geosetta unit API is replaced by an offline conversion for casing diameters.
- Context: document structure, geometry SRS attributes, in-document
xlink:hreftargets and dataBlock arity.
Experimental: DIGGS 3.1-dev¶
pyDIGGS also bundles the unreleased DIGGS 3.1 draft schema, from
DIGGSml/schema-dev branch 3.1-dev, pinned to
one commit (see PROVENANCE.toml). Use it to check files written against the draft,
such as the DIGGS File Inspector's test files:
The profile is experimental:
- It is used only when you name it. The 3.1 draft uses the same namespace as 3.0, so a file is never detected as 3.1-dev, and the default stays 3.0.0.
- When the schema step checks a file against it, the report carries a
schema.unreleased-profilewarning, so a pass readsvalid-with-warnings: passing a draft schema is not conformance to a released DIGGS version. - The draft changes upstream. pyDIGGS updates its pinned copy in minor releases, so the
same file can get different findings after an upgrade. When DIGGS 3.1 is released,
it becomes a normal, detected profile and
3.1-devis deprecated. - Dictionary, Schematron and context checks are the same as for 3.0.0; only the schema (and which deprecations apply) differ.
Two ways to run them¶
Recommended: every check at once, as findings
pydiggs validate (command line) and pydiggs.validate() (Python) run every check
and return findings with stable rule ids, lines and XPaths. The
command prints the verdict and findings to standard output (or to --output);
the Python function prints nothing. Neither writes log files. Start with the
Quickstart.
The validator class and the schema_check, dictionary_check, schematron_check
and context_check commands run one check at a time and print their results or
write log files. They are kept for existing scripts and are shown on the rest of this
page.
Pin a DIGGS version¶
Detection follows the file's namespace. To validate against a specific version instead:
One check at a time¶
All four validator methods return True on success (for the dictionary check: no
ERROR findings). Logs go to the working directory by default; pass
output_log=False (Python) or --no-output_log (command line) to print to the
console instead.
1. Schema¶
from pydiggs import validator
# Profile detected from the namespace (unknown → 3.0.0)
validation = validator("BH-01.xml", output_log=False)
assert validation.schema_check() is True
print(validation.diggs_version)
# Pin a profile, or pass your own XSD
validator("BH-01.xml", diggs_version="2.5.a", output_log=False).schema_check()
validator("BH-01.xml", schema_path="path/to/Diggs.xsd", output_log=False).schema_check()
print(validation.syntax_error_log) # XML syntax errors
print(validation.schema_validation_log) # XSD validation errors
print(validation.schema_error_log) # schema parse errors
2. Dictionary¶
The dictionary check implements DIGGS codeSpace semantics:
- Preferred:
codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/properties.xml#liquid_limit" - Legacy:
codeSpace="https://diggsml.org/def/codes/DIGGS/0.1/properties.xml"with the element text equal to agml:idorgml:name - Bundled dictionaries under
pydiggs/dictionaries/codes/are resolved offline - Units are checked offline against
DiggsUomDictionary.xml
3. Schematron¶
By default the check uses the bundled
pydiggs/schematron/diggs_schematron_rules_2.6.sch (ISO Schematron, xslt1 for lxml).
Cross-unit casing diameter comparison uses the bundled DIGGS units dictionary.
Only use Schematron and XSD files you trust
A custom schema or Schematron file is code, not data: Schematron compiles to XSLT, which can read local files. The bundled rules make no file or network access.
from pydiggs import validator
validation = validator("BH-01.xml", output_log=False)
assert validation.schematron_check() is True
# Your own rules
validator("BH-01.xml", schematron_path="path/to/rules.sch", output_log=False).schematron_check()
print(validation.schematron_validation_log)
print(validation.schematron_error_log)
4. Context¶
Known limits¶
- The bundled schemas, dictionaries and deprecation registry are copies of
DIGGSml/schemas and
DIGGSml/def at the commits recorded in
PROVENANCE.tomlinside the installedpydiggspackage, with a sha256 for every file. A file whose codes appear in a newer upstream dictionary is validated against the bundled copy until pyDIGGS re-syncs. To use a newer property dictionary, download it and passdictionary_path=(command line--dictionary-path).allow_network=True(--allow-network) only fetches whitelisted dictionaries that are not bundled; it never replaces a bundled one. - Official diggs-examples files under
tests/fixtures/official/known_invalid/fail schema validation against the bundled XSDs; they are pinned so we never silently accept them.PileDrivingExample.xmlis among them: upstream rewrote it with DIGGSml/schema-dev types while it still declares 3.0.0.3.0/PorePressureDissipation_Example.xmluses eight codes the official dictionaries do not define, and fails dictionary check 5. - Dictionary check 12 (UOM/quantity mismatch) is an ERROR. Three 2.6 pore-pressure
fixtures correct
t50tos;coef_consolidation_horizkeeps the 2.6 AllUnits spellingcm2/m, which check 12 aliases tocm2/min. Upstream: DIGGSml/diggs-examples#4; seetests/fixtures/official/PROVENANCE.txt. - DIGGS 3.x MWD and pile-driving property codes live in the specialised dictionaries
mwd_properties.xmlandpil_properties.xml, now published on diggsml.org/def and bundled from there. The golden code inventory ispydiggs.dictionaries.supplements. - Legacy
http://diggsml.org/dictionaries/DIGGSTestPropertyDefinitions.xml#…codeSpaces are resolved against the moderndef/codes/DIGGS/0.1/properties.xmldefinitions when present. - Upstream Schematron
queryBinding="xslt3"rules that call remote APIs are not executed by lxml; pyDIGGS ships an adapted subset plus offline casing unit checks. - The full DIGGSml/validation XSLT modules for CRS, xlink and dataBlock structure remain out of scope; see that repository for the Saxon pipeline.