{"action":"opened","issue":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/693","repository_url":"https://api.github.com/repos/OAI/OpenAPI-Specification","labels_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/693/labels{/name}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/693/comments","events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/693/events","html_url":"https://github.com/OAI/OpenAPI-Specification/issues/693","id":154543867,"number":693,"title":"Structural improvements: Enable the use of (atomic) definition for query, path and header parameters","user":{"login":"arno-di-loreto","id":10104551,"avatar_url":"https://avatars.githubusercontent.com/u/10104551?v=3","gravatar_id":"","url":"https://api.github.com/users/arno-di-loreto","html_url":"https://github.com/arno-di-loreto","followers_url":"https://api.github.com/users/arno-di-loreto/followers","following_url":"https://api.github.com/users/arno-di-loreto/following{/other_user}","gists_url":"https://api.github.com/users/arno-di-loreto/gists{/gist_id}","starred_url":"https://api.github.com/users/arno-di-loreto/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/arno-di-loreto/subscriptions","organizations_url":"https://api.github.com/users/arno-di-loreto/orgs","repos_url":"https://api.github.com/users/arno-di-loreto/repos","events_url":"https://api.github.com/users/arno-di-loreto/events{/privacy}","received_events_url":"https://api.github.com/users/arno-di-loreto/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2016-05-12T17:58:44Z","updated_at":"2016-05-12T17:58:44Z","closed_at":null,"body":"When we define a query, path or header parameter we cannot use a reference to an existing definition.\r\n\r\nIf I create a Username definition to describe a string which is a username with a certain length and a regex pattern, I can use it in any definition I want.\r\n\r\nBut if I want to describe a Username path parameter with the same characteristics, I cannot use a schema (only availble if `in` value is `body`). So I'll have to define again the characteristics of this Username atomic definition in the UsernameParameter.\r\n\r\nBefore: Username is described twice\r\n```YAML\r\npaths:\r\n  /persons/{username}:\r\n    get:\r\n      parameters:\r\n        - $ref: '#/parameters/UsernameParameter'\r\n      responses:\r\n        '200':\r\n          description: A person\r\n          schema:\r\n            $ref: '#/definitions/Person'\r\ndefinitions:\r\n  Username:\r\n    description: A person's username\r\n    type: string\r\n    pattern: '[a-z0-9]{8,64}'\r\n    minLength: 8\r\n    maxLength: 64\r\n  Person:\r\n    properties:\r\n      username:\r\n        # we can reference the atomic definition Username in any definition\r\n        $ref: '#/definitions/Username'\r\n      firstname:\r\n        type: string\r\n      lastname:\r\n        type: string\r\n      friends:\r\n        type: array\r\n        items:\r\n          # we can reference the atomic definition Username in any definition\r\n          $ref: '#/definitions/Friend'\r\n  Friend:\r\n    properties:\r\n      username:\r\n        $ref: '#/definitions/Username'\r\nparameters:\r\n  UsernameParameter:\r\n    name: username\r\n    in: path\r\n    required: true\r\n    # but we cannot reference the atomic definition Username in atomic parameters\r\n    # username is described twice\r\n    description: A person's username\r\n    type: string\r\n    pattern: '[a-z0-9]{8,64}'\r\n    minLength: 8\r\n    maxLength: 64\r\n```\r\n\r\nIf we could use schema: Username is described only once\r\n```YAML\r\npaths:\r\n  /persons/{username}:\r\n    get:\r\n      parameters:\r\n        - $ref: '#/parameters/UsernameParameter'\r\n      responses:\r\n        '200':\r\n          description: A person\r\n          schema:\r\n            $ref: '#/definitions/Person'\r\ndefinitions:\r\n  Username:\r\n    description: A person's username\r\n    type: string\r\n    pattern: '[a-z0-9]{8,64}'\r\n    minLength: 8\r\n    maxLength: 64\r\n  Person:\r\n    properties:\r\n      username:\r\n        $ref: '#/definitions/Username'\r\n      firstname:\r\n        type: string\r\n      lastname:\r\n        type: string\r\n      friends:\r\n        type: array\r\n        items:\r\n          $ref: '#/definitions/Friend'\r\n  Friend:\r\n    properties:\r\n      username:\r\n        $ref: '#/definitions/Username'\r\nparameters:\r\n  UsernameParameter:\r\n    name: username\r\n    in: path\r\n    required: true\r\n    # username can be used in an atomic parameted and is described once\r\n    schema:\r\n      $ref: '#/definitions/Username'\r\n```"}}