{"action":"created","comment":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments/67556711","id":67556711,"diff_hunk":"@@ -1123,6 +1125,344 @@ application/json:\n   breed: Mixed\n ```\n \n+#### <a name=\"linksObject\"></a>Links Object\n+The links object represents a set of possible design-time links for a response.  The presence of a link does not guarantee the caller's ability to successfully call invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.\n+\n+As opposed to _dynamic_ links--that is, links provided **in** the response payload, the OAS linking mechanism does not require that link information be provided in a specific response format at runtime.\n+\n+For computing links, and providing instructions to execute them, a mechanism is defined for accessing values in a response and using them as variables while invoking the linked operation.\n+\n+Field Name | Type | Description\n+---|:---:|---\n+<a name=\"referenceRef\"></a>$ref | `string` | If present, a reference to another Links Object.  Note, the presence of `$ref` in the Links Object will cause all _Patterned Objects_ to be ignored. \n+\n+Field Pattern | Type | Description\n+---|:---:|---\n+<a name=\"linkName\"></a>link name | [Link Object](#linkObject) | A short name for the link, following the naming constraints of the <a href=\"#definitionsName\">definitions name</a>.  The link shall reference a single Link Object, or a JSON Reference to a single link object\n+\n+\n+### Link Object\n+The `Link Object` is responsible for defining a possible operation based on a single response.\n+\n+Field Name  |  Type  | Description\n+  ---       | :---:  |     ---\n+href      |  url   | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field.\n+ operationId| string | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive with the `href` field.  Relative `href` values _may_ be used to locate an existing Operation Object in the OAS.","path":"versions/3.0.md","position":44,"original_position":44,"commit_id":"30c10c6268be84f46263f5773a90c14cb89efe96","original_commit_id":"30c10c6268be84f46263f5773a90c14cb89efe96","user":{"login":"fehguy","id":249413,"avatar_url":"https://avatars.githubusercontent.com/u/249413?v=3","gravatar_id":"","url":"https://api.github.com/users/fehguy","html_url":"https://github.com/fehguy","followers_url":"https://api.github.com/users/fehguy/followers","following_url":"https://api.github.com/users/fehguy/following{/other_user}","gists_url":"https://api.github.com/users/fehguy/gists{/gist_id}","starred_url":"https://api.github.com/users/fehguy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fehguy/subscriptions","organizations_url":"https://api.github.com/users/fehguy/orgs","repos_url":"https://api.github.com/users/fehguy/repos","events_url":"https://api.github.com/users/fehguy/events{/privacy}","received_events_url":"https://api.github.com/users/fehguy/received_events","type":"User","site_admin":false},"body":"```\r\nhref: '/foo'\r\nmethod: 'get'\r\n```\r\n\r\n```\r\npaths:\r\n  /foo:\r\n    $ref: 'http://gigantic-server.com/#paths/fooPath'\r\n```\r\n\r\non `gigantic-server.com`:\r\n\r\n```\r\npaths:\r\n  fooPath:\r\n    get:\r\n      operationId: conflict # !!!\r\n```","created_at":"2016-06-17T18:40:17Z","updated_at":"2016-06-17T18:40:17Z","html_url":"https://github.com/OAI/OpenAPI-Specification/pull/710#discussion_r67556711","pull_request_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710","_links":{"self":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments/67556711"},"html":{"href":"https://github.com/OAI/OpenAPI-Specification/pull/710#discussion_r67556711"},"pull_request":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710"}}},"pull_request":{"url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710","id":73242460,"html_url":"https://github.com/OAI/OpenAPI-Specification/pull/710","diff_url":"https://github.com/OAI/OpenAPI-Specification/pull/710.diff","patch_url":"https://github.com/OAI/OpenAPI-Specification/pull/710.patch","issue_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/710","number":710,"state":"open","locked":false,"title":"added links proposal","user":{"login":"fehguy","id":249413,"avatar_url":"https://avatars.githubusercontent.com/u/249413?v=3","gravatar_id":"","url":"https://api.github.com/users/fehguy","html_url":"https://github.com/fehguy","followers_url":"https://api.github.com/users/fehguy/followers","following_url":"https://api.github.com/users/fehguy/following{/other_user}","gists_url":"https://api.github.com/users/fehguy/gists{/gist_id}","starred_url":"https://api.github.com/users/fehguy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fehguy/subscriptions","organizations_url":"https://api.github.com/users/fehguy/orgs","repos_url":"https://api.github.com/users/fehguy/repos","events_url":"https://api.github.com/users/fehguy/events{/privacy}","received_events_url":"https://api.github.com/users/fehguy/received_events","type":"User","site_admin":false},"body":"To support HAL-style linking, as suggested in #688, I propose the following:\r\n\r\n* A mechanism for design-time, _static_ links between responses and operations to make operations on responses visible to consumers\r\n* A reusable linking structure to allow link definitions to be DRY\r\n* A mechasim for parameterized link traversal to avoid server-side computation of links through reuse of existing, OAS-defined operations\r\n\r\nAdditional considerations:\r\n* This is not intended to be a _run time_ linking solution.  This solution does not require users to redesign their runtime API.  It _may_ be able to represent the intent of runtime HAL-style links in responses.  It does _not_ intend to represent dynamically generated, arbitrary links.\r\n* A clear separation of concerns, between payloads and operations.  Therefore no _operation data_ shall be tied to payload schemas.\r\n\r\nSpec changes\r\n* Introduction of a `Link Object` to represent a single `link`\r\n* Addition of a  `links` object in the `Response Object` to define what links are available from a specific operation\r\n* Addition of a `links` section in the `Components Object` to allow reuse across operations\r\n* Introduction of a `Link Parameters Object` to represent parameters to build a link from\r\n* A mechanism for reading values from response payloads and using them for client-side link computation\r\n","created_at":"2016-06-09T16:11:22Z","updated_at":"2016-06-17T18:40:17Z","closed_at":null,"merged_at":null,"merge_commit_sha":"c703ea60a6849d5407030408201d49a76e1d2ac9","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710/commits","review_comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710/comments","review_comment_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/710/comments","statuses_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/30c10c6268be84f46263f5773a90c14cb89efe96","head":{"label":"OAI:feature/links","ref":"feature/links","sha":"30c10c6268be84f46263f5773a90c14cb89efe96","user":{"login":"OAI","id":16343502,"avatar_url":"https://avatars.githubusercontent.com/u/16343502?v=3","gravatar_id":"","url":"https://api.github.com/users/OAI","html_url":"https://github.com/OAI","followers_url":"https://api.github.com/users/OAI/followers","following_url":"https://api.github.com/users/OAI/following{/other_user}","gists_url":"https://api.github.com/users/OAI/gists{/gist_id}","starred_url":"https://api.github.com/users/OAI/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/OAI/subscriptions","organizations_url":"https://api.github.com/users/OAI/orgs","repos_url":"https://api.github.com/users/OAI/repos","events_url":"https://api.github.com/users/OAI/events{/privacy}","received_events_url":"https://api.github.com/users/OAI/received_events","type":"Organization","site_admin":false},"repo":{"id":17372733,"name":"OpenAPI-Specification","full_name":"OAI/OpenAPI-Specification","owner":{"login":"OAI","id":16343502,"avatar_url":"https://avatars.githubusercontent.com/u/16343502?v=3","gravatar_id":"","url":"https://api.github.com/users/OAI","html_url":"https://github.com/OAI","followers_url":"https://api.github.com/users/OAI/followers","following_url":"https://api.github.com/users/OAI/following{/other_user}","gists_url":"https://api.github.com/users/OAI/gists{/gist_id}","starred_url":"https://api.github.com/users/OAI/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/OAI/subscriptions","organizations_url":"https://api.github.com/users/OAI/orgs","repos_url":"https://api.github.com/users/OAI/repos","events_url":"https://api.github.com/users/OAI/events{/privacy}","received_events_url":"https://api.github.com/users/OAI/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/OAI/OpenAPI-Specification","description":"The OpenAPI Specification Repository","fork":false,"url":"https://api.github.com/repos/OAI/OpenAPI-Specification","forks_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/forks","keys_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/keys{/key_id}","collaborators_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/teams","hooks_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/hooks","issue_events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/events{/number}","events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/events","assignees_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/assignees{/user}","branches_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/branches{/branch}","tags_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/tags","blobs_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/refs{/sha}","trees_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/trees{/sha}","statuses_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/{sha}","languages_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/languages","stargazers_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/stargazers","contributors_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/contributors","subscribers_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/subscribers","subscription_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/subscription","commits_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/commits{/sha}","git_commits_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/commits{/sha}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/comments{/number}","issue_comment_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/comments{/number}","contents_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/contents/{+path}","compare_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/compare/{base}...{head}","merges_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/merges","archive_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/downloads","issues_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues{/number}","pulls_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls{/number}","milestones_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/milestones{/number}","notifications_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/labels{/name}","releases_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/releases{/id}","deployments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/deployments","created_at":"2014-03-03T16:53:36Z","updated_at":"2016-06-17T17:27:08Z","pushed_at":"2016-06-15T17:00:50Z","git_url":"git://github.com/OAI/OpenAPI-Specification.git","ssh_url":"git@github.com:OAI/OpenAPI-Specification.git","clone_url":"https://github.com/OAI/OpenAPI-Specification.git","svn_url":"https://github.com/OAI/OpenAPI-Specification","homepage":"https://openapis.org","size":1508,"stargazers_count":3901,"watchers_count":3901,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1184,"mirror_url":null,"open_issues_count":225,"forks":1184,"open_issues":225,"watchers":3901,"default_branch":"master"}},"base":{"label":"OAI:OpenAPI.next","ref":"OpenAPI.next","sha":"6d25b128ac6893f9ebb417103e1e244e3709695a","user":{"login":"OAI","id":16343502,"avatar_url":"https://avatars.githubusercontent.com/u/16343502?v=3","gravatar_id":"","url":"https://api.github.com/users/OAI","html_url":"https://github.com/OAI","followers_url":"https://api.github.com/users/OAI/followers","following_url":"https://api.github.com/users/OAI/following{/other_user}","gists_url":"https://api.github.com/users/OAI/gists{/gist_id}","starred_url":"https://api.github.com/users/OAI/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/OAI/subscriptions","organizations_url":"https://api.github.com/users/OAI/orgs","repos_url":"https://api.github.com/users/OAI/repos","events_url":"https://api.github.com/users/OAI/events{/privacy}","received_events_url":"https://api.github.com/users/OAI/received_events","type":"Organization","site_admin":false},"repo":{"id":17372733,"name":"OpenAPI-Specification","full_name":"OAI/OpenAPI-Specification","owner":{"login":"OAI","id":16343502,"avatar_url":"https://avatars.githubusercontent.com/u/16343502?v=3","gravatar_id":"","url":"https://api.github.com/users/OAI","html_url":"https://github.com/OAI","followers_url":"https://api.github.com/users/OAI/followers","following_url":"https://api.github.com/users/OAI/following{/other_user}","gists_url":"https://api.github.com/users/OAI/gists{/gist_id}","starred_url":"https://api.github.com/users/OAI/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/OAI/subscriptions","organizations_url":"https://api.github.com/users/OAI/orgs","repos_url":"https://api.github.com/users/OAI/repos","events_url":"https://api.github.com/users/OAI/events{/privacy}","received_events_url":"https://api.github.com/users/OAI/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/OAI/OpenAPI-Specification","description":"The OpenAPI Specification Repository","fork":false,"url":"https://api.github.com/repos/OAI/OpenAPI-Specification","forks_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/forks","keys_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/keys{/key_id}","collaborators_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/teams","hooks_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/hooks","issue_events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/events{/number}","events_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/events","assignees_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/assignees{/user}","branches_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/branches{/branch}","tags_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/tags","blobs_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/refs{/sha}","trees_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/trees{/sha}","statuses_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/{sha}","languages_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/languages","stargazers_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/stargazers","contributors_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/contributors","subscribers_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/subscribers","subscription_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/subscription","commits_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/commits{/sha}","git_commits_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/git/commits{/sha}","comments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/comments{/number}","issue_comment_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/comments{/number}","contents_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/contents/{+path}","compare_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/compare/{base}...{head}","merges_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/merges","archive_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/downloads","issues_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues{/number}","pulls_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls{/number}","milestones_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/milestones{/number}","notifications_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/labels{/name}","releases_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/releases{/id}","deployments_url":"https://api.github.com/repos/OAI/OpenAPI-Specification/deployments","created_at":"2014-03-03T16:53:36Z","updated_at":"2016-06-17T17:27:08Z","pushed_at":"2016-06-15T17:00:50Z","git_url":"git://github.com/OAI/OpenAPI-Specification.git","ssh_url":"git@github.com:OAI/OpenAPI-Specification.git","clone_url":"https://github.com/OAI/OpenAPI-Specification.git","svn_url":"https://github.com/OAI/OpenAPI-Specification","homepage":"https://openapis.org","size":1508,"stargazers_count":3901,"watchers_count":3901,"language":"JavaScript","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1184,"mirror_url":null,"open_issues_count":225,"forks":1184,"open_issues":225,"watchers":3901,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710"},"html":{"href":"https://github.com/OAI/OpenAPI-Specification/pull/710"},"issue":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/710"},"comments":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/issues/710/comments"},"review_comments":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710/comments"},"review_comment":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/pulls/710/commits"},"statuses":{"href":"https://api.github.com/repos/OAI/OpenAPI-Specification/statuses/30c10c6268be84f46263f5773a90c14cb89efe96"}}}}
{"actor":{"display_login":"fehguy"}}