{"action":"created","comment":{"url":"https://api.github.com/repos/json-api/json-api/pulls/comments/29359543","id":29359543,"diff_hunk":"@@ -113,9 +113,14 @@ of resources, or resource relationship primarily targeted by a request.\n \n A document **MUST** contain either primary data or an array of [error objects](#errors).\n \n-Primary data **MUST** appear under a top-level key named `\"data\"`. Primary\n-data **MUST** be either a single resource object, an array of resource\n-objects, or a value representing a resource relationship.\n+Primary data **MUST** appear under a top-level key named `\"data\"`.\n+\n+Primary data **MUST** be either:\n+\n+* a single resource object or `null`, for requests that target single resources\n+* an array of resource objects or an empty array ([]), for requests that target\n+resource collections\n+* resource linkage, for requests that target a resource's relationship","path":"format/index.md","position":14,"original_position":14,"commit_id":"1c09ce4a2785f6ddc5adc097b38749fd6a8f0b0f","original_commit_id":"1c09ce4a2785f6ddc5adc097b38749fd6a8f0b0f","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},"body":"Sorry, I totally missed the `null` case. I had actually sketched the exact same list as you did here (sans the nulls) before settling on the separate paragraph I quoted. You're right that the second sentence seems kinda redundant now, but maybe it could remain for completeness. I don't really have an opinion either way.\r\n","created_at":"2015-04-29T17:33:37Z","updated_at":"2015-04-29T17:33:37Z","html_url":"https://github.com/json-api/json-api/pull/530#discussion_r29359543","pull_request_url":"https://api.github.com/repos/json-api/json-api/pulls/530","_links":{"self":{"href":"https://api.github.com/repos/json-api/json-api/pulls/comments/29359543"},"html":{"href":"https://github.com/json-api/json-api/pull/530#discussion_r29359543"},"pull_request":{"href":"https://api.github.com/repos/json-api/json-api/pulls/530"}}},"pull_request":{"url":"https://api.github.com/repos/json-api/json-api/pulls/530","id":32215003,"html_url":"https://github.com/json-api/json-api/pull/530","diff_url":"https://github.com/json-api/json-api/pull/530.diff","patch_url":"https://github.com/json-api/json-api/pull/530.patch","issue_url":"https://api.github.com/repos/json-api/json-api/issues/530","number":530,"state":"open","locked":false,"title":"Clarify null vs. 404 responses; possible shapes of primary data","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},"body":"Filters allow for the creation of endpoints that conceptually represent a  single json-api resource or `null`, in the case that no resource currently exists which satisfies the filter's conditions. In the PR, I give as an example: `/posts?filter[is-latest]=true`, which will always return one post, except when the `posts` collection is empty in which case it doesn't pick out any posts. Another example would be `/events?filter[up-next]=true`, which would return the next upcoming event, or null if all the events in the `events` collection are in the past (or if the `events` collection is empty). \r\n\r\nResponses from these filtered endpoints should be allowed to be `null` too, as that's more appropriate than responding with an empty array (since the endpoints don't conceptually represent a collection) and it's more consistent than responding with 404. (If we were to 404 these requests, we'd probably be compelled to 404 the empty to-one relationship case, which I don't think we want to do.) So this PR merely updates the spec to note this edge case as a circumstance that allows `null` primary data.","created_at":"2015-03-30T10:41:28Z","updated_at":"2015-04-29T17:33:37Z","closed_at":null,"merged_at":null,"merge_commit_sha":"9bfd3cafee48eaf51811834262130a4aadb946d9","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/json-api/json-api/pulls/530/commits","review_comments_url":"https://api.github.com/repos/json-api/json-api/pulls/530/comments","review_comment_url":"https://api.github.com/repos/json-api/json-api/pulls/comments{/number}","comments_url":"https://api.github.com/repos/json-api/json-api/issues/530/comments","statuses_url":"https://api.github.com/repos/json-api/json-api/statuses/1c09ce4a2785f6ddc5adc097b38749fd6a8f0b0f","head":{"label":"ethanresnick:single-item-filters","ref":"single-item-filters","sha":"1c09ce4a2785f6ddc5adc097b38749fd6a8f0b0f","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},"repo":{"id":31444900,"name":"json-api-1","full_name":"ethanresnick/json-api-1","owner":{"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},"private":false,"html_url":"https://github.com/ethanresnick/json-api-1","description":"A shared media type for JSON APIs.","fork":true,"url":"https://api.github.com/repos/ethanresnick/json-api-1","forks_url":"https://api.github.com/repos/ethanresnick/json-api-1/forks","keys_url":"https://api.github.com/repos/ethanresnick/json-api-1/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ethanresnick/json-api-1/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ethanresnick/json-api-1/teams","hooks_url":"https://api.github.com/repos/ethanresnick/json-api-1/hooks","issue_events_url":"https://api.github.com/repos/ethanresnick/json-api-1/issues/events{/number}","events_url":"https://api.github.com/repos/ethanresnick/json-api-1/events","assignees_url":"https://api.github.com/repos/ethanresnick/json-api-1/assignees{/user}","branches_url":"https://api.github.com/repos/ethanresnick/json-api-1/branches{/branch}","tags_url":"https://api.github.com/repos/ethanresnick/json-api-1/tags","blobs_url":"https://api.github.com/repos/ethanresnick/json-api-1/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ethanresnick/json-api-1/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ethanresnick/json-api-1/git/refs{/sha}","trees_url":"https://api.github.com/repos/ethanresnick/json-api-1/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ethanresnick/json-api-1/statuses/{sha}","languages_url":"https://api.github.com/repos/ethanresnick/json-api-1/languages","stargazers_url":"https://api.github.com/repos/ethanresnick/json-api-1/stargazers","contributors_url":"https://api.github.com/repos/ethanresnick/json-api-1/contributors","subscribers_url":"https://api.github.com/repos/ethanresnick/json-api-1/subscribers","subscription_url":"https://api.github.com/repos/ethanresnick/json-api-1/subscription","commits_url":"https://api.github.com/repos/ethanresnick/json-api-1/commits{/sha}","git_commits_url":"https://api.github.com/repos/ethanresnick/json-api-1/git/commits{/sha}","comments_url":"https://api.github.com/repos/ethanresnick/json-api-1/comments{/number}","issue_comment_url":"https://api.github.com/repos/ethanresnick/json-api-1/issues/comments{/number}","contents_url":"https://api.github.com/repos/ethanresnick/json-api-1/contents/{+path}","compare_url":"https://api.github.com/repos/ethanresnick/json-api-1/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ethanresnick/json-api-1/merges","archive_url":"https://api.github.com/repos/ethanresnick/json-api-1/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ethanresnick/json-api-1/downloads","issues_url":"https://api.github.com/repos/ethanresnick/json-api-1/issues{/number}","pulls_url":"https://api.github.com/repos/ethanresnick/json-api-1/pulls{/number}","milestones_url":"https://api.github.com/repos/ethanresnick/json-api-1/milestones{/number}","notifications_url":"https://api.github.com/repos/ethanresnick/json-api-1/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ethanresnick/json-api-1/labels{/name}","releases_url":"https://api.github.com/repos/ethanresnick/json-api-1/releases{/id}","created_at":"2015-02-28T00:11:39Z","updated_at":"2015-04-28T06:45:44Z","pushed_at":"2015-04-28T06:55:25Z","git_url":"git://github.com/ethanresnick/json-api-1.git","ssh_url":"git@github.com:ethanresnick/json-api-1.git","clone_url":"https://github.com/ethanresnick/json-api-1.git","svn_url":"https://github.com/ethanresnick/json-api-1","homepage":"http://jsonapi.org","size":955,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"gh-pages"}},"base":{"label":"json-api:gh-pages","ref":"gh-pages","sha":"ada477d415dbb1e226d9ce779328fa39b3e85ac7","user":{"login":"json-api","id":4341694,"avatar_url":"https://avatars.githubusercontent.com/u/4341694?v=3","gravatar_id":"","url":"https://api.github.com/users/json-api","html_url":"https://github.com/json-api","followers_url":"https://api.github.com/users/json-api/followers","following_url":"https://api.github.com/users/json-api/following{/other_user}","gists_url":"https://api.github.com/users/json-api/gists{/gist_id}","starred_url":"https://api.github.com/users/json-api/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/json-api/subscriptions","organizations_url":"https://api.github.com/users/json-api/orgs","repos_url":"https://api.github.com/users/json-api/repos","events_url":"https://api.github.com/users/json-api/events{/privacy}","received_events_url":"https://api.github.com/users/json-api/received_events","type":"Organization","site_admin":false},"repo":{"id":9859154,"name":"json-api","full_name":"json-api/json-api","owner":{"login":"json-api","id":4341694,"avatar_url":"https://avatars.githubusercontent.com/u/4341694?v=3","gravatar_id":"","url":"https://api.github.com/users/json-api","html_url":"https://github.com/json-api","followers_url":"https://api.github.com/users/json-api/followers","following_url":"https://api.github.com/users/json-api/following{/other_user}","gists_url":"https://api.github.com/users/json-api/gists{/gist_id}","starred_url":"https://api.github.com/users/json-api/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/json-api/subscriptions","organizations_url":"https://api.github.com/users/json-api/orgs","repos_url":"https://api.github.com/users/json-api/repos","events_url":"https://api.github.com/users/json-api/events{/privacy}","received_events_url":"https://api.github.com/users/json-api/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/json-api/json-api","description":"A shared media type for JSON APIs.","fork":false,"url":"https://api.github.com/repos/json-api/json-api","forks_url":"https://api.github.com/repos/json-api/json-api/forks","keys_url":"https://api.github.com/repos/json-api/json-api/keys{/key_id}","collaborators_url":"https://api.github.com/repos/json-api/json-api/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/json-api/json-api/teams","hooks_url":"https://api.github.com/repos/json-api/json-api/hooks","issue_events_url":"https://api.github.com/repos/json-api/json-api/issues/events{/number}","events_url":"https://api.github.com/repos/json-api/json-api/events","assignees_url":"https://api.github.com/repos/json-api/json-api/assignees{/user}","branches_url":"https://api.github.com/repos/json-api/json-api/branches{/branch}","tags_url":"https://api.github.com/repos/json-api/json-api/tags","blobs_url":"https://api.github.com/repos/json-api/json-api/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/json-api/json-api/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/json-api/json-api/git/refs{/sha}","trees_url":"https://api.github.com/repos/json-api/json-api/git/trees{/sha}","statuses_url":"https://api.github.com/repos/json-api/json-api/statuses/{sha}","languages_url":"https://api.github.com/repos/json-api/json-api/languages","stargazers_url":"https://api.github.com/repos/json-api/json-api/stargazers","contributors_url":"https://api.github.com/repos/json-api/json-api/contributors","subscribers_url":"https://api.github.com/repos/json-api/json-api/subscribers","subscription_url":"https://api.github.com/repos/json-api/json-api/subscription","commits_url":"https://api.github.com/repos/json-api/json-api/commits{/sha}","git_commits_url":"https://api.github.com/repos/json-api/json-api/git/commits{/sha}","comments_url":"https://api.github.com/repos/json-api/json-api/comments{/number}","issue_comment_url":"https://api.github.com/repos/json-api/json-api/issues/comments{/number}","contents_url":"https://api.github.com/repos/json-api/json-api/contents/{+path}","compare_url":"https://api.github.com/repos/json-api/json-api/compare/{base}...{head}","merges_url":"https://api.github.com/repos/json-api/json-api/merges","archive_url":"https://api.github.com/repos/json-api/json-api/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/json-api/json-api/downloads","issues_url":"https://api.github.com/repos/json-api/json-api/issues{/number}","pulls_url":"https://api.github.com/repos/json-api/json-api/pulls{/number}","milestones_url":"https://api.github.com/repos/json-api/json-api/milestones{/number}","notifications_url":"https://api.github.com/repos/json-api/json-api/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/json-api/json-api/labels{/name}","releases_url":"https://api.github.com/repos/json-api/json-api/releases{/id}","created_at":"2013-05-04T19:29:30Z","updated_at":"2015-04-29T16:48:19Z","pushed_at":"2015-04-29T14:42:38Z","git_url":"git://github.com/json-api/json-api.git","ssh_url":"git@github.com:json-api/json-api.git","clone_url":"https://github.com/json-api/json-api.git","svn_url":"https://github.com/json-api/json-api","homepage":"http://jsonapi.org","size":3429,"stargazers_count":2044,"watchers_count":2044,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":247,"mirror_url":null,"open_issues_count":86,"forks":247,"open_issues":86,"watchers":2044,"default_branch":"gh-pages"}},"_links":{"self":{"href":"https://api.github.com/repos/json-api/json-api/pulls/530"},"html":{"href":"https://github.com/json-api/json-api/pull/530"},"issue":{"href":"https://api.github.com/repos/json-api/json-api/issues/530"},"comments":{"href":"https://api.github.com/repos/json-api/json-api/issues/530/comments"},"review_comments":{"href":"https://api.github.com/repos/json-api/json-api/pulls/530/comments"},"review_comment":{"href":"https://api.github.com/repos/json-api/json-api/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/json-api/json-api/pulls/530/commits"},"statuses":{"href":"https://api.github.com/repos/json-api/json-api/statuses/1c09ce4a2785f6ddc5adc097b38749fd6a8f0b0f"}}}}