#API-First Initiative

Re: ##8 - thanks Wim for your very kind words.

The change record doesn't mention it, but the commit does change the JSON:API version: JsonApiSpec::SUPPORTED_SPECIFICATION_VERSION = '1.1' is now a fact. So 🌱 [Meta] JSON:API 1.1 spec compliance/support Active is partially done? Completely? See #3305324-18: [Meta] JSON:API 1.1 spec compliance/support → . It seems that meta indicates there's a lot more to be done to be 1.1-compliant, so it's a bit surprising to see that constant being changed. I think either an updated change record that clarifies it, or an additional change record would be appropriate?

I bumped the version in this MR for a few reasons. One, our testing and validation features (e.g., that validates responses when assertions are enabled) depend on a schema for JSON:API itself, which is not exactly stable but the upstream maintenance of JSON:API overall is glacially slow. The schema file we had for 1.0 was draft and not that valid and so the updated 1.1 draft is much closer to truly representing the spec's requirements.

After reviewing the linked issue I would say that we very nearly support 1.1 at a basic level, though we "should" also finish 📌 Spec Compliance: JSON API's profile/extention (Fancy Filters, Drupal sorting, Drupal pagination, relationship arity) needs to be explicitly communicated Active to convey our profile.

TL;DR, it's time to bump it because we were far ahead of 1.0 with implementing features that would later go into 1.1. We don't strictly validate, but it's much closer to the current spec than we've ever been.

This seems to statically define JSON schemas, which is not good enough: many field types have settings that impact what the correct JSON schema would be. IOW: the JSON schemas have to be dynamically defined for them to be precise. For example: min/max for integers and numbers, a limited set of valid values (enum in JSON schema), many strings have a particular format (https://json-schema.org/understanding-json-schema/reference/string#built...), and so on. Are there plans/discussions for how to support those more precise JSON schema descriptions? Perhaps this needs a follow-up?

Schemas _may_ be defined statically, but they need not be. In addition, JSON Schema generation has no caching layer (the assumption being that the caller is responsible for this, e.g. OpenAPI module, and invalidation is based on entity definitions or whatever) so the entire schema for the normalization you are introspecting is generated on-demand. It is true that included in the merged MR was a trait and attributes that help provide static schemas... but that's not a requirement. This allowed us to add a lot of default schemas for primitive types and make it easy to define them this way, but you can also return any valid schema generated any way you like. So I think a follow-up for option module to provide a ListStringItemNormalizer with its own dynamic logic would be amazing. But it requires no change to the underlying API. Perhaps we could introduce some additional traits or whatever to assist with code re-use, but yeah.