{"action":"created","issue":{"url":"https://api.github.com/repos/swagger-api/swagger-spec/issues/136","labels_url":"https://api.github.com/repos/swagger-api/swagger-spec/issues/136/labels{/name}","comments_url":"https://api.github.com/repos/swagger-api/swagger-spec/issues/136/comments","events_url":"https://api.github.com/repos/swagger-api/swagger-spec/issues/136/events","html_url":"https://github.com/swagger-api/swagger-spec/issues/136","id":44406900,"number":136,"title":"Documenting model metadata","user":{"login":"ivan-novakov","id":1208505,"avatar_url":"https://avatars.githubusercontent.com/u/1208505?v=3","gravatar_id":"","url":"https://api.github.com/users/ivan-novakov","html_url":"https://github.com/ivan-novakov","followers_url":"https://api.github.com/users/ivan-novakov/followers","following_url":"https://api.github.com/users/ivan-novakov/following{/other_user}","gists_url":"https://api.github.com/users/ivan-novakov/gists{/gist_id}","starred_url":"https://api.github.com/users/ivan-novakov/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ivan-novakov/subscriptions","organizations_url":"https://api.github.com/users/ivan-novakov/orgs","repos_url":"https://api.github.com/users/ivan-novakov/repos","events_url":"https://api.github.com/users/ivan-novakov/events{/privacy}","received_events_url":"https://api.github.com/users/ivan-novakov/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/swagger-api/swagger-spec/labels/Swagger.Next%20Proposal","name":"Swagger.Next Proposal","color":"207de5"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2014-09-30T07:57:30Z","updated_at":"2015-03-16T02:28:36Z","closed_at":null,"body":"Are there any best practices how to document model metadata such as hyperlinks, context, documentation? For example if I use HAL, the typical resource looks like this:\r\n```json\r\n{\r\n  \"_links\": {\r\n    \"self\": { \"href\": \"/employees/123456\" }\r\n  },\r\n  \"employeeId\": 123456,\r\n  \"firstName\": \"Ivan\",\r\n  \"lastName\": \"Novakov\",\r\n  \"email\": \"ivan.novakov@company.com\"\r\n}\r\n```\r\n\r\nNow such parts like the `_links` section may be defined in the model definition, but they are not actually part of the model and sometimes the structure may be more complex and (what is worse) repeating across the different models.\r\n\r\nMaybe there could be some general support for metadata in the Swagger specs, because most of the current JSON format/specifications use some kind of metadata, see:\r\nhttp://sookocheff.com/posts/2014-03-11-on-choosing-a-hypermedia-format/"},"comment":{"url":"https://api.github.com/repos/swagger-api/swagger-spec/issues/comments/81353855","html_url":"https://github.com/swagger-api/swagger-spec/issues/136#issuecomment-81353855","issue_url":"https://api.github.com/repos/swagger-api/swagger-spec/issues/136","id":81353855,"user":{"login":"oytuntez","id":656635,"avatar_url":"https://avatars.githubusercontent.com/u/656635?v=3","gravatar_id":"","url":"https://api.github.com/users/oytuntez","html_url":"https://github.com/oytuntez","followers_url":"https://api.github.com/users/oytuntez/followers","following_url":"https://api.github.com/users/oytuntez/following{/other_user}","gists_url":"https://api.github.com/users/oytuntez/gists{/gist_id}","starred_url":"https://api.github.com/users/oytuntez/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/oytuntez/subscriptions","organizations_url":"https://api.github.com/users/oytuntez/orgs","repos_url":"https://api.github.com/users/oytuntez/repos","events_url":"https://api.github.com/users/oytuntez/events{/privacy}","received_events_url":"https://api.github.com/users/oytuntez/received_events","type":"User","site_admin":false},"created_at":"2015-03-16T02:28:36Z","updated_at":"2015-03-16T02:28:36Z","body":"One thing to note about this is probably overwriting model representations. As much as I am aware of, there isn't such thing. For example, \"self\" link would be different in different models and it would be amazing to specify this while linking to the model (path templating)."}}