diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index d3cef1a25..099c65a73 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -83,6 +83,7 @@
   - [Updating LLVM](./codegen/updating-llvm.md)
   - [Debugging LLVM](./codegen/debugging.md)
 - [Emitting Diagnostics](./diag.md)
+  - [JSON diagnostic format](./diag/json-format.md)
 
 ---
 
diff --git a/src/diag/json-format.md b/src/diag/json-format.md
new file mode 100644
index 000000000..6ba555b1d
--- /dev/null
+++ b/src/diag/json-format.md
@@ -0,0 +1,36 @@
+# JSON diagnostic output
+
+The compiler accepts an `--error-format json` flag to output
+diagnostics as JSON objects (for the benefit of tools such as `cargo
+fix` or the RLS). It looks like this—
+
+```ignore
+$ rustc json_error_demo.rs --error-format json
+{"message":"cannot add `&str` to `{integer}`","code":{"code":"E0277","explanation":"\nYou tried to use a type which doesn't implement some trait in a place which\nexpected that trait. Erroneous code example:\n\n```compile_fail,E0277\n// here we declare the Foo trait with a bar method\ntrait Foo {\n    fn bar(&self);\n}\n\n// we now declare a function which takes an object implementing the Foo trait\nfn some_func<T: Foo>(foo: T) {\n    foo.bar();\n}\n\nfn main() {\n    // we now call the method with the i32 type, which doesn't implement\n    // the Foo trait\n    some_func(5i32); // error: the trait bound `i32 : Foo` is not satisfied\n}\n```\n\nIn order to fix this error, verify that the type you're using does implement\nthe trait. Example:\n\n```\ntrait Foo {\n    fn bar(&self);\n}\n\nfn some_func<T: Foo>(foo: T) {\n    foo.bar(); // we can now use this method since i32 implements the\n               // Foo trait\n}\n\n// we implement the trait on the i32 type\nimpl Foo for i32 {\n    fn bar(&self) {}\n}\n\nfn main() {\n    some_func(5i32); // ok!\n}\n```\n\nOr in a generic context, an erroneous code example would look like:\n\n```compile_fail,E0277\nfn some_func<T>(foo: T) {\n    println!(\"{:?}\", foo); // error: the trait `core::fmt::Debug` is not\n                           //        implemented for the type `T`\n}\n\nfn main() {\n    // We now call the method with the i32 type,\n    // which *does* implement the Debug trait.\n    some_func(5i32);\n}\n```\n\nNote that the error here is in the definition of the generic function: Although\nwe only call it with a parameter that does implement `Debug`, the compiler\nstill rejects the function: It must work with all possible input types. In\norder to make this example compile, we need to restrict the generic type we're\naccepting:\n\n```\nuse std::fmt;\n\n// Restrict the input type to types that implement Debug.\nfn some_func<T: fmt::Debug>(foo: T) {\n    println!(\"{:?}\", foo);\n}\n\nfn main() {\n    // Calling the method is still fine, as i32 implements Debug.\n    some_func(5i32);\n\n    // This would fail to compile now:\n    // struct WithoutDebug;\n    // some_func(WithoutDebug);\n}\n```\n\nRust only looks at the signature of the called function, as such it must\nalready specify all requirements that will be used for every type parameter.\n"},"level":"error","spans":[{"file_name":"json_error_demo.rs","byte_start":50,"byte_end":51,"line_start":4,"line_end":4,"column_start":7,"column_end":8,"is_primary":true,"text":[{"text":"    a + b","highlight_start":7,"highlight_end":8}],"label":"no implementation for `{integer} + &str`","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"the trait `std::ops::Add<&str>` is not implemented for `{integer}`","code":null,"level":"help","spans":[],"children":[],"rendered":null}],"rendered":"error[E0277]: cannot add `&str` to `{integer}`\n --> json_error_demo.rs:4:7\n  |\n4 |     a + b\n  |       ^ no implementation for `{integer} + &str`\n  |\n  = help: the trait `std::ops::Add<&str>` is not implemented for `{integer}`\n\n"}
+{"message":"aborting due to previous error","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to previous error\n\n"}
+{"message":"For more information about this error, try `rustc --explain E0277`.","code":null,"level":"","spans":[],"children":[],"rendered":"For more information about this error, try `rustc --explain E0277`.\n"}
+```
+
+Note that the output is a series of lines, each of which is a JSON
+object, but the series of lines taken together is, unfortunately, not
+valid JSON, thwarting tools and tricks (such as [piping to `python3 -m
+json.tool`](https://docs.python.org/3/library/json.html#module-json.tool))
+that require such. (One speculates that this was intentional for LSP
+performance purposes, so that each line/object can be sent to RLS as
+it is flushed?)
+
+Also note the "rendered" field, which contains the "human" output as a
+string; this was introduced so that UI tests could both make use of
+the structured JSON and see the "human" output (well, _sans_ colors)
+without having to compile everything twice.
+
+The JSON emitter currently lives in libsyntax/json.rs. (But arguably
+it should live in librustc_errors along with the "human" emitter? It's
+not obvious to the present author why it wasn't moved from libsyntax
+to librustc_errors at the same [time the "human" emitter was
+moved](https://github.com/rust-lang/rust/commit/6ae3502134).)
+
+The JSON emitter defines [its own `Diagnostic`
+struct](https://github.com/rust-lang/rust/blob/b2c6b8c29f13f8d1f242da89e587960b95337819/src/libsyntax/json.rs#L85-L99)
+(and sub-structs) for the JSON serialization. Don't confuse this with
+[`errors::Diagnostic`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Diagnostic.html)!