{"action":"created","issue":{"url":"https://api.github.com/repos/json-api/json-api/issues/312","labels_url":"https://api.github.com/repos/json-api/json-api/issues/312/labels{/name}","comments_url":"https://api.github.com/repos/json-api/json-api/issues/312/comments","events_url":"https://api.github.com/repos/json-api/json-api/issues/312/events","html_url":"https://github.com/json-api/json-api/issues/312","id":48351854,"number":312,"title":"Rename \"data\" to \"primary\"","user":{"login":"ethanresnick","id":471894,"avatar_url":"https://avatars.githubusercontent.com/u/471894?v=3","gravatar_id":"","url":"https://api.github.com/users/ethanresnick","html_url":"https://github.com/ethanresnick","followers_url":"https://api.github.com/users/ethanresnick/followers","following_url":"https://api.github.com/users/ethanresnick/following{/other_user}","gists_url":"https://api.github.com/users/ethanresnick/gists{/gist_id}","starred_url":"https://api.github.com/users/ethanresnick/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ethanresnick/subscriptions","organizations_url":"https://api.github.com/users/ethanresnick/orgs","repos_url":"https://api.github.com/users/ethanresnick/repos","events_url":"https://api.github.com/users/ethanresnick/events{/privacy}","received_events_url":"https://api.github.com/users/ethanresnick/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/json-api/json-api/milestones/1","labels_url":"https://api.github.com/repos/json-api/json-api/milestones/1/labels","id":597996,"number":1,"title":"1.0","description":"The first stable release of JSON API.","creator":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=3","gravatar_id":"","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"open_issues":8,"closed_issues":11,"state":"open","created_at":"2014-03-14T17:28:46Z","updated_at":"2015-02-19T02:31:37Z","due_on":"2014-03-22T07:00:00Z","closed_at":null},"comments":24,"created_at":"2014-11-11T06:18:32Z","updated_at":"2015-02-20T10:08:00Z","closed_at":null,"body":"Right now, top-level resources can be keyed under `\"data\"` when they identify their type within the resource. I think we should rename this key to `\"primary\"` as that more clearly expresses the relationship between those resources and any resources that may be in the `\"linked\"` key"},"comment":{"url":"https://api.github.com/repos/json-api/json-api/issues/comments/75215194","html_url":"https://github.com/json-api/json-api/issues/312#issuecomment-75215194","issue_url":"https://api.github.com/repos/json-api/json-api/issues/312","id":75215194,"user":{"login":"bintoro","id":7081785,"avatar_url":"https://avatars.githubusercontent.com/u/7081785?v=3","gravatar_id":"","url":"https://api.github.com/users/bintoro","html_url":"https://github.com/bintoro","followers_url":"https://api.github.com/users/bintoro/followers","following_url":"https://api.github.com/users/bintoro/following{/other_user}","gists_url":"https://api.github.com/users/bintoro/gists{/gist_id}","starred_url":"https://api.github.com/users/bintoro/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bintoro/subscriptions","organizations_url":"https://api.github.com/users/bintoro/orgs","repos_url":"https://api.github.com/users/bintoro/repos","events_url":"https://api.github.com/users/bintoro/events{/privacy}","received_events_url":"https://api.github.com/users/bintoro/received_events","type":"User","site_admin":false},"created_at":"2015-02-20T10:08:00Z","updated_at":"2015-02-20T10:08:00Z","body":"> If the top-level key were to be added, I would suggest to call it just `resultset`.\r\n\r\n`resultset` or maybe even just `result` might be workable, but it only seems appropriate for responses, not requests. JSON API needs something that can accommodate both.\r\n\r\n> I think it would be very natural to accompany link objects with the resources they are linking.\r\n\r\nThis is a good point. I didn't consider the possibility where `primary` and `related` might not contain items of the same kind.\r\n\r\nWhat it all boils down to is that, if we want a generic top-level key, then *something* must be special-cased. Right now the special case is `linked` which is defined to always hold a set a *related resource objects*, no matter what goes in `data`. This, I understand, is dissatisfying to many.\r\n\r\nAn alternative would be to special-case a top-level key like `resources` that would hold all resource objects. Everything else would go in `data` (relationships and possible future uses).\r\n\r\nAnd finally, there's still the option of dedicated keys, which I believe is a popular approach. How about `relationship` or `relation` for relationships? It's quite befitting, since that's what they are, and the singular form naturally applies to both to-one and to-many relationships.\r\n\r\n```\r\n{\r\n  \"relationship\": { \"type\": \"tags\", \"ids\": [\"2\", \"3\"] }\r\n}\r\n```\r\n`link` would be okay as well but is probably too confusing unless `linked` is turned into `related`.\r\n\r\nWith dedicated keys everything can remain on the top level and still have nice semantics: `primary / related` (or `resources / related`) and `relationship / related` both look like sensible combinations to me, presuming the old definition of *primary resources* could be reinstated.\r\n"}}