@christophersansone thank you for working on this.

I have only one concern here, please help me understand why do we need to support 3 types of syntaxes for include? I think this is confusing and unnecessary, considering the fact that spec suggests it's always a comma-separated list of values. I'd like us to keep things the way they are and as simple as possible (not to mention that the hash syntax for a single include member is weird include: {rel: {}}).

Code-wise, may I suggest two things please:

• to provide docstrings for all the new methods, modules and classes, consider using the YARD format
• to consider using the https://github.com/jsonapi-rb/jsonapi-rspec in the tests (expect(document['data']).to have_type('users') is way cleaner than what we have now)

@stas Thanks for the quick feedback.

...considering the fact that spec suggests it's always a comma-separated list of values...

Sorry, where is this? I added a whole new file of specs to define the behavior, and I did not see anything in the Readme. I'd be happy to adjust wherever that is.

... hash syntax for a single include member is weird include: {rel: {}} ...

I don't think people will do it that way. Just opt for a different syntax, most simply include: :rel or include: [:rel]. If you have other relationships that are nested, do something like include: [:rel, { foo: :bar }].

... why do we need to support 3 types of syntaxes for include?

The existing format is really not very Rubyesque. I don't know of any other library that uses dot notation strings to define nesting. It is also extremely cumbersome and error prone when you are including several relationships several levels deep.

Two examples of heavily used Ruby methods that use similar syntax to what I'm proposing is ActiveModel joins and includes, and also ActionController's strong parameters. The syntax will be familiar to all who use these. In fact, I would think that in most cases where people are using ActiveModel and FastJSONAPI, their ActiveModel includes will look much like their FastJSONAPI include. These methods have similar flexibility as well: define strings, symbols, arrays, and / or hashes. But not dot notation. 😄 ActiveModel Serializers also uses a similar format for defining include as well.

Of course, we need to keep the dot notation syntax around for backward compatibility, so like it or not, it's not going anywhere. I much prefer the new syntax and think it's more intuitive for the Ruby community.

Sorry, where is this? I added a whole new file of specs to define the behavior, and I did not see anything in the Readme. I'd be happy to adjust wherever that is.

@christophersansone I'm looking at this https://jsonapi.org/format/#fetching-includes

Sorry, I'm just trying to keep things as close as possible to what the spec suggests.

@stas Ahh, okay. Well, it also says it needs to be a comma-separated, dot notated list, all in one string, e.g. foo,bar,bar.baz. AFAIK this library never supported comma separation: it expects an array of dot-notated strings. We can do that if needed though!

I think the main difference here is that the json:api spec is (rightfully) language agnostic. But this library lives in Ruby and is used by Ruby developers. Sometimes, for some projects, the list of includes will come from the include parameter passed from the client. Other times, it will be the Ruby developer deciding what gets included, so let's give them a syntax that is familiar to them.

@christophersansone let's just keep the API interface we already have in place. I can't imagine folks parsing a query string of comma-separated dot-notation value into a hash, so we're definitely not going in the right direction by supporting that. The most common use-case here is that one sends a query param like in the spec examples, at most that is split into a list of values and fed to fast_jsonapi. So maintaining what we have for now, should be more than enough.

Thanks!