You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: proposals/0000-specify-dump-json.md
+12-5Lines changed: 12 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -104,13 +104,15 @@ The output of the JSON dump would consist of a list of errors, as well as a top
104
104
- `"code"` corresponding to the change in this [proposal](https://github.com/haskellfoundation/tech-proposals/blob/main/proposals/accepted/024-error-messages.md) and the above `DiagnosticCode` in typeclass `Diagnostic`
105
105
- this is required by the schema but is allowed to have a value of`null`.The hope is that once all diagnostics officially have error codes, this can be required and nonnullable, but that will happen once `diagnosticCode` itself doesn't return a `DiagnosticCode` wrapped in a `Maybe`
106
106
- `"hints"` corresponding to the above `[GhcHint]`
107
+
-While these are required by the schema, `[]` is an allowed value
107
108
-The schema itself doesn't validate at all what these may be, only that they are themselves objects.In my view, the best way to handle them is to output a JSON-ified version of the type `GhcHint`.Any attempt to specify them more than that will result in spiraling complexity and a required update every time the `GhcHint` type changes.Another alternative is to just remove them from the output and only present suggestions as they are rendered in the `message`.
108
109
- `"message"` corresponding to `DecoratedSDoc` of`diagnosticMessage`
109
110
- this is required by the schema, and is the actual string output produced at the command line
110
111
111
112
The top level version is crucial for indicating to downstream consumers which JSON schema they must comply with in the case that the schema is updated in the future (which is quite likely).
112
113
113
114
Information encoded in`diagnosticReason` is not included in this initial version, as that feature is currently unstable.It can be incorporated down the line once it is both more stable and there is a desire to consume that information from users.
115
+
114
116
For demonstrative purposes, here is an example valid instance of the schema.
115
117
```json
116
118
{
@@ -120,13 +122,18 @@ For demonstrative purposes, here is an example valid instance of the schema.
120
122
{
121
123
"span": {
122
124
"file":"typecheck/should_fail/T2414.hs",
123
-
"startLine":9,
124
-
"startCol":13,
125
-
"endLine":9,
126
-
"endCol":17
125
+
"start": {
126
+
"line":9,
127
+
"column":13
128
+
},
129
+
"end": {
130
+
"line":9,
131
+
"column":17
132
+
}
127
133
},
128
134
"severity":"Error",
129
135
"code":27958,
136
+
"hints":[],
130
137
"message":" • Couldn't match type ‘b0’ with ‘(Bool, b0)’ \n Expected: b0 -> Maybe (Bool, b0) \nActual: b0 -> Maybe b0 \n• In the first argument of ‘unfoldr’, namely ‘Just’ \nIn the expression: unfoldr Just \nIn an equation for ‘f’: f = unfoldr Just"
131
138
}
132
139
]
@@ -137,7 +144,7 @@ The schema itself will be brought into version control of the GHC repo and tests
137
144
138
145
One of the major benefits of utilizing a JSON schema is that the expected JSON payload can be well-defined for consumers of the messages. This has massive benefits, as consumers can presume the structure of the output without having to analyze the contents for the presence or absence of particular bits of data. However, one drawback may be the over specification of the output. There may be some opportunities in which flexibility is a benefit for the output. However, this schema can be adapted as further feedback rolls in (with incremented version), making the good net outweigh the bad.
139
146
140
-
In addition to adding a `-dump-json` flag, it may also prove useful to provide a `-dump-json-schema` flag which simply produces the relevant JSON schema for that particular version of GHC. This I leave open for discussion. Provided that the schema is in an easy to find location, it may be overkill.
147
+
In addition to adding a `-dump-diags-json` flag, it may also prove useful to provide a `-dump-diags-json-schema` flag which simply produces the relevant JSON schema for that particular version of GHC. This I leave open for discussion. Provided that the schema is in an easy to find location, it may be overkill.
141
148
142
149
The schema evolution process is currently undetermined, though I imagine that due to the infrequency with which the schema will need to be changed, it can be handled on a case-by-base basis. Though keeping a running list of all relevant stakeholders that may need to be informed could be a good idea.
0 commit comments