doc: document JSON modules and --es-module-specifier-resolution

doc/api/cli.md

@@ -134,6 +134,27 @@ added: v6.0.0
 Enable FIPS-compliant crypto at startup. (Requires Node.js to be built with
 `./configure --openssl-fips`.)
 
+### `--es-module-specifier-resolution=mode`
+<!-- YAML
+added: REPLACEME
+-->
+
+To be used in conjunction with `--experimental modules`. Sets the resolution
+algorithm for resolving specifiers. Valid options are `explicit` and `node`.
+
+The default is `explicit`, which requires you to provide the full path to a
+module. The `node` mode will enable support for optional file extensions and
+the ability to import a directory that has an index file.
+
+Please see [customizing esm specifier resolution][] for example usage.
+
+### `--experimental-json-modules`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable experimental JSON support for the ES Module loader.
+
 ### `--experimental-modules`
 <!-- YAML
 added: v8.5.0
@@ -911,7 +932,8 @@ greater than `4` (its current default value). For more information, see the
 [debugger]: debugger.html
 [debugging security implications]: https://nodejs.org/en/docs/guides/debugging-getting-started/#security-implications
 [emit_warning]: process.html#process_process_emitwarning_warning_type_code_ctor
-[experimental ECMAScript Module]: esm.html#esm_experimental_loader_hooks
+[experimental ECMAScript Module]: esm.html#esm_resolve_hook
+[customizing esm specifier resolution]: esm.html#esm_customizing_esm_specifier_resolution_algorithm
 [libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
 [remote code execution]: https://www.owasp.org/index.php/Code_Injection
 [secureProtocol]: tls.html#tls_tls_createsecurecontext_options

doc/api/esm.md

@@ -7,9 +7,13 @@
 
 ## Introduction
 
-ECMAScript modules are the official standard format to package JavaScript code for reuse. Modules are defined using a variety of [`import`][] and [`export`][] statements.
+ECMAScript modules are the official standard format to package JavaScript code
+for reuse. Modules are defined using a variety of [`import`][] and [`export`][]
+statements.
 
-Node.js fully supports ECMAScript modules as they are currently specified and provides limited interoperability between them and the existing module format, [CommonJS][]. 
+Node.js fully supports ECMAScript modules as they are currently specified and
+provides limited interoperability between them and the existing module format,
+[CommonJS][].
 
 <!--name=esm-->
 
@@ -390,6 +394,39 @@ fs.readFileSync = () => Buffer.from('Hello, ESM');
 fs.readFileSync === readFileSync;
 ```
 
+## Experimental JSON Modules
+
+**Note: This API is still being designed and is subject to change.**.
+
+Currently importing JSON modules are only supported in the `commonjs` mode
+and are loaded using the CJS loader. [WHATWG JSON modules][] are currently
+being standardized, and are experimentally supported by including the
+additional flag `--experimental-json-modules` when running Node.js.
+
+When the `--experimental-json-modules` flag is included both the
+`commonjs` and `module` mode will use the new experimental JSON
+loader. The imported JSON only exposes a `default`, there is no
+support for named exports. A cache entry is created in the CommonJS
+cache, to avoid duplication. The same object will be returned in
+CommonJS if the JSON module has already been imported from the
+same path.
+
+Assuming an `index.js` with
+
+<!-- eslint-skip -->
+```js
+import packageConfig from './package.json';
+```
+
+You will need to include the `--experimental-json-modules` flag for the module
+to work.
+
+<!-- eslint-skip -->
+```bash
+node --experimental-modules --type=module index.js # fails
+node --experimental-modules --type=module --experimental-json-modules index.js # works
+```
+
 ## Experimental Loader hooks
 
 **Note: This API is currently being redesigned and will still change.**.
@@ -659,6 +696,28 @@ READ_PACKAGE_JSON(_packageURL_)
 
 </details>
 
+### Customizing ESM specifier resolution algorithm
+
+The current specifier resolution does not support all default behavior of
+the CommonJS loader. One of the behavior differences is automatic resolution
+of file extensions and the ability to import directories that have an index
+file.
+
+By using the `--es-module-specifier-resolution=[mode]` flag you can customize
+the extension resolution algorithm. The default mode is `explicit`, which
+requires the full path to a module be provided to the loader. To enable the
+automatic extension resolution and importing from directories that include an
+index file use the `node` mode.
+
+```bash
+$ node --experimental-modules index.mjs
+success!
+$ node --experimental-modules index #Failure!
+Error: Cannot find module
+$ node --experimental-modules --es-module-specifier-resolution=node index
+success!
+```
+
 [`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
 [`export`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export
 [CommonJS]: modules.html
@@ -668,3 +727,4 @@ READ_PACKAGE_JSON(_packageURL_)
 [`import.meta.url`]: #esm_import_meta
 [`import()`]: #esm_import-expressions
 [ecmascript-modules implementation]: https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md
+[WHATWG JSON modules]: https://github.com/whatwg/html/issues/4315