{"action":"created","comment":{"url":"https://api.github.com/repos/apiaryio/api-elements/pulls/comments/98237833","pull_request_review_id":18875575,"id":98237833,"diff_hunk":"@@ -86,10 +86,42 @@ The value of the `Templated Href` type SHOULD be resolved as a URI-Reference per\n \n The definition is a Data Structure element `Object Type` where keys are respective URI Template variables.\n \n+**NOTE:** *A href variable may include an attribute `type` which may\n+contain a label for the variable type.*\n+\n #### Properties\n \n - `element`: hrefVariables (string, fixed)","path":"docs/element-definitions.md","position":9,"original_position":9,"commit_id":"601dbe6f788999c9f681f6b5de9bc9d093fe9984","original_commit_id":"601dbe6f788999c9f681f6b5de9bc9d093fe9984","user":{"login":"kylef","id":44164,"avatar_url":"https://avatars.githubusercontent.com/u/44164?v=3","gravatar_id":"","url":"https://api.github.com/users/kylef","html_url":"https://github.com/kylef","followers_url":"https://api.github.com/users/kylef/followers","following_url":"https://api.github.com/users/kylef/following{/other_user}","gists_url":"https://api.github.com/users/kylef/gists{/gist_id}","starred_url":"https://api.github.com/users/kylef/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kylef/subscriptions","organizations_url":"https://api.github.com/users/kylef/orgs","repos_url":"https://api.github.com/users/kylef/repos","events_url":"https://api.github.com/users/kylef/events{/privacy}","received_events_url":"https://api.github.com/users/kylef/received_events","type":"User","site_admin":false},"body":"I don't think so, as the attributes isn't on `hrefVariables` itself, but the members within `hrefVariables`. Open to suggestions on how to document this further. Perhaps:\r\n\r\n```apib\r\n### Properties\r\n\r\n- `element`: hrefVariables (string, fixed)\r\n- `content` (array[member])\r\n    - (member)\r\n        - attributes (object)\r\n            - type\r\n```","created_at":"2017-01-27T16:26:17Z","updated_at":"2017-01-27T16:26:17Z","html_url":"https://github.com/apiaryio/api-elements/pull/20#discussion_r98237833","pull_request_url":"https://api.github.com/repos/apiaryio/api-elements/pulls/20","_links":{"self":{"href":"https://api.github.com/repos/apiaryio/api-elements/pulls/comments/98237833"},"html":{"href":"https://github.com/apiaryio/api-elements/pull/20#discussion_r98237833"},"pull_request":{"href":"https://api.github.com/repos/apiaryio/api-elements/pulls/20"}}},"pull_request":{"url":"https://api.github.com/repos/apiaryio/api-elements/pulls/20","id":103511803,"html_url":"https://github.com/apiaryio/api-elements/pull/20","diff_url":"https://github.com/apiaryio/api-elements/pull/20.diff","patch_url":"https://github.com/apiaryio/api-elements/pull/20.patch","issue_url":"https://api.github.com/repos/apiaryio/api-elements/issues/20","number":20,"state":"open","locked":false,"title":"Allow `type` attribute for a href variable","user":{"login":"kylef","id":44164,"avatar_url":"https://avatars.githubusercontent.com/u/44164?v=3","gravatar_id":"","url":"https://api.github.com/users/kylef","html_url":"https://github.com/kylef","followers_url":"https://api.github.com/users/kylef/followers","following_url":"https://api.github.com/users/kylef/following{/other_user}","gists_url":"https://api.github.com/users/kylef/gists{/gist_id}","starred_url":"https://api.github.com/users/kylef/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kylef/subscriptions","organizations_url":"https://api.github.com/users/kylef/orgs","repos_url":"https://api.github.com/users/kylef/repos","events_url":"https://api.github.com/users/kylef/events{/privacy}","received_events_url":"https://api.github.com/users/kylef/received_events","type":"User","site_admin":false},"body":"This PR introduces a new attributed called `type` for a href variable along with including a full example of a `HrefVariables` element.\r\n\r\nThis allows solving two problems:\r\n\r\n1) Loss of type information, API Blueprint supports freeform text for parameter type which couldn't be represented in API Elements.\r\n2) Incorrect re-serialisation of values such as booleans.\r\n\r\nPreviously parsers such as the API Blueprint parser Drafter cannot store the raw representation a user used for a type for example given the following parameter in an API Blueprint:\r\n\r\n```apib\r\n+ Parameters\r\n    + since (datetime)\r\n```\r\n\r\nWithout MSON Parameters, this would be treated as a string internally and serialised in API Elements as such. Inside [API Blueprint AST](https://github.com/apiaryio/api-blueprint-ast#parameter-object) the type would be available. This may be unnecessary for some types such as numerical types where they can be represented as Refract primitives:\r\n\r\n```json\r\n{\r\n  \"element\": \"hrefVariables\",\r\n  \"content\": [\r\n    {\r\n      \"element\": \"member\",\r\n      \"content\": {\r\n        \"key\": {\r\n          \"element\": \"string\",\r\n          \"content\": \"since\"\r\n        },\r\n        \"value\": {\r\n          \"element\": \"number\"\r\n        }\r\n      }\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\nHowever in API Blueprint a parameter type is purely just freeform text, and there are no restrictions on the type values and how they would be represented in a URL. Unlike MSON where you would always serialise in a specific format so you can have expectations that booleans values may be `true` or `false`. This isn't the case in parameters as there are no standards that define how data types should be serialised in a URI. As an example:\r\n\r\n```apib\r\n+ Parameters\r\n    + `is_admin`: 1 (boolean)\r\n```\r\n\r\nIt would be fully expected that `1` is a valid value as per the API Blueprint specification. The specifications mentions no limitations on value types, and as there are no expectations on how values are serialised into URLs, it should be expected that `1` would end up in the URL if the template `/users{?is_admin}` was expanded `/users?is_admin=1`. As URIs do not have any upfront expectation of how values (boolean, number, etc) would be serialised it would be incorrect to force booleans to be `true`/`false` and serialised as either `true` or `false`.\r\n\r\nThis isn't the case at the moment in Drafter with API Elements serialisation. Since `boolean` would currently be mapped to a API Elements type boolean where `1` isn't picked up as a `true` value so the default would be `false`. Also, this means that tools would serialise the boolean value as `true` or `false` instead of what the user intended as `0` or `1`. Ideally users would specify an enum in API Blueprint, however that isn't nice because API Blueprint would currently require you to duplicate the enum type. In future this could be much more elegant when a user could declare a parameter boolean type of enum and reuse it.\r\n\r\n```apib\r\n+ Parameters\r\n    + `is_admin`: 1 (enum)\r\n        + 1\r\n         + 0\r\n```\r\n\r\n/c @smizell would love to get your feedback here if you have some spare time to take a look.","created_at":"2017-01-27T15:29:31Z","updated_at":"2017-01-27T16:26:17Z","closed_at":null,"merged_at":null,"merge_commit_sha":"94e794ad25975648d48defaaa8950ef4a1331a4c","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/apiaryio/api-elements/pulls/20/commits","review_comments_url":"https://api.github.com/repos/apiaryio/api-elements/pulls/20/comments","review_comment_url":"https://api.github.com/repos/apiaryio/api-elements/pulls/comments{/number}","comments_url":"https://api.github.com/repos/apiaryio/api-elements/issues/20/comments","statuses_url":"https://api.github.com/repos/apiaryio/api-elements/statuses/601dbe6f788999c9f681f6b5de9bc9d093fe9984","head":{"label":"apiaryio:kylef/href-variable-type","ref":"kylef/href-variable-type","sha":"601dbe6f788999c9f681f6b5de9bc9d093fe9984","user":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"repo":{"id":52306093,"name":"api-elements","full_name":"apiaryio/api-elements","owner":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apiaryio/api-elements","description":null,"fork":false,"url":"https://api.github.com/repos/apiaryio/api-elements","forks_url":"https://api.github.com/repos/apiaryio/api-elements/forks","keys_url":"https://api.github.com/repos/apiaryio/api-elements/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apiaryio/api-elements/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apiaryio/api-elements/teams","hooks_url":"https://api.github.com/repos/apiaryio/api-elements/hooks","issue_events_url":"https://api.github.com/repos/apiaryio/api-elements/issues/events{/number}","events_url":"https://api.github.com/repos/apiaryio/api-elements/events","assignees_url":"https://api.github.com/repos/apiaryio/api-elements/assignees{/user}","branches_url":"https://api.github.com/repos/apiaryio/api-elements/branches{/branch}","tags_url":"https://api.github.com/repos/apiaryio/api-elements/tags","blobs_url":"https://api.github.com/repos/apiaryio/api-elements/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apiaryio/api-elements/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apiaryio/api-elements/git/refs{/sha}","trees_url":"https://api.github.com/repos/apiaryio/api-elements/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apiaryio/api-elements/statuses/{sha}","languages_url":"https://api.github.com/repos/apiaryio/api-elements/languages","stargazers_url":"https://api.github.com/repos/apiaryio/api-elements/stargazers","contributors_url":"https://api.github.com/repos/apiaryio/api-elements/contributors","subscribers_url":"https://api.github.com/repos/apiaryio/api-elements/subscribers","subscription_url":"https://api.github.com/repos/apiaryio/api-elements/subscription","commits_url":"https://api.github.com/repos/apiaryio/api-elements/commits{/sha}","git_commits_url":"https://api.github.com/repos/apiaryio/api-elements/git/commits{/sha}","comments_url":"https://api.github.com/repos/apiaryio/api-elements/comments{/number}","issue_comment_url":"https://api.github.com/repos/apiaryio/api-elements/issues/comments{/number}","contents_url":"https://api.github.com/repos/apiaryio/api-elements/contents/{+path}","compare_url":"https://api.github.com/repos/apiaryio/api-elements/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apiaryio/api-elements/merges","archive_url":"https://api.github.com/repos/apiaryio/api-elements/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apiaryio/api-elements/downloads","issues_url":"https://api.github.com/repos/apiaryio/api-elements/issues{/number}","pulls_url":"https://api.github.com/repos/apiaryio/api-elements/pulls{/number}","milestones_url":"https://api.github.com/repos/apiaryio/api-elements/milestones{/number}","notifications_url":"https://api.github.com/repos/apiaryio/api-elements/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apiaryio/api-elements/labels{/name}","releases_url":"https://api.github.com/repos/apiaryio/api-elements/releases{/id}","deployments_url":"https://api.github.com/repos/apiaryio/api-elements/deployments","created_at":"2016-02-22T21:10:59Z","updated_at":"2016-12-20T10:13:43Z","pushed_at":"2017-01-27T15:29:32Z","git_url":"git://github.com/apiaryio/api-elements.git","ssh_url":"git@github.com:apiaryio/api-elements.git","clone_url":"https://github.com/apiaryio/api-elements.git","svn_url":"https://github.com/apiaryio/api-elements","homepage":"http://api-elements.readthedocs.org/","size":123,"stargazers_count":9,"watchers_count":9,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":5,"forks":1,"open_issues":5,"watchers":9,"default_branch":"master"}},"base":{"label":"apiaryio:master","ref":"master","sha":"cbb0808615cffae585e27c51c3485f912f92ac8c","user":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"repo":{"id":52306093,"name":"api-elements","full_name":"apiaryio/api-elements","owner":{"login":"apiaryio","id":765943,"avatar_url":"https://avatars.githubusercontent.com/u/765943?v=3","gravatar_id":"","url":"https://api.github.com/users/apiaryio","html_url":"https://github.com/apiaryio","followers_url":"https://api.github.com/users/apiaryio/followers","following_url":"https://api.github.com/users/apiaryio/following{/other_user}","gists_url":"https://api.github.com/users/apiaryio/gists{/gist_id}","starred_url":"https://api.github.com/users/apiaryio/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/apiaryio/subscriptions","organizations_url":"https://api.github.com/users/apiaryio/orgs","repos_url":"https://api.github.com/users/apiaryio/repos","events_url":"https://api.github.com/users/apiaryio/events{/privacy}","received_events_url":"https://api.github.com/users/apiaryio/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/apiaryio/api-elements","description":null,"fork":false,"url":"https://api.github.com/repos/apiaryio/api-elements","forks_url":"https://api.github.com/repos/apiaryio/api-elements/forks","keys_url":"https://api.github.com/repos/apiaryio/api-elements/keys{/key_id}","collaborators_url":"https://api.github.com/repos/apiaryio/api-elements/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/apiaryio/api-elements/teams","hooks_url":"https://api.github.com/repos/apiaryio/api-elements/hooks","issue_events_url":"https://api.github.com/repos/apiaryio/api-elements/issues/events{/number}","events_url":"https://api.github.com/repos/apiaryio/api-elements/events","assignees_url":"https://api.github.com/repos/apiaryio/api-elements/assignees{/user}","branches_url":"https://api.github.com/repos/apiaryio/api-elements/branches{/branch}","tags_url":"https://api.github.com/repos/apiaryio/api-elements/tags","blobs_url":"https://api.github.com/repos/apiaryio/api-elements/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/apiaryio/api-elements/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/apiaryio/api-elements/git/refs{/sha}","trees_url":"https://api.github.com/repos/apiaryio/api-elements/git/trees{/sha}","statuses_url":"https://api.github.com/repos/apiaryio/api-elements/statuses/{sha}","languages_url":"https://api.github.com/repos/apiaryio/api-elements/languages","stargazers_url":"https://api.github.com/repos/apiaryio/api-elements/stargazers","contributors_url":"https://api.github.com/repos/apiaryio/api-elements/contributors","subscribers_url":"https://api.github.com/repos/apiaryio/api-elements/subscribers","subscription_url":"https://api.github.com/repos/apiaryio/api-elements/subscription","commits_url":"https://api.github.com/repos/apiaryio/api-elements/commits{/sha}","git_commits_url":"https://api.github.com/repos/apiaryio/api-elements/git/commits{/sha}","comments_url":"https://api.github.com/repos/apiaryio/api-elements/comments{/number}","issue_comment_url":"https://api.github.com/repos/apiaryio/api-elements/issues/comments{/number}","contents_url":"https://api.github.com/repos/apiaryio/api-elements/contents/{+path}","compare_url":"https://api.github.com/repos/apiaryio/api-elements/compare/{base}...{head}","merges_url":"https://api.github.com/repos/apiaryio/api-elements/merges","archive_url":"https://api.github.com/repos/apiaryio/api-elements/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/apiaryio/api-elements/downloads","issues_url":"https://api.github.com/repos/apiaryio/api-elements/issues{/number}","pulls_url":"https://api.github.com/repos/apiaryio/api-elements/pulls{/number}","milestones_url":"https://api.github.com/repos/apiaryio/api-elements/milestones{/number}","notifications_url":"https://api.github.com/repos/apiaryio/api-elements/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/apiaryio/api-elements/labels{/name}","releases_url":"https://api.github.com/repos/apiaryio/api-elements/releases{/id}","deployments_url":"https://api.github.com/repos/apiaryio/api-elements/deployments","created_at":"2016-02-22T21:10:59Z","updated_at":"2016-12-20T10:13:43Z","pushed_at":"2017-01-27T15:29:32Z","git_url":"git://github.com/apiaryio/api-elements.git","ssh_url":"git@github.com:apiaryio/api-elements.git","clone_url":"https://github.com/apiaryio/api-elements.git","svn_url":"https://github.com/apiaryio/api-elements","homepage":"http://api-elements.readthedocs.org/","size":123,"stargazers_count":9,"watchers_count":9,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1,"mirror_url":null,"open_issues_count":5,"forks":1,"open_issues":5,"watchers":9,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/apiaryio/api-elements/pulls/20"},"html":{"href":"https://github.com/apiaryio/api-elements/pull/20"},"issue":{"href":"https://api.github.com/repos/apiaryio/api-elements/issues/20"},"comments":{"href":"https://api.github.com/repos/apiaryio/api-elements/issues/20/comments"},"review_comments":{"href":"https://api.github.com/repos/apiaryio/api-elements/pulls/20/comments"},"review_comment":{"href":"https://api.github.com/repos/apiaryio/api-elements/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/apiaryio/api-elements/pulls/20/commits"},"statuses":{"href":"https://api.github.com/repos/apiaryio/api-elements/statuses/601dbe6f788999c9f681f6b5de9bc9d093fe9984"}}}}
{"actor":{"display_login":"kylef"}}