{"action":"created","issue":{"url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/30","labels_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/30/labels{/name}","comments_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/30/comments","events_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/30/events","html_url":"https://github.com/restful-api-description-language/RADL/issues/30","id":99434298,"number":30,"title":"Remove duplicate documentation for URI template variables","user":{"login":"ApiSecRay","id":3496035,"avatar_url":"https://avatars.githubusercontent.com/u/3496035?v=3","gravatar_id":"","url":"https://api.github.com/users/ApiSecRay","html_url":"https://github.com/ApiSecRay","followers_url":"https://api.github.com/users/ApiSecRay/followers","following_url":"https://api.github.com/users/ApiSecRay/following{/other_user}","gists_url":"https://api.github.com/users/ApiSecRay/gists{/gist_id}","starred_url":"https://api.github.com/users/ApiSecRay/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ApiSecRay/subscriptions","organizations_url":"https://api.github.com/users/ApiSecRay/orgs","repos_url":"https://api.github.com/users/ApiSecRay/repos","events_url":"https://api.github.com/users/ApiSecRay/events{/privacy}","received_events_url":"https://api.github.com/users/ApiSecRay/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-08-06T13:30:44Z","updated_at":"2015-08-13T07:28:06Z","closed_at":null,"body":"Assume the RESTBucks service. We'd have an order at `/orders/{order-id}/`, payments for the order at `/orders/{order-id}/payments/`, the receipt at `/orders/{order-id}/receipt/`, and the serving at `/orders/{order-id}/serving/`. With the current schema, you'd have to document the `order-id` URI template variable **four times**.\r\n\r\n(It seems that [Swagger](http://petstore.swagger.io/) suffers from the same problem.)\r\n\r\nI see at least the following ways to get rid of this duplication:\r\n\r\n1. Document the URI template variables once under `<service-conventions>` and turn `<var>` into a reference.\r\n1. Capture the parent-child relationships between `<resource>` elements, for instance using a `parent` attribute, or using nesting (which is what [RAML](http://raml.org/index.html) seems to be doing)."},"comment":{"url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/comments/130564360","html_url":"https://github.com/restful-api-description-language/RADL/issues/30#issuecomment-130564360","issue_url":"https://api.github.com/repos/restful-api-description-language/RADL/issues/30","id":130564360,"user":{"login":"gentlewind","id":6801512,"avatar_url":"https://avatars.githubusercontent.com/u/6801512?v=3","gravatar_id":"","url":"https://api.github.com/users/gentlewind","html_url":"https://github.com/gentlewind","followers_url":"https://api.github.com/users/gentlewind/followers","following_url":"https://api.github.com/users/gentlewind/following{/other_user}","gists_url":"https://api.github.com/users/gentlewind/gists{/gist_id}","starred_url":"https://api.github.com/users/gentlewind/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gentlewind/subscriptions","organizations_url":"https://api.github.com/users/gentlewind/orgs","repos_url":"https://api.github.com/users/gentlewind/repos","events_url":"https://api.github.com/users/gentlewind/events{/privacy}","received_events_url":"https://api.github.com/users/gentlewind/received_events","type":"User","site_admin":false},"created_at":"2015-08-13T07:28:06Z","updated_at":"2015-08-13T07:28:06Z","body":"The URI templates could be strucuted, but resources are not. So I do not think method (2) is good. Is it possible to make the <location> independent of <resource> and make it extensible?"}}