{
  "openapi": "3.1.0",
  "info": {
    "title": "pydiggs HTTP API",
    "summary": "Validate, read and compare DIGGS documents (XSD, dictionaries, Schematron); check AGS4 files, and convert AGS4 to DIGGS and DIGGS to AGS4.",
    "version": "1"
  },
  "paths": {
    "/v1/validate": {
      "post": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Validate one DIGGS document",
        "operationId": "validate",
        "responses": {
          "200": {
            "description": "A diggs-findings 1.2 document (or a SARIF 2.1.0 log). Malformed XML, truncation and an exhausted time budget are 200s with findings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiggsFindingsDocument"
                }
              },
              "application/sarif+json": {
                "schema": {
                  "$ref": "#/components/schemas/SarifLog"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "Accept allows none of the media types this operation sends",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "408": {
            "description": "The body did not arrive within the body timeout",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "Body larger than the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported media type, or compressed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid parameter, unreadable input, not a document of the expected format (reading, converting, comparing), or a result over the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Busy (see Retry-After) or not ready",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "504": {
            "description": "The request passed the hard time limit (process isolation)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "File name to report (reduced to a basename)."
          },
          {
            "name": "checks",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^(context|deprecation|dictionary|geometry|schema|schematron|structure)(,(context|deprecation|dictionary|geometry|schema|schematron|structure))*$",
              "maxLength": 512
            },
            "description": "Comma-separated steps to run (default: all)."
          },
          {
            "name": "diggs_version",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "2.5.a",
                "2.6",
                "3.0.0",
                "3.1-dev"
              ]
            },
            "description": "DIGGS version (default: detected)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "text/xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "additionalProperties": false,
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "checks": {
                    "type": "string",
                    "pattern": "^(context|deprecation|dictionary|geometry|schema|schematron|structure)(,(context|deprecation|dictionary|geometry|schema|schematron|structure))*$",
                    "maxLength": 512
                  },
                  "diggs_version": {
                    "enum": [
                      "2.5.a",
                      "2.6",
                      "3.0.0",
                      "3.1-dev"
                    ]
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "application/xml, text/xml, */*"
                }
              }
            }
          }
        }
      }
    },
    "/v1/read": {
      "post": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Read one DIGGS document into a diggs-model document",
        "operationId": "read",
        "responses": {
          "200": {
            "description": "A diggs-model 1.0 document: what pydiggs.read() returns for the same bytes. A schema-invalid file still reads (run /v1/validate for a verdict); an exhausted time budget is a 200 with complete: false.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiggsModelDocument"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "Accept allows none of the media types this operation sends",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "408": {
            "description": "The body did not arrive within the body timeout",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "Body larger than the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported media type, or compressed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid parameter, unreadable input, not a document of the expected format (reading, converting, comparing), or a result over the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Busy (see Retry-After) or not ready",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "504": {
            "description": "The request passed the hard time limit (process isolation)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "File name to report (reduced to a basename)."
          },
          {
            "name": "diggs_version",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "2.5.a",
                "2.6",
                "3.0.0",
                "3.1-dev"
              ]
            },
            "description": "DIGGS version (default: detected)."
          },
          {
            "name": "select",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 65536,
              "contentMediaType": "application/json",
              "examples": [
                "{\"results\": \"none\"}",
                "{\"results\": [\"Test_1\", \"Test_2\"]}"
              ]
            },
            "description": "JSON text: {\"results\": \"all\" | \"none\" | [node keys]}. Which result tables keep their values (default: all); the others keep their columns and row_count."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "text/xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "additionalProperties": false,
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "diggs_version": {
                    "enum": [
                      "2.5.a",
                      "2.6",
                      "3.0.0",
                      "3.1-dev"
                    ]
                  },
                  "select": {
                    "type": "string",
                    "maxLength": 65536,
                    "contentMediaType": "application/json",
                    "examples": [
                      "{\"results\": \"none\"}",
                      "{\"results\": [\"Test_1\", \"Test_2\"]}"
                    ]
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "application/xml, text/xml, */*"
                }
              }
            }
          }
        }
      }
    },
    "/v1/convert": {
      "post": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Convert AGS4 to DIGGS 3.0.0 or DIGGS to AGS4, with every loss reported",
        "operationId": "convert",
        "responses": {
          "200": {
            "description": "The conversion: the output (DIGGS XML or an AGS4 file, base64), the findings, and the residual AGS4 file for AGS4 to DIGGS. Losses, an output that fails validation or the AGS4 check and an exhausted time budget (complete: false) are 200s; the findings say what happened.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversionResult"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "Accept allows none of the media types this operation sends",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "408": {
            "description": "The body did not arrive within the body timeout",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "Body larger than the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported media type, or compressed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid parameter, unreadable input, not a document of the expected format (reading, converting, comparing), or a result over the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Busy (see Retry-After) or not ready",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "504": {
            "description": "The request passed the hard time limit (process isolation)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "File name to report (reduced to a basename)."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "diggs",
                "ags4"
              ]
            },
            "description": "The format to convert to: diggs (the default; the body is AGS4, a raw body application/octet-stream, text/csv or text/plain) or ags4 (the body is DIGGS XML, a raw body application/xml or text/xml). For a raw body, give it here."
          },
          {
            "name": "diggs_version",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "3.0.0"
              ]
            },
            "description": "to=diggs only: the DIGGS version to write (default: 3.0.0)."
          },
          {
            "name": "ags_version",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "4.2",
                "4.1.1"
              ]
            },
            "description": "to=ags4 only: the AGS4 version to write (default: 4.2). The BGS AGS validator and python-ags4 1.2.0 accept AGS4 only up to 4.1.1 (November 2026)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "text/csv": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "text/plain": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "application/xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "text/xml": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "additionalProperties": false,
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "to": {
                    "enum": [
                      "diggs",
                      "ags4"
                    ]
                  },
                  "diggs_version": {
                    "enum": [
                      "3.0.0"
                    ]
                  },
                  "ags_version": {
                    "enum": [
                      "4.2",
                      "4.1.1"
                    ]
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream, text/csv, text/plain, application/xml, text/xml, */*"
                }
              }
            }
          }
        }
      }
    },
    "/v1/ags4/check": {
      "post": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Check one AGS4 file against the AGS4 rules (Rules 1 to 20)",
        "operationId": "ags4Check",
        "responses": {
          "200": {
            "description": "A diggs-findings 1.2 document of step ags4 (or a SARIF 2.1.0 log). Rule breaks, content that is not AGS4 at all, truncation and an exhausted time budget are 200s with findings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiggsFindingsDocument"
                }
              },
              "application/sarif+json": {
                "schema": {
                  "$ref": "#/components/schemas/SarifLog"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "Accept allows none of the media types this operation sends",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "408": {
            "description": "The body did not arrive within the body timeout",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "Body larger than the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported media type, or compressed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid parameter, unreadable input, not a document of the expected format (reading, converting, comparing), or a result over the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Busy (see Retry-After) or not ready",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "504": {
            "description": "The request passed the hard time limit (process isolation)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "File name to report (reduced to a basename)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "text/csv": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "text/plain": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "additionalProperties": false,
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "dictionary": {
                    "type": "string",
                    "format": "binary",
                    "description": "An AGS4 data dictionary (pyDIGGS bundles none); without one, the rules that need it run only for the file's own DICT group."
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 4096
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream, text/csv, text/plain, */*"
                },
                "dictionary": {
                  "contentType": "application/octet-stream, text/csv, text/plain, */*"
                }
              }
            }
          }
        }
      }
    },
    "/v1/diff": {
      "post": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Compare two DIGGS documents: what was added, removed or changed",
        "operationId": "diff",
        "responses": {
          "200": {
            "description": "A diggs-diff 1.0 document: what pydiggs.diff.compare() returns for the same bytes and options, each file under its basename. Identical or not, the answer is a 200; a max_changes limit is a 200 with complete: false. Running out of time is a 200 with complete: false under thread isolation, and 504 timeout under process isolation (create_app's default).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiggsDiffDocument"
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "406": {
            "description": "Accept allows none of the media types this operation sends",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "408": {
            "description": "The body did not arrive within the body timeout",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "Body larger than the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "Unsupported media type, or compressed input",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid parameter, unreadable input, not a document of the expected format (reading, converting, comparing), or a result over the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Busy (see Retry-After) or not ready",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "504": {
            "description": "The request passed the hard time limit (process isolation)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "old_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "Name to report the old file as (a basename)."
          },
          {
            "name": "new_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096
            },
            "description": "Name to report the new file as (a basename)."
          },
          {
            "name": "match",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "auto",
                "gml-id",
                "natural",
                "gml_id"
              ],
              "default": "auto"
            },
            "description": "How records are paired: auto (by gml:id, then by natural key), gml-id (ids only; also written gml_id) or natural (natural keys only)."
          },
          {
            "name": "rel_tol",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "exclusiveMaximum": 1,
              "default": 1e-09
            },
            "description": "Two numbers are equal within this fraction of the larger one."
          },
          {
            "name": "abs_tol",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "default": 0.0
            },
            "description": "Or within this much, in the value's own unit."
          },
          {
            "name": "max_changes",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 999999999999999999,
              "default": 10000
            },
            "description": "Most changes listed; the counts stay exact, and a cut list is an incomplete comparison (complete: false)."
          },
          {
            "name": "show_reformatted",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Also list values that are only written differently (1.50 and 1.5)."
          },
          {
            "name": "show_renamed",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Also list records whose gml:id changed (never a difference)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "old",
                  "new"
                ],
                "additionalProperties": false,
                "properties": {
                  "old": {
                    "type": "string",
                    "format": "binary",
                    "description": "The earlier DIGGS file; at most the server's max_body_bytes."
                  },
                  "new": {
                    "type": "string",
                    "format": "binary",
                    "description": "The later DIGGS file; at most the server's max_body_bytes."
                  },
                  "old_name": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "new_name": {
                    "type": "string",
                    "maxLength": 4096
                  },
                  "match": {
                    "enum": [
                      "auto",
                      "gml-id",
                      "natural",
                      "gml_id"
                    ],
                    "default": "auto",
                    "description": "How records are paired: auto (by gml:id, then by natural key), gml-id (ids only; also written gml_id) or natural (natural keys only)."
                  },
                  "rel_tol": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMaximum": 1,
                    "default": 1e-09,
                    "description": "Two numbers are equal within this fraction of the larger one."
                  },
                  "abs_tol": {
                    "type": "number",
                    "minimum": 0,
                    "default": 0.0,
                    "description": "Or within this much, in the value's own unit."
                  },
                  "max_changes": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 999999999999999999,
                    "default": 10000,
                    "description": "Most changes listed; the counts stay exact, and a cut list is an incomplete comparison (complete: false)."
                  },
                  "show_reformatted": {
                    "type": "boolean",
                    "default": false,
                    "description": "Also list values that are only written differently (1.50 and 1.5)."
                  },
                  "show_renamed": {
                    "type": "boolean",
                    "default": false,
                    "description": "Also list records whose gml:id changed (never a difference)."
                  }
                }
              },
              "encoding": {
                "old": {
                  "contentType": "application/xml, text/xml, */*"
                },
                "new": {
                  "contentType": "application/xml, text/xml, */*"
                }
              }
            }
          }
        }
      }
    },
    "/v1/versions": {
      "get": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Versions of pydiggs, the findings schema and the bundled data",
        "operationId": "versions",
        "responses": {
          "200": {
            "description": "Versions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Versions"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/capabilities": {
      "get": {
        "tags": [
          "pydiggs"
        ],
        "summary": "What this pydiggs can do: operations, options, stability, extras",
        "operationId": "capabilities",
        "responses": {
          "200": {
            "description": "A diggs-capabilities 1.0 document: what pydiggs.capabilities() returns in the server's own interpreter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/rules": {
      "get": {
        "tags": [
          "pydiggs"
        ],
        "summary": "The rule catalogue",
        "operationId": "listRules",
        "responses": {
          "200": {
            "description": "The rule catalogue",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/RuleInfo"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid parameter, unreadable input, not a document of the expected format (reading, converting, comparing), or a result over the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "step",
            "in": "query",
            "required": false,
            "schema": {
              "enum": [
                "structure",
                "schema",
                "codeType",
                "dictionary",
                "schematron",
                "geometry",
                "crs",
                "coordinate",
                "deprecation",
                "context",
                "ags4",
                "convert",
                "diff"
              ]
            },
            "description": "Only the rules of this step."
          }
        ]
      }
    },
    "/v1/rules/{rule_id}": {
      "get": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Explain one rule id",
        "operationId": "explainRule",
        "responses": {
          "200": {
            "description": "The rule (``known: false`` for a valid id pydiggs does not emit)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RuleInfo"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid parameter, unreadable input, not a document of the expected format (reading, converting, comparing), or a result over the limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Internal error (fixed text and a correlation id)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "rule_id",
            "in": "path",
            "required": true,
            "description": "A rule id, <step>.<name>.",
            "schema": {
              "type": "string",
              "maxLength": 256,
              "pattern": "^(structure|schema|codeType|dictionary|schematron|geometry|crs|coordinate|deprecation|context|ags4|convert|diff)\\.[A-Za-z0-9][A-Za-z0-9._-]*$"
            }
          }
        ]
      }
    },
    "/v1/readyz": {
      "get": {
        "tags": [
          "pydiggs"
        ],
        "summary": "Readiness: 200 once the workers are warm",
        "operationId": "readyzV1",
        "responses": {
          "200": {
            "description": "Ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ready"
                }
              }
            }
          },
          "403": {
            "description": "Cross-site request refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "Busy (see Retry-After) or not ready",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/livez": {
      "get": {
        "summary": "Liveness: 200 while the server runs",
        "operationId": "livez",
        "responses": {
          "200": {
            "description": "Ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ready"
                }
              }
            }
          }
        }
      }
    },
    "/readyz": {
      "get": {
        "summary": "Readiness: 200 once the workers are warm",
        "operationId": "readyz",
        "responses": {
          "200": {
            "description": "Ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ready"
                }
              }
            }
          },
          "503": {
            "description": "Busy (see Retry-After) or not ready",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Capabilities": {
        "title": "diggs-capabilities 1.0",
        "description": "What one pydiggs install can do, as pydiggs.capabilities().to_dict() returns it (pydiggs capabilities --json, GET /v1/capabilities, MCP resource pydiggs://capabilities): each operation with its stability, inputs, outputs, options, the extras it needs and whether they are installed. Open for consumers: objects accept unknown fields, so a 1.0 consumer accepts any 1.x document. A new optional field or a new token in inputs, outputs or needs is a minor version; a new stability or option type, or anything else, is a new major.",
        "type": "object",
        "required": [
          "$schema",
          "schema_version",
          "pydiggs_version",
          "operations"
        ],
        "properties": {
          "$schema": {
            "type": "string",
            "description": "URL of the schema the document follows."
          },
          "schema_version": {
            "type": "string",
            "pattern": "^1\\.[0-9]+$",
            "description": "Major.minor of diggs-capabilities."
          },
          "pydiggs_version": {
            "type": "string",
            "description": "The pydiggs version that wrote the document."
          },
          "operations": {
            "type": "array",
            "description": "Every operation this pydiggs offers, available here or not.",
            "items": {
              "type": "object",
              "description": "One thing pydiggs can do.",
              "required": [
                "id",
                "label",
                "stability",
                "inputs",
                "outputs",
                "options",
                "needs",
                "available"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^[a-z0-9]+([._-][a-z0-9]+)*$",
                  "description": "Stable identifier, such as validate, read, ags4.check or export.gpkg."
                },
                "label": {
                  "type": "string",
                  "description": "What the operation does, in plain language."
                },
                "stability": {
                  "enum": [
                    "stable",
                    "preview",
                    "experimental"
                  ],
                  "description": "stable follows Semantic Versioning; preview may change in a minor release; experimental may change or go at any time."
                },
                "inputs": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "What it reads: a DIGGS version (diggs-2.6), an AGS4 version (ags4-4.1.1), a pydiggs document (diggs-model-1.0) or an in-memory Python type."
                },
                "outputs": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "What it gives: a pydiggs document (diggs-findings-1.2, diggs-model-1.0), a media type (application/geo+json), an AGS4 version or an in-memory Python type (pandas.DataFrame)."
                },
                "options": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "object",
                    "description": "One option of an operation.",
                    "required": [
                      "type",
                      "label",
                      "default",
                      "choices",
                      "required"
                    ],
                    "properties": {
                      "type": {
                        "enum": [
                          "boolean",
                          "integer",
                          "number",
                          "string",
                          "string[]",
                          "file"
                        ],
                        "description": "The value type; file is a second file (a path in Python)."
                      },
                      "label": {
                        "type": "string",
                        "description": "What the option does, in plain language."
                      },
                      "default": {
                        "type": [
                          "string",
                          "integer",
                          "number",
                          "boolean",
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "string"
                        },
                        "description": "The default; null means not given, and the operation then decides."
                      },
                      "choices": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "string"
                        },
                        "description": "The values accepted (each item of a string[] option), or null for any."
                      },
                      "required": {
                        "type": "boolean",
                        "description": "Whether the option must be given."
                      }
                    }
                  },
                  "description": "Option name (the keyword argument and request parameter) -> its description."
                },
                "needs": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "The pydiggs extras it needs (pip install 'pydiggs[gis]'); empty for the core."
                },
                "available": {
                  "type": "boolean",
                  "description": "Whether everything it needs is installed in the interpreter that answered."
                }
              }
            }
          }
        }
      },
      "ConversionResult": {
        "title": "ConversionResult",
        "description": "One conversion, AGS4 to DIGGS (to=diggs) or DIGGS to AGS4 (to=ags4): the output as base64 with its media type and sha256, the findings about the source (report) and the output (validation), and for AGS4 to DIGGS the residual AGS4 file of what was not converted. Every surface (HTTP, sidecar, CLI) produces the same result for the same input.",
        "type": "object",
        "required": [
          "to",
          "media_type",
          "output_name",
          "diggs_version",
          "ags_version",
          "mapping_version",
          "complete",
          "lossless",
          "report",
          "validation",
          "output_sha256",
          "output_base64",
          "residual_base64"
        ],
        "properties": {
          "to": {
            "enum": [
              "diggs",
              "ags4"
            ],
            "description": "The output format."
          },
          "media_type": {
            "type": "string",
            "examples": [
              "application/xml",
              "text/plain; charset=utf-8"
            ],
            "description": "Of the output: application/xml (DIGGS) or text/plain (AGS4)."
          },
          "output_name": {
            "type": "string",
            "description": "A file name for the output: the input's name, new extension."
          },
          "diggs_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "Of the DIGGS output (to=diggs) or of the DIGGS input (to=ags4)."
          },
          "ags_version": {
            "anyOf": [
              {
                "enum": [
                  "4.2",
                  "4.1.1"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Of the AGS4 output (to=ags4); null for to=diggs."
          },
          "mapping_version": {
            "type": "string",
            "description": "Of the mapping table used."
          },
          "complete": {
            "type": "boolean",
            "description": "False when a size or time limit stopped the conversion."
          },
          "lossless": {
            "type": "boolean",
            "description": "True when no convert finding of severity warning or error."
          },
          "report": {
            "$ref": "#/components/schemas/DiggsFindingsDocument"
          },
          "validation": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsFindingsDocument"
              },
              {
                "type": "null"
              }
            ],
            "description": "Of the output: pydiggs.validate (DIGGS) or pydiggs.ags4.check (AGS4)."
          },
          "output_sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "output_base64": {
            "type": "string",
            "contentEncoding": "base64",
            "description": "The output's bytes (of media_type), standard base64 (RFC 4648, padded)."
          },
          "residual_base64": {
            "type": [
              "string",
              "null"
            ],
            "contentEncoding": "base64",
            "contentMediaType": "text/plain; charset=utf-8",
            "description": "AGS4 to DIGGS: the AGS4 file of every value a convert finding names, with the key fields of its row, so that the output and this file together hold everything the source did; null when everything was converted, and always null for DIGGS to AGS4. Standard base64."
          }
        }
      },
      "DiggsDiffChange": {
        "type": "object",
        "required": [
          "op",
          "collection",
          "element",
          "name",
          "old_key",
          "new_key",
          "matched_by",
          "truncated",
          "values"
        ],
        "properties": {
          "op": {
            "$ref": "#/components/schemas/DiggsDiffOp"
          },
          "collection": {
            "type": "string",
            "minLength": 1,
            "description": "Where the record lives: document, projects, features, samples, measurements, layers, components ... What a file holds outside every record (the attributes of its root element, the text between its members) is the document's: compared with its record, or listed as the root element (element Diggs) when the two files have no pair of document records."
          },
          "element": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "old_key": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "new_key": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200
          },
          "matched_by": {
            "enum": [
              "gml_id",
              "natural",
              null
            ]
          },
          "truncated": {
            "type": "boolean",
            "description": "True when name or a key was cut to 200 characters."
          },
          "values": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsDiffValueChange"
            }
          }
        }
      },
      "DiggsDiffCounts": {
        "type": "object",
        "required": [
          "added",
          "removed",
          "changed",
          "unchanged"
        ],
        "properties": {
          "added": {
            "type": "integer",
            "minimum": 0
          },
          "removed": {
            "type": "integer",
            "minimum": 0
          },
          "changed": {
            "type": "integer",
            "minimum": 0
          },
          "unchanged": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "DiggsDiffDocument": {
        "title": "diggs-diff 1.0",
        "description": "The difference between two DIGGS files at model level, as pydiggs.diff.compare() writes it (pyDIGGS 1.13 and later). Open for consumers: objects accept unknown fields, so a 1.0 consumer accepts any 1.x document. A new optional field is a minor version; anything else is a new major. Nothing is converted: a change of unit is a change.",
        "type": "object",
        "required": [
          "$schema",
          "format",
          "schema_version",
          "tool",
          "identical",
          "complete",
          "limits_hit",
          "old",
          "new",
          "options",
          "summary",
          "value_changes",
          "reformatted",
          "renamed",
          "changes",
          "notes"
        ],
        "properties": {
          "$schema": {
            "type": "string",
            "description": "URL of the schema the document follows."
          },
          "format": {
            "const": "diggs-diff"
          },
          "schema_version": {
            "type": "string",
            "pattern": "^1\\.[0-9]+(-beta\\.[0-9]+)?$",
            "description": "Major.minor of diggs-diff; a pre-release adds -beta.N (1.0-beta.1 was written by pyDIGGS 1.12)."
          },
          "tool": {
            "type": "object",
            "required": [
              "name",
              "version"
            ],
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1
              },
              "version": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          "identical": {
            "type": "boolean",
            "description": "True only when nothing differs and the comparison finished (complete). A number written differently (reformatted) and a record's own gml:id (renamed) are not differences."
          },
          "complete": {
            "type": "boolean",
            "description": "False when a limit stopped the comparison, a file was read in part, or values were not there to compare; see limits_hit and notes. An incomplete comparison is never identical."
          },
          "limits_hit": {
            "type": "array",
            "items": {
              "type": "string",
              "examples": [
                "max_changes",
                "time_budget",
                "old_read_incomplete",
                "new_read_incomplete",
                "old_results_not_read",
                "new_results_not_read"
              ]
            },
            "description": "What stopped the comparison or what it could not look at; empty exactly when complete. max_changes: the list of changes was cut. time_budget: the time ran out. old_read_incomplete, new_read_incomplete: that file was read in part. old_results_not_read, new_results_not_read: that side is a model read without the values of its result tables, so their cells were not compared. A later minor version may add a value."
          },
          "old": {
            "$ref": "#/components/schemas/DiggsDiffSource"
          },
          "new": {
            "$ref": "#/components/schemas/DiggsDiffSource"
          },
          "options": {
            "type": "object",
            "required": [
              "match",
              "rel_tol",
              "abs_tol",
              "max_changes",
              "time_budget"
            ],
            "properties": {
              "match": {
                "enum": [
                  "auto",
                  "gml-id",
                  "natural"
                ]
              },
              "rel_tol": {
                "type": "number",
                "minimum": 0,
                "exclusiveMaximum": 1
              },
              "abs_tol": {
                "type": "number",
                "minimum": 0
              },
              "max_changes": {
                "type": "integer",
                "minimum": 0
              },
              "time_budget": {
                "type": [
                  "number",
                  "null"
                ],
                "exclusiveMinimum": 0
              }
            }
          },
          "summary": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/DiggsDiffCounts"
            },
            "description": "Node counts per collection (features, samples, measurements, layers, components ...). Exact when only max_changes stopped the list; partial after a time_budget stop."
          },
          "value_changes": {
            "type": "integer",
            "minimum": 0,
            "description": "How many values differ (every listed value change counts, listed or not)."
          },
          "reformatted": {
            "type": "integer",
            "minimum": 0,
            "description": "How many values are written differently but are equal: a number (1.50 and 1.5), the separators of a result set whose values read the same, a declared type written another way (double and float)."
          },
          "renamed": {
            "type": "integer",
            "minimum": 0,
            "description": "How many records were matched by their natural key and have a different gml:id in the two files. Not a difference: such a record counts as unchanged unless a value of it differs."
          },
          "changes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsDiffChange"
            },
            "description": "Ordered by collection, then key, then path. At most max_changes entries (changes plus value changes). A record with op reformatted or renamed did not change; it is listed only on request."
          },
          "notes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsDiffNote"
            },
            "description": "Findings of step diff: diff.ambiguous-match, diff.limit, diff.timeout."
          }
        },
        "allOf": [
          {
            "description": "Identical means complete, and nothing counted or listed as a difference.",
            "if": {
              "required": [
                "identical"
              ],
              "properties": {
                "identical": {
                  "const": true
                }
              }
            },
            "then": {
              "properties": {
                "complete": {
                  "const": true
                },
                "value_changes": {
                  "const": 0
                },
                "summary": {
                  "additionalProperties": {
                    "properties": {
                      "added": {
                        "const": 0
                      },
                      "removed": {
                        "const": 0
                      },
                      "changed": {
                        "const": 0
                      }
                    }
                  }
                },
                "changes": {
                  "items": {
                    "properties": {
                      "op": {
                        "enum": [
                          "reformatted",
                          "renamed"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          {
            "description": "A complete comparison names no limit; an incomplete one names at least one.",
            "if": {
              "required": [
                "complete"
              ],
              "properties": {
                "complete": {
                  "const": true
                }
              }
            },
            "then": {
              "properties": {
                "limits_hit": {
                  "maxItems": 0
                }
              }
            },
            "else": {
              "properties": {
                "limits_hit": {
                  "minItems": 1
                }
              }
            }
          }
        ]
      },
      "DiggsDiffNote": {
        "type": "object",
        "description": "A finding of step diff, as diggs-findings 1.2 writes one. Open, like every object in this schema: a field a later findings minor adds leaves a 1.0 document valid.",
        "required": [
          "layer",
          "step",
          "rule_id",
          "severity",
          "message",
          "location"
        ],
        "properties": {
          "layer": {
            "enum": [
              "native",
              "official"
            ]
          },
          "step": {
            "enum": [
              "structure",
              "schema",
              "codeType",
              "dictionary",
              "schematron",
              "geometry",
              "crs",
              "coordinate",
              "deprecation",
              "context",
              "ags4",
              "convert",
              "diff"
            ]
          },
          "rule_id": {
            "type": "string",
            "pattern": "^(structure|schema|codeType|dictionary|schematron|geometry|crs|coordinate|deprecation|context|ags4|convert|diff)\\.[A-Za-z0-9][A-Za-z0-9._-]*$",
            "description": "Stable id; the part before the first dot equals step."
          },
          "severity": {
            "enum": [
              "error",
              "warning",
              "info"
            ]
          },
          "message": {
            "type": "string"
          },
          "location": {
            "type": "object",
            "required": [
              "line",
              "column",
              "xpath",
              "gml_id"
            ],
            "properties": {
              "line": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1
              },
              "column": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1
              },
              "xpath": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "gml_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "path": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024
              }
            }
          },
          "source_snippet": {
            "type": "string",
            "maxLength": 1024
          }
        }
      },
      "DiggsDiffOp": {
        "enum": [
          "added",
          "removed",
          "changed",
          "reformatted",
          "renamed"
        ],
        "description": "reformatted: the same value written differently (1.50 and 1.5; the separators of a result set whose values read the same; double and float). renamed: the record's own gml:id differs (a value with path gml_id), or, on a record, its id differs and no value changed. Neither is a difference."
      },
      "DiggsDiffSource": {
        "type": "object",
        "required": [
          "name",
          "sha256",
          "size",
          "diggs_version"
        ],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "size": {
            "type": "integer",
            "minimum": 0
          },
          "diggs_version": {
            "type": "string"
          }
        }
      },
      "DiggsDiffValueChange": {
        "type": "object",
        "required": [
          "op",
          "path",
          "old",
          "new",
          "at",
          "truncated"
        ],
        "properties": {
          "op": {
            "$ref": "#/components/schemas/DiggsDiffOp"
          },
          "path": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000,
            "description": "Which value: name, params.<element>, interval.top, results[0].columns[<key>].cells[@<index>] ...; gml_id is the record's own gml:id; a path that starts with xml. is content of the file that the model does not keep, below the record (xml.Diggs[1] is the root element). A path that would be longer than 1,000 characters keeps its first 200 and its last 400, around a digest of the whole path, so two different paths stay different."
          },
          "old": {
            "description": "The value in the old file as JSON (a quantity is its text and unit, e.g. \"1.50 ft\"); null when the old file has none. Text is cut to 200 characters and lists to 200 items."
          },
          "new": {
            "description": "The value in the new file; null when the new file has none."
          },
          "at": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 1000,
            "description": "XPath of the record in the new file. An XPath that would be longer than 1,000 characters is shortened as a path is, and is then no longer an XPath."
          },
          "truncated": {
            "type": "boolean",
            "description": "True when old or new was cut."
          }
        }
      },
      "DiggsFindingsCommit": {
        "type": "string",
        "pattern": "^[0-9a-f]{7,64}$"
      },
      "DiggsFindingsCounts": {
        "type": "object",
        "required": [
          "error",
          "warning",
          "info"
        ],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "integer",
            "minimum": 0
          },
          "warning": {
            "type": "integer",
            "minimum": 0
          },
          "info": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "DiggsFindingsDocument": {
        "title": "diggs-findings 1.2",
        "description": "Findings about DIGGS instance files and AGS4 files, as written by pydiggs (pydiggs validate --format json). Version 1.2 adds to 1.1 the step diff (the findings of a model diff, pydiggs.diff); 1.1 added to 1.0 the steps ags4 and convert, the optional location.path and the optional files[].format. Every 1.0 and 1.1 document is a valid 1.2 document. A new optional field is a minor version; renaming or removing a field is a 2.0.",
        "type": "object",
        "required": [
          "$schema",
          "format",
          "schema_version",
          "tool",
          "files"
        ],
        "additionalProperties": false,
        "properties": {
          "$schema": {
            "enum": [
              "https://xinp-hub.github.io/pydiggs/schemas/diggs-findings-1.2.schema.json",
              "https://xinp-hub.github.io/pydiggs/schemas/diggs-findings-1.1.schema.json",
              "https://xinp-hub.github.io/pydiggs/schemas/diggs-findings-1.0.schema.json"
            ],
            "description": "The schema the document was written for: this one, or 1.1 or 1.0, whose documents are valid here."
          },
          "format": {
            "const": "diggs-findings"
          },
          "schema_version": {
            "type": "string",
            "pattern": "^1\\.[0-9]+$",
            "description": "Major.minor version of this schema the document follows."
          },
          "tool": {
            "type": "object",
            "required": [
              "name",
              "version",
              "reference_data"
            ],
            "additionalProperties": false,
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1
              },
              "version": {
                "type": "string",
                "minLength": 1
              },
              "reference_data": {
                "description": "Upstream commit of each vendored DIGGS reference-data source (from PROVENANCE.toml).",
                "type": "object",
                "properties": {
                  "schemas": {
                    "$ref": "#/components/schemas/DiggsFindingsCommit"
                  },
                  "def": {
                    "$ref": "#/components/schemas/DiggsFindingsCommit"
                  },
                  "diggs-examples": {
                    "$ref": "#/components/schemas/DiggsFindingsCommit"
                  }
                },
                "additionalProperties": {
                  "$ref": "#/components/schemas/DiggsFindingsCommit"
                }
              }
            }
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsFindingsFile"
            }
          }
        }
      },
      "DiggsFindingsFile": {
        "type": "object",
        "required": [
          "path",
          "sha256",
          "diggs_version",
          "status",
          "verdict",
          "steps",
          "counts",
          "findings"
        ],
        "additionalProperties": false,
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1,
            "description": "Relative to the working directory when the file is under it, else the bare file name; absolute only when asked for."
          },
          "sha256": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9a-f]{64}$"
          },
          "format": {
            "enum": [
              "diggs",
              "ags4"
            ],
            "description": "What kind of file this is; diggs when absent. New in 1.1."
          },
          "diggs_version": {
            "description": "DIGGS profile the file was checked as (2.5.a, 2.6, 3.0.0), or null when it could not be told or the file is not DIGGS (always null for an AGS4 file).",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "enum": [
              "checked",
              "not-diggs",
              "unreadable"
            ],
            "description": "not-diggs: the root element is not a DIGGS Diggs element; only the structure step ran."
          },
          "verdict": {
            "enum": [
              "valid",
              "valid-with-warnings",
              "not-valid",
              "partly-checked",
              "not-diggs",
              "unreadable"
            ],
            "description": "Derived from status, steps and findings: not-diggs or unreadable from the status; else not-valid if any finding is an error; else partly-checked if a step is partial or incomplete; else valid-with-warnings if any finding is a warning; else valid."
          },
          "error": {
            "type": "string",
            "description": "Why an unreadable file could not be read."
          },
          "steps": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "step",
                "status"
              ],
              "additionalProperties": false,
              "properties": {
                "step": {
                  "$ref": "#/components/schemas/DiggsFindingsStep"
                },
                "status": {
                  "enum": [
                    "passed",
                    "partial",
                    "failed",
                    "skipped",
                    "incomplete"
                  ],
                  "description": "partial: no error, but part of the step could not be checked offline (dictionary.offline); incomplete: the step could not finish, or lost findings to max_findings (see the structure.findings-truncated finding). A step with an error is failed (or incomplete), never partial."
                }
              }
            }
          },
          "counts": {
            "$ref": "#/components/schemas/DiggsFindingsCounts"
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsFindingsFinding"
            }
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "const": "unreadable"
                }
              }
            },
            "then": {
              "required": [
                "error"
              ],
              "properties": {
                "sha256": {
                  "type": "null"
                },
                "verdict": {
                  "const": "unreadable"
                },
                "findings": {
                  "maxItems": 0
                }
              }
            },
            "else": {
              "not": {
                "required": [
                  "error"
                ]
              },
              "properties": {
                "sha256": {
                  "type": "string"
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "not-diggs"
                }
              }
            },
            "then": {
              "properties": {
                "verdict": {
                  "const": "not-diggs"
                },
                "diggs_version": {
                  "type": "null"
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "checked"
                }
              }
            },
            "then": {
              "properties": {
                "verdict": {
                  "enum": [
                    "valid",
                    "valid-with-warnings",
                    "not-valid",
                    "partly-checked"
                  ]
                }
              }
            }
          },
          {
            "if": {
              "required": [
                "format"
              ],
              "properties": {
                "format": {
                  "const": "ags4"
                }
              }
            },
            "then": {
              "properties": {
                "diggs_version": {
                  "type": "null"
                }
              }
            }
          }
        ]
      },
      "DiggsFindingsFinding": {
        "type": "object",
        "required": [
          "layer",
          "step",
          "rule_id",
          "severity",
          "message",
          "location"
        ],
        "additionalProperties": false,
        "properties": {
          "layer": {
            "enum": [
              "native",
              "official"
            ]
          },
          "step": {
            "$ref": "#/components/schemas/DiggsFindingsStep"
          },
          "rule_id": {
            "type": "string",
            "pattern": "^(structure|schema|codeType|dictionary|schematron|geometry|crs|coordinate|deprecation|context|ags4|convert|diff)\\.[A-Za-z0-9][A-Za-z0-9._-]*$",
            "description": "Stable id; the part before the first dot equals step."
          },
          "severity": {
            "$ref": "#/components/schemas/DiggsFindingsSeverity"
          },
          "message": {
            "type": "string",
            "description": "Human-readable text. Never compare it; compare rule_id and location."
          },
          "location": {
            "type": "object",
            "required": [
              "line",
              "column",
              "xpath",
              "gml_id"
            ],
            "additionalProperties": false,
            "properties": {
              "line": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1
              },
              "column": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1
              },
              "xpath": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Element path in the official diggs:get-path form, e.g. /diggs:Diggs[1]/diggs:samplingFeature[2]."
              },
              "gml_id": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "gml:id of the nearest element at or above the problem."
              },
              "path": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1024,
                "description": "Place in a source that is not XML. For AGS4: GROUP, GROUP/row or GROUP/row/HEADING (rows are DATA rows, counted from 1), e.g. GEOL/12/GEOL_LEG. New in 1.1; absent for a place in XML."
              }
            }
          },
          "source_snippet": {
            "type": "string",
            "maxLength": 1024,
            "description": "The offending element's XML, at most 1 KiB; present only when snippets were asked for."
          }
        }
      },
      "DiggsFindingsSeverity": {
        "enum": [
          "error",
          "warning",
          "info"
        ]
      },
      "DiggsFindingsStep": {
        "enum": [
          "structure",
          "schema",
          "codeType",
          "dictionary",
          "schematron",
          "geometry",
          "crs",
          "coordinate",
          "deprecation",
          "context",
          "ags4",
          "convert",
          "diff"
        ]
      },
      "DiggsModelAssociate": {
        "description": "A BusinessAssociate.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "roles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelCode"
            }
          }
        }
      },
      "DiggsModelCode": {
        "type": "object",
        "required": [
          "value",
          "code_space"
        ],
        "properties": {
          "value": {
            "type": "string"
          },
          "code_space": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "DiggsModelColumn": {
        "type": "object",
        "required": [
          "name",
          "key",
          "definition",
          "uom",
          "type",
          "null_value",
          "values"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "key": {
            "type": [
              "string",
              "null"
            ],
            "description": "propertyClass fragment, e.g. liquid_limit."
          },
          "definition": {
            "type": [
              "string",
              "null"
            ]
          },
          "uom": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string",
            "examples": [
              "number",
              "string",
              "boolean",
              "datetime"
            ]
          },
          "null_value": {
            "type": [
              "string",
              "null"
            ]
          },
          "values": {
            "type": "array",
            "items": {
              "type": [
                "number",
                "string",
                "boolean",
                "null"
              ]
            }
          },
          "si_uom": {
            "type": [
              "string",
              "null"
            ]
          },
          "si_factor": {
            "type": [
              "number",
              "null"
            ]
          },
          "si_offset": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "DiggsModelComponent": {
        "description": "A record nested inside another node (a casing, water strike, well opening, SPT drive set, cone, constituent ...), kept as a node of its own.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "role": {
            "type": "string",
            "description": "The DIGGS property that holds it. Open vocabulary.",
            "examples": [
              "casing",
              "waterStrike",
              "driveSet",
              "constituent"
            ]
          },
          "interval": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelInterval"
              },
              {
                "type": "null"
              }
            ]
          },
          "location": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelPosition"
              },
              {
                "type": "null"
              }
            ]
          },
          "time": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelTimeSpan"
              },
              {
                "type": "null"
              }
            ]
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelComponent"
            }
          }
        }
      },
      "DiggsModelCrsComponent": {
        "type": "object",
        "required": [
          "epsg",
          "name",
          "type",
          "unit",
          "axis_order",
          "datum",
          "components"
        ],
        "properties": {
          "epsg": {
            "type": [
              "integer",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "geographic_2d",
              "geographic_3d",
              "projected",
              "vertical",
              "geocentric",
              "compound"
            ]
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "The axes' unit when they share one."
          },
          "axis_order": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "lat,lon",
              "east,north",
              "up"
            ]
          },
          "datum": {
            "type": [
              "string",
              "null"
            ]
          },
          "components": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "EPSG codes of a compound CRS's parts."
          }
        },
        "description": "One component of a CRS. Facts come from pyDIGGS's EPSG subset (EPSG Dataset, owned by IOGP; see pydiggs.crs.epsg_source()); a code not in it has only epsg."
      },
      "DiggsModelCrsRef": {
        "type": "object",
        "required": [
          "srs_name",
          "form",
          "name",
          "horizontal",
          "vertical",
          "axis_order",
          "unit",
          "known",
          "local"
        ],
        "properties": {
          "srs_name": {
            "type": "string",
            "description": "As written."
          },
          "form": {
            "type": "string",
            "examples": [
              "epsg",
              "diggs",
              "ogc",
              "local",
              "unknown"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "horizontal": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelCrsComponent"
              },
              {
                "type": "null"
              }
            ]
          },
          "vertical": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelCrsComponent"
              },
              {
                "type": "null"
              }
            ]
          },
          "axis_order": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "lat,lon",
              "east,north"
            ]
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "The coordinates' unit when the CRS states one (a projected CRS's, or a linear referencing method's units)."
          },
          "known": {
            "type": "boolean",
            "description": "Whether pyDIGGS found what it names: the EPSG codes in its subset, or the gml:id in the file."
          },
          "local": {
            "type": [
              "string",
              "null"
            ],
            "description": "gml:id of a local or linear referencing system defined in the file."
          }
        }
      },
      "DiggsModelDocument": {
        "title": "diggs-model 1.0",
        "description": "The normalised, version-agnostic model of one DIGGS file that pydiggs.read() returns (pyDIGGS 1.7 and later). Open for consumers: objects accept unknown fields and string vocabularies are open, so a 1.0 consumer accepts any 1.x document. A new optional field or vocabulary value is a minor version; anything else is a new major. Coordinates and values are kept as written; nothing is converted or transformed silently.",
        "type": "object",
        "required": [
          "schema_version",
          "tool",
          "source",
          "complete",
          "document",
          "projects",
          "associates",
          "features",
          "sampling_activities",
          "samples",
          "observations",
          "measurements",
          "others",
          "crs",
          "links",
          "notes"
        ],
        "properties": {
          "$schema": {
            "type": "string",
            "description": "URL of the schema the document follows."
          },
          "schema_version": {
            "type": "string",
            "pattern": "^1\\.[0-9]+(-(draft|beta\\.[0-9]+))?$",
            "description": "Major.minor of diggs-model; pre-releases add -draft or -beta.N.",
            "examples": [
              "1.0-draft",
              "1.0-beta.1",
              "1.0"
            ]
          },
          "tool": {
            "type": "object",
            "required": [
              "name",
              "version"
            ],
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1
              },
              "version": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          "source": {
            "$ref": "#/components/schemas/DiggsModelSource"
          },
          "complete": {
            "type": "boolean",
            "description": "False when a limit stopped reading; members read so far are kept."
          },
          "limits_hit": {
            "type": "array",
            "items": {
              "type": "string",
              "examples": [
                "time_budget"
              ]
            },
            "description": "Which limits stopped reading; empty when complete."
          },
          "document": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelDocumentInfo"
              },
              {
                "type": "null"
              }
            ],
            "description": "The DocumentInformation member, if any."
          },
          "projects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelProject"
            }
          },
          "associates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelAssociate"
            }
          },
          "features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelFeature"
            },
            "description": "Sampling features: boreholes, soundings, wells, and every other kind."
          },
          "sampling_activities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelSamplingActivity"
            }
          },
          "samples": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelSample"
            }
          },
          "observations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelObservation"
            }
          },
          "measurements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelMeasurement"
            },
            "description": "Tests, monitors, surveys: every measurement member."
          },
          "others": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelOther"
            },
            "description": "Top-level members with no typed mapper yet (header, links, extra)."
          },
          "crs": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/DiggsModelCrsRef"
            },
            "description": "Every coordinate reference system used, by key (the srsName as written)."
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelLink"
            },
            "description": "Every edge in document order; both directions are derivable."
          },
          "notes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsFindingsFinding"
            },
            "description": "What reading had to work around, as diggs-findings findings. Notes are not a validity verdict."
          }
        }
      },
      "DiggsModelDocumentInfo": {
        "description": "The DocumentInformation member.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "creation_date": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "DiggsModelDomain": {
        "type": "object",
        "required": [
          "shape",
          "index",
          "crs"
        ],
        "properties": {
          "shape": {
            "type": "string",
            "examples": [
              "point",
              "interval",
              "temporal",
              "grid2d",
              "grid3d",
              "none"
            ]
          },
          "index": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelColumn"
            },
            "description": "Columns that place each row: position (position_1 ... for more axes) for a multi-point location, top and base for one interval per row."
          },
          "crs": {
            "type": [
              "string",
              "null"
            ],
            "description": "srsName of the index values; key into the model's crs table."
          }
        }
      },
      "DiggsModelExtraNode": {
        "type": "object",
        "required": [
          "qname",
          "ns",
          "attrs",
          "text",
          "children",
          "line"
        ],
        "description": "A child element no typed field consumed, kept in document order.",
        "properties": {
          "qname": {
            "type": "string"
          },
          "ns": {
            "type": [
              "string",
              "null"
            ]
          },
          "attrs": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "text": {
            "type": [
              "string",
              "null"
            ]
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelExtraNode"
            }
          },
          "line": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          }
        }
      },
      "DiggsModelFeature": {
        "description": "A sampling feature.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "location": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelPosition"
              },
              {
                "type": "null"
              }
            ]
          },
          "centerline": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/DiggsModelPosition"
            }
          },
          "total_depth": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelQuantity"
              },
              {
                "type": "null"
              }
            ]
          },
          "lrs": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "when_constructed": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelTimeSpan"
              },
              {
                "type": "null"
              }
            ]
          },
          "construction": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelComponent"
            },
            "description": "How the feature was built: method, casing, backfill, hole diameter, flush, advancement, events; a well's casing, openings and installation events."
          },
          "water_strikes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelComponent"
            }
          },
          "parent": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          }
        }
      },
      "DiggsModelFieldLocation": {
        "type": "object",
        "required": [
          "xpath",
          "line"
        ],
        "description": "Where one value of a node was read, relative to the node's xpath.",
        "properties": {
          "xpath": {
            "type": "string",
            "description": "e.g. diggs:totalMeasuredDepth[1]"
          },
          "line": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          }
        }
      },
      "DiggsModelHeader": {
        "type": "object",
        "required": [
          "key",
          "gml_id",
          "element",
          "kind",
          "name",
          "names",
          "params",
          "provenance",
          "extra",
          "description",
          "remarks"
        ],
        "description": "Fields every node starts with.",
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "description": "gml:id when present and unique, else '@' + xpath. Unique in the model."
          },
          "gml_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "element": {
            "type": "string",
            "description": "DIGGS element name, after version aliases.",
            "examples": [
              "Borehole",
              "Test"
            ]
          },
          "kind": {
            "type": "string",
            "description": "Open vocabulary.",
            "examples": [
              "borehole",
              "sounding",
              "well",
              "test",
              "lithology"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "names": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "remarks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "params": {
            "$ref": "#/components/schemas/DiggsModelParams"
          },
          "provenance": {
            "$ref": "#/components/schemas/DiggsModelProvenance"
          },
          "extra": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelExtraNode"
            }
          }
        }
      },
      "DiggsModelInterval": {
        "type": "object",
        "required": [
          "top",
          "base",
          "lrs"
        ],
        "properties": {
          "top": {
            "$ref": "#/components/schemas/DiggsModelQuantity"
          },
          "base": {
            "$ref": "#/components/schemas/DiggsModelQuantity"
          },
          "lrs": {
            "type": [
              "string",
              "null"
            ],
            "description": "crs key of the linear referencing system."
          }
        }
      },
      "DiggsModelLink": {
        "type": "object",
        "required": [
          "source",
          "relation",
          "target",
          "href",
          "resolved"
        ],
        "properties": {
          "source": {
            "type": "string",
            "minLength": 1,
            "description": "Key of another node in this model."
          },
          "relation": {
            "type": "string",
            "description": "Element name without 'Ref'. Open vocabulary.",
            "examples": [
              "project",
              "samplingFeature",
              "sample",
              "samplingActivity"
            ]
          },
          "target": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "href": {
            "type": "string"
          },
          "resolved": {
            "type": "boolean"
          }
        }
      },
      "DiggsModelLithologyLayer": {
        "description": "One layer of a lithology observation.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "interval": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelInterval"
              },
              {
                "type": "null"
              }
            ]
          },
          "classification": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelCode"
            },
            "description": "Shortcut: the primary lithology's classification codes (classificationCode, classificationSymbol, legendCode, lithologyClassification)."
          },
          "colour": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelCode"
              },
              {
                "type": "null"
              }
            ],
            "description": "Shortcut: the primary lithology's colour code."
          },
          "geologic_unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "The unit name the layer gives."
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelComponent"
            },
            "description": "The layer's lithologies (primaryLithology, componentLithology), each with its constituents and colour nested."
          }
        }
      },
      "DiggsModelMeasurement": {
        "description": "A measurement: Test, Monitor, GeophysicalFieldSurvey, ...",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "feature": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "samples": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "description": "Key of another node in this model."
            }
          },
          "specimen": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "result_time": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelTimeSpan"
              },
              {
                "type": "null"
              }
            ]
          },
          "procedure": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelProcedure"
              },
              {
                "type": "null"
              }
            ]
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelResultTable"
            },
            "description": "Every result set under the measurement (outcome and procedure); columns have no values when read with results=False."
          }
        }
      },
      "DiggsModelObservation": {
        "description": "An observation system (lithology typed; others generic).",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "system": {
            "type": "string",
            "examples": [
              "LithologySystem",
              "DiscontinuitySystem"
            ]
          },
          "feature": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "layers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelLithologyLayer"
            }
          }
        }
      },
      "DiggsModelOther": {
        "description": "A top-level member with no typed mapper yet.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelResultTable"
            },
            "description": "Every result set under the member."
          }
        }
      },
      "DiggsModelParam": {
        "description": "A simple value: a quantity (the element had a uom), a code (a codeSpace) or text.",
        "anyOf": [
          {
            "$ref": "#/components/schemas/DiggsModelQuantity"
          },
          {
            "$ref": "#/components/schemas/DiggsModelCode"
          },
          {
            "type": "string"
          }
        ]
      },
      "DiggsModelParams": {
        "type": "object",
        "description": "Simple values by DIGGS element name: every child with no child elements that appears once and has no attribute but uom or codeSpace. Everything else stays in extra.",
        "additionalProperties": {
          "$ref": "#/components/schemas/DiggsModelParam"
        }
      },
      "DiggsModelPosition": {
        "type": "object",
        "required": [
          "coordinates",
          "dim",
          "crs",
          "geographic",
          "transformed_by"
        ],
        "properties": {
          "coordinates": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "As written, in the CRS's own axis order."
          },
          "dim": {
            "type": "integer",
            "minimum": 1,
            "maximum": 3
          },
          "crs": {
            "type": [
              "string",
              "null"
            ],
            "description": "Key into the model's crs table."
          },
          "geographic": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "lon",
              "lat",
              "datum"
            ],
            "description": "Filled in core only for geographic CRSs; datum recorded, never shifted.",
            "properties": {
              "lon": {
                "type": "number"
              },
              "lat": {
                "type": "number"
              },
              "h": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "datum": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "transformed_by": {
            "type": [
              "string",
              "null"
            ],
            "description": "Set only by pydiggs[gis], e.g. 'pydiggs[gis] pyproj 3.8'."
          }
        }
      },
      "DiggsModelProcedure": {
        "type": "object",
        "required": [
          "type",
          "params",
          "components",
          "extra"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Procedure element. Open vocabulary.",
            "examples": [
              "DrivenPenetrationTest",
              "StaticConePenetrationTest",
              "AtterbergLimitsTest"
            ]
          },
          "params": {
            "$ref": "#/components/schemas/DiggsModelParams"
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelComponent"
            },
            "description": "Nested records: SPT drive sets, equipment, trials, sieve analyses ..."
          },
          "extra": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelExtraNode"
            }
          }
        }
      },
      "DiggsModelProject": {
        "description": "A Project.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "client": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "locality": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "DiggsModelProvenance": {
        "type": "object",
        "required": [
          "xpath",
          "line",
          "fields"
        ],
        "description": "Where the node is, in the same form as a diggs-findings location.",
        "properties": {
          "xpath": {
            "type": "string",
            "description": "e.g. /diggs:Diggs[1]/diggs:samplingFeature[2]/diggs:Borehole[1]"
          },
          "line": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1
          },
          "fields": {
            "type": [
              "object",
              "null"
            ],
            "description": "Filled only by read(..., provenance=\"field\"): for each child element the node read a value from, keyed by its local name (name[2] for a second one).",
            "additionalProperties": {
              "$ref": "#/components/schemas/DiggsModelFieldLocation"
            }
          }
        }
      },
      "DiggsModelQuantity": {
        "type": "object",
        "required": [
          "text",
          "value",
          "uom",
          "si"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "Exactly as reported."
          },
          "value": {
            "type": [
              "number",
              "null"
            ]
          },
          "uom": {
            "type": [
              "string",
              "null"
            ]
          },
          "si": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "value",
              "uom"
            ],
            "description": "Present only when the unit converts; never silently.",
            "properties": {
              "value": {
                "type": "number"
              },
              "uom": {
                "type": "string"
              }
            }
          }
        }
      },
      "DiggsModelResultTable": {
        "type": "object",
        "required": [
          "domain",
          "columns",
          "row_count",
          "location",
          "extent"
        ],
        "properties": {
          "domain": {
            "$ref": "#/components/schemas/DiggsModelDomain"
          },
          "columns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DiggsModelColumn"
            }
          },
          "row_count": {
            "type": "integer",
            "minimum": 0
          },
          "location": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelPosition"
              },
              {
                "type": "null"
              }
            ],
            "description": "The single point the whole table was measured at, when the result gives one."
          },
          "extent": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelInterval"
              },
              {
                "type": "null"
              }
            ],
            "description": "The single interval the whole table was measured over, when the result gives one."
          }
        }
      },
      "DiggsModelSample": {
        "description": "A Sample. interval, method and recovery are copied from the sampling activity that produced it; type is its classification.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "feature": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "sampling_activity": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "interval": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelInterval"
              },
              {
                "type": "null"
              }
            ]
          },
          "method": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelCode"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelCode"
              },
              {
                "type": "null"
              }
            ]
          },
          "recovery": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelQuantity"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "DiggsModelSamplingActivity": {
        "description": "A SamplingActivity.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DiggsModelHeader"
          }
        ],
        "type": "object",
        "required": [],
        "properties": {
          "feature": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "description": "Key of another node in this model, or null."
          },
          "interval": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelInterval"
              },
              {
                "type": "null"
              }
            ]
          },
          "method": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelCode"
              },
              {
                "type": "null"
              }
            ]
          },
          "recovery": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelQuantity"
              },
              {
                "type": "null"
              }
            ]
          },
          "date": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DiggsModelTimeSpan"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "DiggsModelSource": {
        "type": "object",
        "required": [
          "name",
          "sha256",
          "size",
          "diggs_version",
          "namespace",
          "detected"
        ],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "Of the bytes as read; scopes every key."
          },
          "size": {
            "type": "integer",
            "minimum": 0
          },
          "diggs_version": {
            "type": "string",
            "examples": [
              "2.5.a",
              "2.6",
              "3.0.0",
              "3.1-dev"
            ]
          },
          "namespace": {
            "type": [
              "string",
              "null"
            ]
          },
          "detected": {
            "type": "boolean",
            "description": "False when the caller named the version."
          }
        }
      },
      "DiggsModelTimeSpan": {
        "type": "object",
        "required": [
          "start",
          "end"
        ],
        "description": "A time instant (start only) or interval, each end exactly as written.",
        "properties": {
          "start": {
            "type": [
              "string",
              "null"
            ]
          },
          "end": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Problem": {
        "title": "Problem",
        "description": "RFC 9457 problem details. Switch on `code`; every text is fixed.",
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "enum": [
              "busy",
              "compressed-input",
              "cross-site",
              "input-too-large",
              "input-unreadable",
              "internal",
              "invalid-document",
              "invalid-host",
              "invalid-multipart",
              "invalid-parameter",
              "method-not-allowed",
              "missing-input",
              "not-acceptable",
              "not-found",
              "not-ready",
              "request-timeout",
              "resource-error",
              "result-too-large",
              "timeout",
              "unsupported-media-type"
            ]
          },
          "errors": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "required": [
                "parameter",
                "problem"
              ],
              "properties": {
                "parameter": {
                  "type": "string"
                },
                "problem": {
                  "type": "string"
                }
              }
            }
          },
          "correlation_id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "description": "For invalid-document: why the bytes are not a document of the expected format (DIGGS XML, or AGS4 for a conversion to DIGGS).",
            "examples": [
              "malformed",
              "not-diggs",
              "unsafe-entity",
              "namespace-too-long",
              "not-ags4",
              "unsupported-version"
            ]
          }
        }
      },
      "Ready": {
        "title": "Ready",
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "const": "ready"
          }
        }
      },
      "RuleInfo": {
        "title": "RuleInfo",
        "description": "One rule id pydiggs can emit (or an open family, as a pattern).",
        "type": "object",
        "required": [
          "id",
          "pattern",
          "step",
          "description",
          "severities",
          "help_uri",
          "known"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "pattern": {
            "type": [
              "string",
              "null"
            ]
          },
          "step": {
            "enum": [
              "structure",
              "schema",
              "codeType",
              "dictionary",
              "schematron",
              "geometry",
              "crs",
              "coordinate",
              "deprecation",
              "context",
              "ags4",
              "convert",
              "diff"
            ]
          },
          "description": {
            "type": "string"
          },
          "severities": {
            "type": "array",
            "items": {
              "enum": [
                "error",
                "warning",
                "info"
              ]
            }
          },
          "help_uri": {
            "type": "string"
          },
          "known": {
            "type": "boolean"
          },
          "guidance": {
            "type": [
              "object",
              "null"
            ],
            "description": "Plain-language guidance for engineers: a short title, what the rule means for the data, and how to fix it. Null for an unknown rule id.",
            "required": [
              "title",
              "meaning",
              "fix",
              "locale"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "meaning": {
                "type": "string"
              },
              "fix": {
                "type": "string"
              },
              "locale": {
                "type": "string",
                "examples": [
                  "en"
                ]
              }
            }
          }
        }
      },
      "SarifLog": {
        "title": "SARIF 2.1.0 log",
        "description": "A SARIF 2.1.0 log with one run (sent for Accept: application/sarif+json).",
        "type": "object",
        "required": [
          "version",
          "runs"
        ],
        "properties": {
          "version": {
            "const": "2.1.0"
          },
          "runs": {
            "type": "array"
          }
        }
      },
      "Versions": {
        "title": "Versions",
        "description": "The running pydiggs, its findings schema and bundled reference data.",
        "type": "object",
        "required": [
          "api_version",
          "pydiggs_version",
          "findings_schema_version",
          "findings_schema_url",
          "diggs_versions",
          "reference_data"
        ],
        "properties": {
          "api_version": {
            "const": "1"
          },
          "pydiggs_version": {
            "type": "string"
          },
          "findings_schema_version": {
            "type": "string"
          },
          "findings_schema_url": {
            "type": "string",
            "format": "uri"
          },
          "diggs_versions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reference_data": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
