Change record status: 
Project: 
Introduced in branch: 
8.8.x
Introduced in version: 
8.8.0
Description: 

Until now, Drupal core has been setting the wrong example: it has been implementing normalizers at the @FieldType plugin level. It should have been implementing normalizers at the @DataType plugin level.

It's better to implement them at the @DataType plugin level, because then the normalizers can be reused by both the default normalization (used for the json and xml formats, provided by core's Serialization module) as well as the hal format (provided by core's HAL module).

Field-level normalizers need to be duplicated, for example #2768651: Let TimestampItem (de)normalize to/from RFC3339 timestamps, not UNIX timestamps, for better DX added a TimestampItemNormalizer to both the Serialization and HAL modules. When considering the contrib JSON API module (which we're working to bring to Drupal core), that would be yet another duplicate.
This is untenable. Not only does this mean duplication of effort and increased complexity, it also means more opportunity for subtle unintentional differences, which make automatic API docs (via OpenAPI) more and more difficult. Perhaps worst of all, it means that some fields cannot be normalized at all, or not in a sane way, for certain formats. Because the necessary duplication hasn't happened yet!

To strengthen the API-First ecosystem, and ensure that future normalizers work everywhere automatically — for serialization (json + xml formats), hal (hal_json format) and jsonapi (api_json format), we're codifying what has already been recommended best practice in the issue queues and discussions.

For detailed background, see the https://www.drupal.org/project/drupal/issues/2926507 issue summary

Impacts: 
Module developers