JsonApi::Deserialization YARD docs are misleading

[wasabigeek]

Expected behavior vs actual behavior

In the YARD docs the example suggests that using a symbol-keyed hash will work:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Lines 27 to 56 in 873cf4a

	# document = {
	# data: {
	# id: 1,
	# type: 'post',
	# attributes: {
	# title: 'Title 1',
	# date: '2015-12-20'
	# },
	# associations: {
	# author: {
	# data: {
	# type: 'user',
	# id: 2
	# }
	# },
	# second_author: {
	# data: nil
	# },
	# comments: {
	# data: [{
	# type: 'comment',
	# id: 3
	# },{
	# type: 'comment',
	# id: 4
	# }]
	# }
	# }
	# }
	# }

(Edited)

But in the code, it will actually check via string-keys:
https://github.com/rails-api/active_model_serializers/blob/v0.10.10/lib/active_model_serializers/adapter/json_api/deserialization.rb#L118

[wasifhossain]

In the YARD docs it suggests that using a symbol-keyed hash will work:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Line 22 in 873cf4a

# keys: Hash of translated keys (e.g. :author => :user).

it says about the keys option; not about the data found inside the JSON API document.

you may take a look at an example how it can be used:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Lines 67 to 69 in 873cf4a

	# parse(document, only: [:title, :date, :author],
	# keys: { date: :published_at },
	# polymorphic: [:author]) #=>

[wasifhossain]

But in the code, it will actually check via string-keys:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Line 118 in 873cf4a

primary_data = payload['data']

because payload is expected to be a valid JSON API document, either string-keys or ActionController::Parameters, as mentioned in:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Line 18 in 873cf4a

# @param [Hash|ActionController::Parameters] document

and in the latter case, its converted to a hash with string-keys, as can be seen in:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Line 86 in 873cf4a

document = document.dup.permit!.to_h if document.is_a?(ActionController::Parameters)

[wasifhossain]

to be honest, I have found one gotcha though: it should be relationships according to the JSON API spec in place of associations on L35, as found in:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Lines 27 to 56 in 873cf4a

	# document = {
	# data: {
	# id: 1,
	# type: 'post',
	# attributes: {
	# title: 'Title 1',
	# date: '2015-12-20'
	# },
	# associations: {
	# author: {
	# data: {
	# type: 'user',
	# id: 2
	# }
	# },
	# second_author: {
	# data: nil
	# },
	# comments: {
	# data: [{
	# type: 'comment',
	# id: 3
	# },{
	# type: 'comment',
	# id: 4
	# }]
	# }
	# }
	# }
	# }

may be because the spec was like that during the time when this example was written :)

[wasabigeek]

Hey @wasifhossain thanks for pointing that out to me >_< I guess I should have pointed to this example instead - this would be a symbol-keyed hash, no?

to be honest, I have found one gotcha though: it should be relationships according to the JSON API spec in place of associations on L35, as found in:

active_model_serializers/lib/active_model_serializers/adapter/json_api/deserialization.rb

Lines 27 to 56 in 873cf4a

	# document = {
	# data: {
	# id: 1,
	# type: 'post',
	# attributes: {
	# title: 'Title 1',
	# date: '2015-12-20'
	# },
	# associations: {
	# author: {
	# data: {
	# type: 'user',
	# id: 2
	# }
	# },
	# second_author: {
	# data: nil
	# },
	# comments: {
	# data: [{
	# type: 'comment',
	# id: 3
	# },{
	# type: 'comment',
	# id: 4
	# }]
	# }
	# }
	# }
	# }

may be because the spec was like that during the time when this example was written :)

[wasifhossain]

according to the spec, a valid JSON API document keys should be stringified, as shown in this typical example

https://jsonapi.org/format/#document-compound-documents

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "links": {
      "self": "http://example.com/articles/1"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

[wasabigeek]

@wasifhossain I get that - since we're documenting in Ruby though, should we not expect that users will read this as Ruby?

Happy to close this either way...

[wasifhossain]

I will push a PR with a working example for this api (#2384 (comment))

thanks for pointing it out 👍

[wasabigeek]

I'd be happy to make a PR if you don't have time, just wanted to be sure that I had the correct interpretation!

[wasifhossain]

sure thing. please go ahead with this. I will have a look later. thanks!