{"action":"created","comment":{"url":"https://api.github.com/repos/gawkermedia/json-filter/pulls/comments/38740689","id":38740689,"diff_hunk":"@@ -1,2 +1,124 @@\n # json-filter\n-Scala library that implements dynamic json filtering (partial response), built on top of Play json transformers\n+Scala library that implements dynamic json filtering (partial response), built on top of Play framework's json transformers\n+\n+# How to use it?\n+\n+By using json filter, you can get your json filtered by applying include and exclude expressions. \n+It is allowed to filter within arrays as well.\n+\n+On the server side: mix in `RequestTransformers`, then you can filter the json even \n+- by passing a play Request implicitly\n+```scala\n+implicit request =>\n+val filteredJson = filter(json)\n+```\n+- by passing the include and exclude expressions explicitly:\n+```scala\n+val filteredJson = filter(json, Some(\"key5\"), Some(\"key5(key51)\")\n+```\n+\n+\n+On the client side: use include and exclude query parameters that will be applied to the json result \n+\n+\n+This resembles a lot Google's [partial response](https://developers.google.com/blogger/docs/3.0/performance#partial-response) syntax with three additions:\n+  1. use parentheses consistently (even if you'd like to select only one child element)\n+  2. you can't just tell what fields to include in the json, but also what to exclude. \n+  So we have two query parameters - include and exclude - which can be combined\n+  3. no wildcards\n+  \n+Rules on the result:\n+- you can a use syntax like include=items(reply(display,excerpt),approvedCount) even if any of these fields is an array\n+- you can combine include and exclude parameters\n+- if the syntax is not valid or the fields do not conform with the actual json object, \n+we fall back to the original complete json (this also means that if you require a.b but a is null, fallback mechanism kicks in)\n+- the tool doesn't change the structure, only skips certain fields/branches of the object tree\n+\n+# Examples\n+\n+If the original json is:\n+```javascript\n+{\n+  \"key1\" : \"alpha\",\n+  \"key2\" : {\n+    \"key21\" : \"beta\",\n+    \"key22\" : {\n+                \"key221\" : \"omega\"\n+    },\n+    \"key23\" : 15\n+  },\n+  \"key3\" : [\"gamma\", \"delta\"],\n+  \"key4\" : \"kappa\",\n+  \"key5\" : [\n+    {\n+      \"key51\" : 11,\n+      \"key52\" : \"13\"\n+    },\n+    {\n+      \"key51\" : null,\n+      \"key52\" : true\n+    }\n+  ]\n+}\n+```\n+\n+### Example to keep json fields\n+\n+?include=key1,key2(key21),key5(key52) results in:\n+\n+```javascript\n+{\n+  \"key1\" : \"alpha\",\n+  \"key2\" : {\n+    \"key21\" : \"beta\",\n+  },\n+  \"key5\" : [\n+    {\n+      \"key52\" : \"13\"\n+    },\n+    {\n+      \"key52\" : true\n+    }\n+  ]\n+}\n+```\n+\n+### Example to exclude json fields\n+\n+?exclude=key1,key2(key21),key5(key52) results in:\n+\n+```javascript\n+{\n+  \"key2\" : {\n+    \"key22\" : {\n+                \"key221\" : \"omega\"\n+    },\n+    \"key23\" : 15\n+  },\n+  \"key3\" : [\"gamma\", \"delta\"],\n+  \"key4\" : \"kappa\",\n+  \"key5\" : [\n+    {\n+      \"key51\" : 11\n+    },\n+    {\n+      \"key51\" : null\n+    }\n+  ]\n+}\n+```\n+\n+### Example to combine include and exclude\n+?include=key2,key3,key4&exclude=key2(key22) results in:","path":"README.md","position":113,"original_position":113,"commit_id":"99cfc8eeb5bd163121a3ca6842b5bbc971b46f4c","original_commit_id":"99cfc8eeb5bd163121a3ca6842b5bbc971b46f4c","user":{"login":"tferi","id":4521356,"avatar_url":"https://avatars.githubusercontent.com/u/4521356?v=3","gravatar_id":"","url":"https://api.github.com/users/tferi","html_url":"https://github.com/tferi","followers_url":"https://api.github.com/users/tferi/followers","following_url":"https://api.github.com/users/tferi/following{/other_user}","gists_url":"https://api.github.com/users/tferi/gists{/gist_id}","starred_url":"https://api.github.com/users/tferi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tferi/subscriptions","organizations_url":"https://api.github.com/users/tferi/orgs","repos_url":"https://api.github.com/users/tferi/repos","events_url":"https://api.github.com/users/tferi/events{/privacy}","received_events_url":"https://api.github.com/users/tferi/received_events","type":"User","site_admin":false},"body":"I think you should document the precedence of inclusions and exclusions.\r\nWhat happens if you include `key2.key22` when `key2` is excluded?","created_at":"2015-09-04T10:53:41Z","updated_at":"2015-09-04T10:53:41Z","html_url":"https://github.com/gawkermedia/json-filter/pull/2#discussion_r38740689","pull_request_url":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2","_links":{"self":{"href":"https://api.github.com/repos/gawkermedia/json-filter/pulls/comments/38740689"},"html":{"href":"https://github.com/gawkermedia/json-filter/pull/2#discussion_r38740689"},"pull_request":{"href":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2"}}},"pull_request":{"url":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2","id":42810805,"html_url":"https://github.com/gawkermedia/json-filter/pull/2","diff_url":"https://github.com/gawkermedia/json-filter/pull/2.diff","patch_url":"https://github.com/gawkermedia/json-filter/pull/2.patch","issue_url":"https://api.github.com/repos/gawkermedia/json-filter/issues/2","number":2,"state":"open","locked":false,"title":"Add readme with examples","user":{"login":"leventem","id":10024983,"avatar_url":"https://avatars.githubusercontent.com/u/10024983?v=3","gravatar_id":"","url":"https://api.github.com/users/leventem","html_url":"https://github.com/leventem","followers_url":"https://api.github.com/users/leventem/followers","following_url":"https://api.github.com/users/leventem/following{/other_user}","gists_url":"https://api.github.com/users/leventem/gists{/gist_id}","starred_url":"https://api.github.com/users/leventem/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/leventem/subscriptions","organizations_url":"https://api.github.com/users/leventem/orgs","repos_url":"https://api.github.com/users/leventem/repos","events_url":"https://api.github.com/users/leventem/events{/privacy}","received_events_url":"https://api.github.com/users/leventem/received_events","type":"User","site_admin":false},"body":"### What does this PR do? How does it affect users?\r\n^^^\r\n\r\n@stratiator could you please take a look?\r\n","created_at":"2015-08-19T12:57:23Z","updated_at":"2015-09-04T10:53:41Z","closed_at":null,"merged_at":null,"merge_commit_sha":"bdbd34df32125a3bf9088a2554200af43fb892d4","assignee":{"login":"stratiator","id":2676848,"avatar_url":"https://avatars.githubusercontent.com/u/2676848?v=3","gravatar_id":"","url":"https://api.github.com/users/stratiator","html_url":"https://github.com/stratiator","followers_url":"https://api.github.com/users/stratiator/followers","following_url":"https://api.github.com/users/stratiator/following{/other_user}","gists_url":"https://api.github.com/users/stratiator/gists{/gist_id}","starred_url":"https://api.github.com/users/stratiator/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/stratiator/subscriptions","organizations_url":"https://api.github.com/users/stratiator/orgs","repos_url":"https://api.github.com/users/stratiator/repos","events_url":"https://api.github.com/users/stratiator/events{/privacy}","received_events_url":"https://api.github.com/users/stratiator/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2/commits","review_comments_url":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2/comments","review_comment_url":"https://api.github.com/repos/gawkermedia/json-filter/pulls/comments{/number}","comments_url":"https://api.github.com/repos/gawkermedia/json-filter/issues/2/comments","statuses_url":"https://api.github.com/repos/gawkermedia/json-filter/statuses/99cfc8eeb5bd163121a3ca6842b5bbc971b46f4c","head":{"label":"gawkermedia:readme","ref":"readme","sha":"99cfc8eeb5bd163121a3ca6842b5bbc971b46f4c","user":{"login":"gawkermedia","id":852924,"avatar_url":"https://avatars.githubusercontent.com/u/852924?v=3","gravatar_id":"","url":"https://api.github.com/users/gawkermedia","html_url":"https://github.com/gawkermedia","followers_url":"https://api.github.com/users/gawkermedia/followers","following_url":"https://api.github.com/users/gawkermedia/following{/other_user}","gists_url":"https://api.github.com/users/gawkermedia/gists{/gist_id}","starred_url":"https://api.github.com/users/gawkermedia/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gawkermedia/subscriptions","organizations_url":"https://api.github.com/users/gawkermedia/orgs","repos_url":"https://api.github.com/users/gawkermedia/repos","events_url":"https://api.github.com/users/gawkermedia/events{/privacy}","received_events_url":"https://api.github.com/users/gawkermedia/received_events","type":"Organization","site_admin":false},"repo":{"id":40970793,"name":"json-filter","full_name":"gawkermedia/json-filter","owner":{"login":"gawkermedia","id":852924,"avatar_url":"https://avatars.githubusercontent.com/u/852924?v=3","gravatar_id":"","url":"https://api.github.com/users/gawkermedia","html_url":"https://github.com/gawkermedia","followers_url":"https://api.github.com/users/gawkermedia/followers","following_url":"https://api.github.com/users/gawkermedia/following{/other_user}","gists_url":"https://api.github.com/users/gawkermedia/gists{/gist_id}","starred_url":"https://api.github.com/users/gawkermedia/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gawkermedia/subscriptions","organizations_url":"https://api.github.com/users/gawkermedia/orgs","repos_url":"https://api.github.com/users/gawkermedia/repos","events_url":"https://api.github.com/users/gawkermedia/events{/privacy}","received_events_url":"https://api.github.com/users/gawkermedia/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gawkermedia/json-filter","description":"Scala library that implements dynamic json filtering (partial response), built on top of Play json transformers","fork":false,"url":"https://api.github.com/repos/gawkermedia/json-filter","forks_url":"https://api.github.com/repos/gawkermedia/json-filter/forks","keys_url":"https://api.github.com/repos/gawkermedia/json-filter/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gawkermedia/json-filter/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gawkermedia/json-filter/teams","hooks_url":"https://api.github.com/repos/gawkermedia/json-filter/hooks","issue_events_url":"https://api.github.com/repos/gawkermedia/json-filter/issues/events{/number}","events_url":"https://api.github.com/repos/gawkermedia/json-filter/events","assignees_url":"https://api.github.com/repos/gawkermedia/json-filter/assignees{/user}","branches_url":"https://api.github.com/repos/gawkermedia/json-filter/branches{/branch}","tags_url":"https://api.github.com/repos/gawkermedia/json-filter/tags","blobs_url":"https://api.github.com/repos/gawkermedia/json-filter/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gawkermedia/json-filter/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gawkermedia/json-filter/git/refs{/sha}","trees_url":"https://api.github.com/repos/gawkermedia/json-filter/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gawkermedia/json-filter/statuses/{sha}","languages_url":"https://api.github.com/repos/gawkermedia/json-filter/languages","stargazers_url":"https://api.github.com/repos/gawkermedia/json-filter/stargazers","contributors_url":"https://api.github.com/repos/gawkermedia/json-filter/contributors","subscribers_url":"https://api.github.com/repos/gawkermedia/json-filter/subscribers","subscription_url":"https://api.github.com/repos/gawkermedia/json-filter/subscription","commits_url":"https://api.github.com/repos/gawkermedia/json-filter/commits{/sha}","git_commits_url":"https://api.github.com/repos/gawkermedia/json-filter/git/commits{/sha}","comments_url":"https://api.github.com/repos/gawkermedia/json-filter/comments{/number}","issue_comment_url":"https://api.github.com/repos/gawkermedia/json-filter/issues/comments{/number}","contents_url":"https://api.github.com/repos/gawkermedia/json-filter/contents/{+path}","compare_url":"https://api.github.com/repos/gawkermedia/json-filter/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gawkermedia/json-filter/merges","archive_url":"https://api.github.com/repos/gawkermedia/json-filter/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gawkermedia/json-filter/downloads","issues_url":"https://api.github.com/repos/gawkermedia/json-filter/issues{/number}","pulls_url":"https://api.github.com/repos/gawkermedia/json-filter/pulls{/number}","milestones_url":"https://api.github.com/repos/gawkermedia/json-filter/milestones{/number}","notifications_url":"https://api.github.com/repos/gawkermedia/json-filter/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gawkermedia/json-filter/labels{/name}","releases_url":"https://api.github.com/repos/gawkermedia/json-filter/releases{/id}","created_at":"2015-08-18T12:32:20Z","updated_at":"2015-09-04T10:14:42Z","pushed_at":"2015-09-04T10:14:43Z","git_url":"git://github.com/gawkermedia/json-filter.git","ssh_url":"git@github.com:gawkermedia/json-filter.git","clone_url":"https://github.com/gawkermedia/json-filter.git","svn_url":"https://github.com/gawkermedia/json-filter","homepage":null,"size":192,"stargazers_count":0,"watchers_count":0,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"base":{"label":"gawkermedia:master","ref":"master","sha":"0596526ae278dbb155761d2faf246c658e248db7","user":{"login":"gawkermedia","id":852924,"avatar_url":"https://avatars.githubusercontent.com/u/852924?v=3","gravatar_id":"","url":"https://api.github.com/users/gawkermedia","html_url":"https://github.com/gawkermedia","followers_url":"https://api.github.com/users/gawkermedia/followers","following_url":"https://api.github.com/users/gawkermedia/following{/other_user}","gists_url":"https://api.github.com/users/gawkermedia/gists{/gist_id}","starred_url":"https://api.github.com/users/gawkermedia/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gawkermedia/subscriptions","organizations_url":"https://api.github.com/users/gawkermedia/orgs","repos_url":"https://api.github.com/users/gawkermedia/repos","events_url":"https://api.github.com/users/gawkermedia/events{/privacy}","received_events_url":"https://api.github.com/users/gawkermedia/received_events","type":"Organization","site_admin":false},"repo":{"id":40970793,"name":"json-filter","full_name":"gawkermedia/json-filter","owner":{"login":"gawkermedia","id":852924,"avatar_url":"https://avatars.githubusercontent.com/u/852924?v=3","gravatar_id":"","url":"https://api.github.com/users/gawkermedia","html_url":"https://github.com/gawkermedia","followers_url":"https://api.github.com/users/gawkermedia/followers","following_url":"https://api.github.com/users/gawkermedia/following{/other_user}","gists_url":"https://api.github.com/users/gawkermedia/gists{/gist_id}","starred_url":"https://api.github.com/users/gawkermedia/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gawkermedia/subscriptions","organizations_url":"https://api.github.com/users/gawkermedia/orgs","repos_url":"https://api.github.com/users/gawkermedia/repos","events_url":"https://api.github.com/users/gawkermedia/events{/privacy}","received_events_url":"https://api.github.com/users/gawkermedia/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gawkermedia/json-filter","description":"Scala library that implements dynamic json filtering (partial response), built on top of Play json transformers","fork":false,"url":"https://api.github.com/repos/gawkermedia/json-filter","forks_url":"https://api.github.com/repos/gawkermedia/json-filter/forks","keys_url":"https://api.github.com/repos/gawkermedia/json-filter/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gawkermedia/json-filter/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gawkermedia/json-filter/teams","hooks_url":"https://api.github.com/repos/gawkermedia/json-filter/hooks","issue_events_url":"https://api.github.com/repos/gawkermedia/json-filter/issues/events{/number}","events_url":"https://api.github.com/repos/gawkermedia/json-filter/events","assignees_url":"https://api.github.com/repos/gawkermedia/json-filter/assignees{/user}","branches_url":"https://api.github.com/repos/gawkermedia/json-filter/branches{/branch}","tags_url":"https://api.github.com/repos/gawkermedia/json-filter/tags","blobs_url":"https://api.github.com/repos/gawkermedia/json-filter/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gawkermedia/json-filter/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gawkermedia/json-filter/git/refs{/sha}","trees_url":"https://api.github.com/repos/gawkermedia/json-filter/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gawkermedia/json-filter/statuses/{sha}","languages_url":"https://api.github.com/repos/gawkermedia/json-filter/languages","stargazers_url":"https://api.github.com/repos/gawkermedia/json-filter/stargazers","contributors_url":"https://api.github.com/repos/gawkermedia/json-filter/contributors","subscribers_url":"https://api.github.com/repos/gawkermedia/json-filter/subscribers","subscription_url":"https://api.github.com/repos/gawkermedia/json-filter/subscription","commits_url":"https://api.github.com/repos/gawkermedia/json-filter/commits{/sha}","git_commits_url":"https://api.github.com/repos/gawkermedia/json-filter/git/commits{/sha}","comments_url":"https://api.github.com/repos/gawkermedia/json-filter/comments{/number}","issue_comment_url":"https://api.github.com/repos/gawkermedia/json-filter/issues/comments{/number}","contents_url":"https://api.github.com/repos/gawkermedia/json-filter/contents/{+path}","compare_url":"https://api.github.com/repos/gawkermedia/json-filter/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gawkermedia/json-filter/merges","archive_url":"https://api.github.com/repos/gawkermedia/json-filter/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gawkermedia/json-filter/downloads","issues_url":"https://api.github.com/repos/gawkermedia/json-filter/issues{/number}","pulls_url":"https://api.github.com/repos/gawkermedia/json-filter/pulls{/number}","milestones_url":"https://api.github.com/repos/gawkermedia/json-filter/milestones{/number}","notifications_url":"https://api.github.com/repos/gawkermedia/json-filter/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gawkermedia/json-filter/labels{/name}","releases_url":"https://api.github.com/repos/gawkermedia/json-filter/releases{/id}","created_at":"2015-08-18T12:32:20Z","updated_at":"2015-09-04T10:14:42Z","pushed_at":"2015-09-04T10:14:43Z","git_url":"git://github.com/gawkermedia/json-filter.git","ssh_url":"git@github.com:gawkermedia/json-filter.git","clone_url":"https://github.com/gawkermedia/json-filter.git","svn_url":"https://github.com/gawkermedia/json-filter","homepage":null,"size":192,"stargazers_count":0,"watchers_count":0,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2"},"html":{"href":"https://github.com/gawkermedia/json-filter/pull/2"},"issue":{"href":"https://api.github.com/repos/gawkermedia/json-filter/issues/2"},"comments":{"href":"https://api.github.com/repos/gawkermedia/json-filter/issues/2/comments"},"review_comments":{"href":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2/comments"},"review_comment":{"href":"https://api.github.com/repos/gawkermedia/json-filter/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/gawkermedia/json-filter/pulls/2/commits"},"statuses":{"href":"https://api.github.com/repos/gawkermedia/json-filter/statuses/99cfc8eeb5bd163121a3ca6842b5bbc971b46f4c"}}}}