{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://xinp-hub.github.io/pydiggs/schemas/diggs-diff-1.0.schema.json",
  "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": "#/$defs/source" },
    "new": { "$ref": "#/$defs/source" },
    "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": "#/$defs/counts" },
      "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": "#/$defs/change" },
      "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": "#/$defs/note" },
      "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 } } }
    }
  ],
  "$defs": {
    "note": {
      "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 }
      }
    },
    "source": {
      "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" }
      }
    },
    "counts": {
      "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 }
      }
    },
    "op": {
      "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."
    },
    "change": {
      "type": "object",
      "required": [
        "op",
        "collection",
        "element",
        "name",
        "old_key",
        "new_key",
        "matched_by",
        "truncated",
        "values"
      ],
      "properties": {
        "op": { "$ref": "#/$defs/op" },
        "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": "#/$defs/value_change" } }
      }
    },
    "value_change": {
      "type": "object",
      "required": ["op", "path", "old", "new", "at", "truncated"],
      "properties": {
        "op": { "$ref": "#/$defs/op" },
        "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."
        }
      }
    }
  }
}
