{"action":"created","issue":{"url":"https://api.github.com/repos/json-api/json-api/issues/310","labels_url":"https://api.github.com/repos/json-api/json-api/issues/310/labels{/name}","comments_url":"https://api.github.com/repos/json-api/json-api/issues/310/comments","events_url":"https://api.github.com/repos/json-api/json-api/issues/310/events","html_url":"https://github.com/json-api/json-api/issues/310","id":48288008,"number":310,"title":"Schemas","user":{"login":"lgebhardt","id":29154,"avatar_url":"https://avatars.githubusercontent.com/u/29154?v=3","gravatar_id":"","url":"https://api.github.com/users/lgebhardt","html_url":"https://github.com/lgebhardt","followers_url":"https://api.github.com/users/lgebhardt/followers","following_url":"https://api.github.com/users/lgebhardt/following{/other_user}","gists_url":"https://api.github.com/users/lgebhardt/gists{/gist_id}","starred_url":"https://api.github.com/users/lgebhardt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lgebhardt/subscriptions","organizations_url":"https://api.github.com/users/lgebhardt/orgs","repos_url":"https://api.github.com/users/lgebhardt/repos","events_url":"https://api.github.com/users/lgebhardt/events{/privacy}","received_events_url":"https://api.github.com/users/lgebhardt/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/json-api/json-api/labels/enhancement","name":"enhancement","color":"84b6eb"}],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":16,"created_at":"2014-11-10T17:07:39Z","updated_at":"2015-06-29T10:41:34Z","closed_at":"2015-06-29T10:41:34Z","body":"Before we release version 1.0 I think we should discuss the idea of adding support for schemas. Currently we can define links at the top level, or in the individual resources. Links can contain hrefs or url templates to help resolve associated resources. However I think we will want to be able to define more schema information for a resource than only its links.\r\n\r\nI propose that we replace the top level links with a top level `types` key, which will contain a definition for each type returned in the response document. The type can be either a full type definition or an href to the full definition. Providing an href to the type definition allows for larger type definitions to be provided without the overhead of including them in every response (clients would be expected to cache them and not fetch them each time).\r\n\r\nFor example:\r\n\r\nBefore:\r\n```json\r\n{\r\n  \"links\": {\r\n    \"posts.comments\": \"http://example.com/comments?posts={posts.id}\"\r\n  },\r\n  \"posts\": [{\r\n    \"id\": \"1\",\r\n    \"title\": \"Rails is Omakase\"\r\n  }, {\r\n    \"id\": \"2\",\r\n    \"title\": \"The Parley Letter\"\r\n  }]\r\n}\r\n```\r\n\r\nAfter:\r\n```json\r\n{\r\n  \"types\": {\r\n    \"posts\": {\r\n      \"links\": {\r\n        \"comments\": \"http://example.com/comments?posts={posts.id}\"\r\n      }\r\n    }\r\n  },\r\n  \"posts\": [{\r\n    \"id\": \"1\",\r\n    \"title\": \"Rails is Omakase\"\r\n  }, \r\n  {\r\n    \"id\": \"2\",\r\n    \"title\": \"The Parley Letter\"\r\n  }]\r\n}\r\n```\r\n\r\nor \r\n\r\n```json\r\n{\r\n  \"types\": {\r\n    \"posts\": \"http://example.com/types/posts\"\r\n  },\r\n  \"posts\": [{\r\n    \"id\": \"1\",\r\n    \"title\": \"Rails is Omakase\"\r\n  }, \r\n  {\r\n    \"id\": \"2\",\r\n    \"title\": \"The Parley Letter\"\r\n  }]\r\n}\r\n```\r\n\r\nBy refactoring into types we leave ourselves the ability to add additional information about the capabilities of a resource. These might include the filters it supports, the methods available to the current user (would require resource specific types - see below), the attributes it provides (maybe with more detail), etc.\r\n\r\nEach resource should also be able to provide a type definition the overrides parts of the top level type definition. These hashes would be merged with the resource taking precedence. This would preserve the idea of resource level links.\r\n\r\nFor version 1.0 we would not need to define the additional capabilities of the type. This would obviously be a breaking change, but it gives us a lot more flexibility down the road."},"comment":{"url":"https://api.github.com/repos/json-api/json-api/issues/comments/116599263","html_url":"https://github.com/json-api/json-api/issues/310#issuecomment-116599263","issue_url":"https://api.github.com/repos/json-api/json-api/issues/310","id":116599263,"user":{"login":"tkellen","id":1004324,"avatar_url":"https://avatars.githubusercontent.com/u/1004324?v=3","gravatar_id":"","url":"https://api.github.com/users/tkellen","html_url":"https://github.com/tkellen","followers_url":"https://api.github.com/users/tkellen/followers","following_url":"https://api.github.com/users/tkellen/following{/other_user}","gists_url":"https://api.github.com/users/tkellen/gists{/gist_id}","starred_url":"https://api.github.com/users/tkellen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tkellen/subscriptions","organizations_url":"https://api.github.com/users/tkellen/orgs","repos_url":"https://api.github.com/users/tkellen/repos","events_url":"https://api.github.com/users/tkellen/events{/privacy}","received_events_url":"https://api.github.com/users/tkellen/received_events","type":"User","site_admin":false},"created_at":"2015-06-29T10:41:34Z","updated_at":"2015-06-29T10:41:34Z","body":"This could definitely be considered for an extension in a post 1.1 world (when we have proper support for extensions). Our current roadmap can be found here: http://discuss.jsonapi.org/t/json-api-weekly-meeting-june-22nd-2015/23\r\n\r\nI am giving this a close now, but I've made a note in a master issue (#794) to re-visit this when we're ready."}}