Add "subfield name" to storage settings for Double Field, for better normalization in core REST, JSON API and GraphQL

I would like someone with JSON API experience make a review.

I am … very confused by this code :D

This patch is achieving "better keys" by subclassing ResourceFieldEnhancerBase, which is a JSON API extras addition. But JSON API Extras designed to override things.

Why not fix the root cause? You can do that by writing a normalizer (see https://www.drupal.org/docs/8/api/serialization-api/serialization-api-ov...). Then it would work in core REST, and in JSON API — even without installing JSON API Extras! See \Drupal\serialization\Normalizer\TimestampItemNormalizer and \Drupal\serialization\Normalizer\EntityReferenceFieldItemNormalizer for examples. More of these field type-specific normalizers are being worked on, and will be landing in the coming days, weeks and months in Drupal core :)

Oh… well you could add new optional settings to Double Field?

Can this be done by setting supportedInterfaceOrClass property of the normalizer?

Yes.

The approach with normalizer seems super simple.

double_field.services.yml

services:
  serializer.normalizer.double_field:
    class: Drupal\double_field\Normalizer\DoubleFieldItemNormalizer
    tags:
      - { name: normalizer, priority: 10 }

src/Normalizer/DoubleFieldItemNormalizer.php

namespace Drupal\double_field\Normalizer;

use Drupal\double_field\Plugin\Field\FieldType\DoubleField;
use Drupal\serialization\Normalizer\NormalizerBase;

/**
 * Converts values for DoubleFieldItem.
 */
class DoubleFieldItemNormalizer extends NormalizerBase {

  /**
   * {@inheritdoc}
   */
  protected $supportedInterfaceOrClass = DoubleField::class;

  /**
   * {@inheritdoc}
   */
  public function normalize($field, $format = NULL, array $context = array()) {
    $value = $field->getValue();
    return [
      'description' => $value['first'],
      'size' => $value['second'],
    ];
  }

}

Unfortunately normalizers are not configurable and Double field has no appropriate settings to make use. Introducing additional configuration to field instance for such a specific case as renaming properties in JSON output does not seem a good idea.

This could probably be a Field Enhancer in JSON API extras.

Introducing additional configuration to field instance for such a specific case as renaming properties in JSON output does not seem a good idea.

But if it's implemented at the normalizer level, then that will only work in the JSON API module (or only in the REST module), but it will not work in https://www.drupal.org/project/graphql nor in https://www.drupal.org/project/openapi.

Ideally, DoubleField::propertyDefinitions() would not use first and second as property names, but it'd use configurable, named properties. That's only possible if those property names were defined in the accompanying field storage definition (FieldStorageDefinitionInterface).

If it's possible to store a "subfield type" in the field storage definition, then surely it's also possible to store a name for them? Then

    foreach (['first', 'second'] as $subfield) {
      $subfield_type = $settings['storage'][$subfield]['type'];
…
      $properties[$subfield] = …

could be modified to

    foreach (['first', 'second'] as $subfield) {
      $subfield_type = $settings['storage'][$subfield]['type'];
…
      $subfield_name = $settings['storage'][$subfield]['name'];
      $properties[$subfield_name] = …     

(And for BC, you can generate the defaults to be first and second, so that existing Double Fields continue to work as they do today.)

That would then make Double Field compatible with all API-First modules.

Anyone who has time to implement this as described in #17 feel free to reopen the issue.