Add JSON:API to core as a stable module

Problem/Motivation

See #2836165: New experimental module: JSON API and #2757967: API-first initiative.

Proposed resolution

Drop in of the JSON:API module.

Remaining tasks

In no particular order,

• Provide a patch. Blocked by #2931785: The path for JSON API to core
• Review the code. Reviewed: see #110 and #114.
• Decide on stability of the module in core. Related to #2842148: The path for JSON API to "super stability" Decided: stable in 8.7.0, see #71.
• Provide a migration plan for users of the existing contrib module. Done: see #91.
• Propose a plan for core to "dog food" this new API. (The actual implementation does not block this issue)

User interface changes

No user interface changes.

API changes

No API changes. Only additions isolated in the experimental module.

Data model changes

No data model changes.

Added dependencies

Production: None!
Dev (require-dev):

• justinrainbow/json-schema:
  • Code quality: documented, comprehensive tests
  • Maintainership of the package: recent releases (latest release was in Jan. 2019); apparently actively maintained.
  • Security policies of the package: unknown
  • Expected release and support cycles: undocumented; sporadic releases
  • Other dependencies it'd add, if any:
    

    "require": {
            "php": ">=5.3.3",
            "marc-mabe/php-enum": "2.3.1",
            "icecave/parity": "1.0.0"
        }

Migration from the contrib module

The ideal migration path is:

1. update from 8.x-1.x to 8.x-2.x while you're on Drupal 8.5 or Drupal 8.6; this may require some changes to JSON:API clients
2. update from Drupal 8.5 or 8.6 + JSON:API 8.x-2.x to Drupal 8.7 and uninstall the contrib jsonapi module (this is exactly what we told sites using the contrib bigpipe module when they upgraded to Drupal 8.1)

For sites that don't want to or cannot invest in updating from JSON:API 8.x-1.x to 8.x-2.x: they can continue to keep the jsonapi contrib module installed, the same 8.x-1.x version. This overrides core's jsonapi module. IOW: even though JSON:API is part of core, this makes Drupal ignore the core module and pick the contrib module instead. @gabesullice manually vetted this.

More information wrt JSON:API module branches and how they're supported

The JSON:API module has 2 branches in contrib: 8.x-1.x and 8.x-2.x. The 8.x-1.x branch has been minimally maintained (security updates only) since June 2018, since 1.22. That branch was first maximally stabilized.
To comply with the JSON:API spec completely, we had to make certain changes that are disruptive to some JSON:API 8.x-1.x users/clients. That's why we opened the 8.x-2.x branch. This new branch is explicitly compatible with not only Drupal 8.6 (current stable) and Drupal 8.7 (the core minor we're targeting for including JSON:API), but also Drupal 8.5 (which currently receives only security updates). This means that JSON:API 8.x-2.x is supported on all secure Drupal 8.x releases. Which in turn means that every JSON:API 8.x-1.x user (which must currently use Drupal 8.5 or 8.6) can first update to 8.x-2.x. And then update to Drupal 8.7. This gives them maximal freedom to update.
The 8.x-2.x branch of the JSON:API contrib module will continue to receive security updates for as long as Drupal 8.6 receives security updates. And so will the JSON:API 8.x-1.x branch.