tods-validate/docs/report.schema.json at main · ghzhost/tods-validate · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/ChelseaKR/tods-validate/main/docs/report.schema.json",
  "title": "tods-validate JSON report",
  "description": "Output of `tods-validate validate --format json`. Stable: fields are only added, never removed or renamed, within a major version.",
  "type": "object",
  "required": ["validator", "specVersion", "source", "summary", "findings"],
  "properties": {
    "validator": { "const": "tods-validate" },
    "toolVersion": {
      "type": "string",
      "description": "Version of tods-validate that produced the report."
    },
    "reportVersion": {
      "type": "string",
      "description": "Version of this report schema. Fields are only added within a major version."
    },
    "specVersion": {
      "type": "string",
      "description": "TODS specification version the rules implement."
    },
    "source": {
      "type": "string",
      "description": "The path that was validated, as given on the command line."
    },
    "summary": {
      "type": "object",
      "required": ["errors", "warnings", "infos"],
      "properties": {
        "errors": { "type": "integer", "minimum": 0 },
        "warnings": { "type": "integer", "minimum": 0 },
        "infos": { "type": "integer", "minimum": 0 },
        "byRule": {
          "type": "object",
          "description": "Count of findings per rule ID, most frequent first.",
          "additionalProperties": { "type": "integer", "minimum": 1 }
        }
      },
      "additionalProperties": false
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["rule_id", "severity", "file", "row", "field", "location", "data", "message", "suggestion", "caused_by", "fingerprint", "severity_original"],
        "properties": {
          "rule_id": { "type": "string", "pattern": "^TODS-[EWI][0-9]{3}$" },
          "severity": { "enum": ["ERROR", "WARNING", "INFO"] },
          "file": { "type": ["string", "null"] },
          "row": {
            "type": ["integer", "null"],
            "minimum": 1,
            "description": "1-based line number; the header row is line 1."
          },
          "field": { "type": ["string", "null"] },
          "location": {
            "type": ["string", "null"],
            "description": "Stable machine location identifier, e.g. 'run_events.txt#L4/end_time'."
          },
          "data": {
            "type": ["object", "null"],
            "description": "Structured machine context (offending value, referenced ID, etc.). Additive; null for rules not yet migrated to emit it.",
            "additionalProperties": { "type": "string" }
          },
          "message": { "type": "string" },
          "suggestion": { "type": ["string", "null"] },
          "caused_by": {
            "type": ["string", "null"],
            "description": "Location identifier (see 'location') of the root finding that structurally caused this one, e.g. a TODS-E104 ragged row that left this field blank. Null when this finding is not a known downstream echo of another."
          },
          "fingerprint": {
            "type": "string",
            "description": "SHA-256 hex content fingerprint used as the --baseline identity (rule_id, file, field, data); excludes row and message so inserted rows don't churn a baseline."
          },
          "severity_original": {
            "enum": ["ERROR", "WARNING", "INFO", null],
            "description": "The rule's spec-declared severity, set only when a config `[severity]` table remapped `severity` to a different value. Every remapped finding is also disclosed in text/Markdown/SARIF/HTML output."
          }
        },
        "additionalProperties": false
      }
    },
    "coverage": {
      "type": "object",
      "description": "Validation-assurance manifest: which rules ran versus were skipped and why. Added in report schema 1.2.0.",
      "required": ["total", "ran", "skipped", "skippedByReason", "rules"],
      "properties": {
        "total": { "type": "integer", "minimum": 0 },
        "ran": { "type": "integer", "minimum": 0 },
        "skipped": { "type": "integer", "minimum": 0 },
        "skippedByReason": {
          "type": "object",
          "description": "Rule IDs skipped, keyed by status (e.g. 'skipped:needs_gtfs').",
          "additionalProperties": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["id", "severity", "category", "status"],
            "properties": {
              "id": { "type": "string" },
              "severity": { "enum": ["ERROR", "WARNING", "INFO"] },
              "category": { "type": "string" },
              "status": {
                "description": "'ran' means the check executed against data it could read. Every other value is a skip: the check did not run, and its rule must not be read as passed. 'skipped:needs_gtfs_table' means a companion feed was available but did not contain a GTFS file the check reads.",
                "enum": [
                  "ran",
                  "skipped:needs_gtfs",
                  "skipped:needs_gtfs_table",
                  "skipped:disabled",
                  "skipped:ignored",
                  "skipped:spec_version"
                ]
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "suggestions": {
      "type": "array",
      "description": "Machine-form companion to the text/Markdown --suggest block: one entry per mechanically-derived fix. Present only when --suggest is used with JSON output. Added in report schema 1.3.0.",
      "items": {
        "type": "object",
        "required": ["rule_id", "kind", "file", "row", "field", "current", "proposed", "description"],
        "properties": {
          "rule_id": { "type": "string", "pattern": "^TODS-[EWI][0-9]{3}$" },
          "kind": {
            "enum": ["auto", "review"],
            "description": "'auto' is meaning-preserving (tods-validate fix applies it); 'review' wants a human's confirmation."
          },
          "file": { "type": ["string", "null"] },
          "row": {
            "type": ["integer", "null"],
            "minimum": 1,
            "description": "1-based line number; the header row is line 1."
          },
          "field": { "type": ["string", "null"] },
          "current": {
            "type": ["string", "null"],
            "description": "The value found in the feed, when the fix changes one value."
          },
          "proposed": {
            "type": ["string", "null"],
            "description": "The value the fix would write, when the fix changes one value."
          },
          "description": { "type": "string" }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}