Use OptionsProviderInterface::getPossibleOptions() for allowed field values (anyOf / oneOf)

I managed to get this working, but I'd like to get some more eyes on it to see if it makes sense. I opened an MR, and also attached a patch.

This required one additional change outside of DataDefinitionNormalizer. Here is why...

Within the context of DataDefinitionNormalizer::normalize(), when it is normalizing a field that implements OptionsProviderInterface, we have access to the following method arguments:

• $entity - An object of type \Drupal\Core\TypedData\DataDefinition, which represents the low-level data value of the field. (This is not an "entity" in the Drupal sense, despite its name.)
• $format - This is always schema_json to indicate that this is being normalized into JSON Schema.
• $context - An array with two keyed item: name (the data name, usually "value" in this context) and parent (the FieldItemDataDefinition representing the field itself).

With these as our available input, we can get the field storage definition from $context['parent'], and then call getOptionsProvider(), which gives us the instantiated field item class object itself (eg: ListStringItem), which we can then call getPossibleOptions() on.

The catch is: getOptionsProvider() requires a Drupal entity be passed into it. This makes sense, because in theory the allowed values may depend on the specific entity in question. However, in this context, we are building a general JSON Schema for all entities of a certain bundle. We don't have a specific entity.

So, my patch creates a mock entity. I can't see any way around this, but would love to know if there's a better way!

Now... even creating a mock entity is a little bit tricky because in the relevant context we're working in (DataDefinitionNormalizer::normalize()), we can't actually figure out what bundle we're dealing with! I tried getting that information from the field definition, with $context['parent']->getFieldDefinition()->getTargetBundle() but this always seems to return NULL, so it was a non-starter.

This brings me to the "one additional change outside of DataDefinitionNormalizer" I mentioned above...

In JsonApiSchemaController::addFieldsSchema(), currently the only thing being added to $context is $context['name'] (further down the chain, in ComplexDataDefinitionNormalizer, $context['parent'] gets added too). Another argument that is available to us in JsonApiSchemaController::addFieldsSchema() is \Drupal\jsonapi\ResourceType\ResourceType $resource_type. If we add that to $context['resource_type'] it becomes available downstream in DataDefinitionNormalizer::normalize(), and we can do $resource_type->getEntityTypeId() and $resource_type->getBundle() to get the entity type ID and bundle.

With these two pieces of information, we can create a mock entity of the correct bundle, pass that into getOptionsProvider(), and then call getPossibleOptions().

After that, we use the existing code to plug those allowed values into anyOf / oneOf enumerations in the normalized JSON schema. Voila! :-D

Curious what others think! Or if there is a better way to do any of this. Setting to "Needs review"...

Also worth noting, I came across this recent issue from @joachim, which feels very related: #3332360: Add possible values for data types →

The MR in that issue *also* uses getPossibleValues(), but it seems to be for a different case than this one. It does not handle fields with allowed_values, etc. Nor does it conflict with this MR. I found that with both, it added even more enumerations that are currently missing, so we may actually want to merge both of them. I also wonder if there's a way we could combine their logic together, so they handle all cases, but that was a bit beyond my current means, so I didn't dig into it. Curious if @joachim has any thoughts on this one! I will comment on the other issue to bring attention to this one.

It is also used in core's BooleanItem

A user of this patch reported a bug today... tl;dr: we should omit BooleanItem fields from this logic.

On BooleanItem fields, the oneOf values that are included in the schema are 1 and 0. This makes sense because that's what Drupal / PHP expects for boolean values, but JSON expects true and false.

json-schema.org explicitly states:

Note that values that evaluate to true or false, such as 1 and 0, are not accepted by the schema.

https://json-schema.org/understanding-json-schema/reference/boolean

This means that it's not possible to validate boolean fields with this patch, because it only allows values (1 and 0) that are unacceptable.

I think the easiest solution to this is to simply omit BooleanItem fields from being included in this logic, so that we do not add the oneOf property to them.

I've added a commit to the MR to this effect, and attached an updated patch.

Rebased this on top of latest 8.x-1.x, which now includes automated tests (via #3257911). Let's see if this breaks anything in the current tests, and then add new tests for this functionality specifically.

I've added tests for this. In doing so, I found that this patch was only working for base fields, not for config fields. It was a simple tweak to support both: instead of checking if the field storage definition is an instanceof ListDataDefinitionInterface, now it checks if the field definition is. Tests are included for both base and config field types now.

I think the easiest solution to this is to simply omit BooleanItem fields from being included in this logic, so that we do not add the oneOf property to them.

I also split the allowed values logic out (and streamlined/documented it) into an allowedValues() method on the DataDefinitionNormalizer class, and then subclassed that for boolean fields to disable allowed values. This removes the need to reference BooleanItem directly in DataDefinitionNormalizer, and it will allow field types that extend boolean to inherit the same default behavior, or override it if they want to.

I think this is ready to merge. All tests are green, and all the context and reasoning is documented thoroughly above and in code comments.

I reached out to @joachim regarding #3332360: Add possible values for data types → to see if we can incorporate that too. If I don't hear back I may move forward with this regardless and we can tackle other cases later.

Automatically closed - issue fixed for 2 weeks with no activity.