{"action":"created","comment":{"url":"https://api.github.com/repos/dotnet/docfx/pulls/comments/122625641","pull_request_review_id":44756060,"id":122625641,"diff_hunk":"@@ -0,0 +1,73 @@\n+# DocFX Document Schema Design Specification\n+\n+## 1. Introduction\n+DocFX supports different [document processors](..\\tutorial\\howto_build_your_own_type_of_documentation_with_custom_plug-in.md) to handle different kind of input. For now, if the data model changes a bit, a new document processor is needed, even most works in processors are the same.\n+\n+DocFX Document Schema (abbreviated to `this schema` below) is introduced to address ths problem. This schema is a JSON media type for defining the structure of a DocFX document. This schema is intended to define manipulation, documentation, validation of the document data.\n+\n+## 2. Conventions and Terminology\n+The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).\n+\n+## 3. Overview\n+DocFX Document Schema is in [JSON](http://www.json.org/) format. It borrows most syntax from [JSON Schema](http://json-schema.org/), while it also introduces some other syntax to manuplating the data.\n+\n+### 3.1 Validation\n+This schema can describe the structure of a DocFX document. \n+[JSON schema validation](http://json-schema.org/latest/json-schema-validation.html) already defines many keywords. This schema starts from supporting limited keyword like `type`, `properties`.\n+\n+### 3.2 Manipulation\n+This schema can describe how to handle each property of the document.\n+\n+Some handler is predefined in DocFX, like markup a string using [DFM](..\\spec\\docfx_flavored_markdown.md), mark a property as an uid, include content from another source, etc. \n+\n+Some handler can be injected into the schema parsing process to acomplish some custom steps.\n+\n+## 4. General Considerations\n+* This schema will reuses keywords in JSON schema, but will not change the defition of the existing one.","path":"Documentation/spec/docfx_document_schema.md","position":26,"original_position":26,"commit_id":"2c176a757cdfb28ff2344f62bc1d3b01b5f0d9e5","original_commit_id":"2c176a757cdfb28ff2344f62bc1d3b01b5f0d9e5","user":{"login":"hellosnow","id":1836885,"avatar_url":"https://avatars0.githubusercontent.com/u/1836885?v=3","gravatar_id":"","url":"https://api.github.com/users/hellosnow","html_url":"https://github.com/hellosnow","followers_url":"https://api.github.com/users/hellosnow/followers","following_url":"https://api.github.com/users/hellosnow/following{/other_user}","gists_url":"https://api.github.com/users/hellosnow/gists{/gist_id}","starred_url":"https://api.github.com/users/hellosnow/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hellosnow/subscriptions","organizations_url":"https://api.github.com/users/hellosnow/orgs","repos_url":"https://api.github.com/users/hellosnow/repos","events_url":"https://api.github.com/users/hellosnow/events{/privacy}","received_events_url":"https://api.github.com/users/hellosnow/received_events","type":"User","site_admin":false},"body":">reuses [](start = 19, length = 6)\r\n\r\nreuse?","created_at":"2017-06-19T06:00:37Z","updated_at":"2017-06-19T06:00:37Z","html_url":"https://github.com/dotnet/docfx/pull/1771#discussion_r122625641","pull_request_url":"https://api.github.com/repos/dotnet/docfx/pulls/1771","_links":{"self":{"href":"https://api.github.com/repos/dotnet/docfx/pulls/comments/122625641"},"html":{"href":"https://github.com/dotnet/docfx/pull/1771#discussion_r122625641"},"pull_request":{"href":"https://api.github.com/repos/dotnet/docfx/pulls/1771"}}},"pull_request":{"url":"https://api.github.com/repos/dotnet/docfx/pulls/1771","id":125993216,"html_url":"https://github.com/dotnet/docfx/pull/1771","diff_url":"https://github.com/dotnet/docfx/pull/1771.diff","patch_url":"https://github.com/dotnet/docfx/pull/1771.patch","issue_url":"https://api.github.com/repos/dotnet/docfx/issues/1771","number":1771,"state":"open","locked":false,"title":"init version of schema spec","user":{"login":"superyyrrzz","id":3831744,"avatar_url":"https://avatars2.githubusercontent.com/u/3831744?v=3","gravatar_id":"","url":"https://api.github.com/users/superyyrrzz","html_url":"https://github.com/superyyrrzz","followers_url":"https://api.github.com/users/superyyrrzz/followers","following_url":"https://api.github.com/users/superyyrrzz/following{/other_user}","gists_url":"https://api.github.com/users/superyyrrzz/gists{/gist_id}","starred_url":"https://api.github.com/users/superyyrrzz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/superyyrrzz/subscriptions","organizations_url":"https://api.github.com/users/superyyrrzz/orgs","repos_url":"https://api.github.com/users/superyyrrzz/repos","events_url":"https://api.github.com/users/superyyrrzz/events{/privacy}","received_events_url":"https://api.github.com/users/superyyrrzz/received_events","type":"User","site_admin":false},"body":"","created_at":"2017-06-16T09:24:46Z","updated_at":"2017-06-19T06:00:37Z","closed_at":null,"merged_at":null,"merge_commit_sha":"d6662af3504db4fdd6d3bf570b1381a101bb88d9","assignee":null,"assignees":[],"requested_reviewers":[{"login":"vicancy","id":668244,"avatar_url":"https://avatars3.githubusercontent.com/u/668244?v=3","gravatar_id":"","url":"https://api.github.com/users/vicancy","html_url":"https://github.com/vicancy","followers_url":"https://api.github.com/users/vicancy/followers","following_url":"https://api.github.com/users/vicancy/following{/other_user}","gists_url":"https://api.github.com/users/vicancy/gists{/gist_id}","starred_url":"https://api.github.com/users/vicancy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vicancy/subscriptions","organizations_url":"https://api.github.com/users/vicancy/orgs","repos_url":"https://api.github.com/users/vicancy/repos","events_url":"https://api.github.com/users/vicancy/events{/privacy}","received_events_url":"https://api.github.com/users/vicancy/received_events","type":"User","site_admin":false},{"login":"herohua","id":2174068,"avatar_url":"https://avatars0.githubusercontent.com/u/2174068?v=3","gravatar_id":"","url":"https://api.github.com/users/herohua","html_url":"https://github.com/herohua","followers_url":"https://api.github.com/users/herohua/followers","following_url":"https://api.github.com/users/herohua/following{/other_user}","gists_url":"https://api.github.com/users/herohua/gists{/gist_id}","starred_url":"https://api.github.com/users/herohua/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/herohua/subscriptions","organizations_url":"https://api.github.com/users/herohua/orgs","repos_url":"https://api.github.com/users/herohua/repos","events_url":"https://api.github.com/users/herohua/events{/privacy}","received_events_url":"https://api.github.com/users/herohua/received_events","type":"User","site_admin":false}],"milestone":null,"commits_url":"https://api.github.com/repos/dotnet/docfx/pulls/1771/commits","review_comments_url":"https://api.github.com/repos/dotnet/docfx/pulls/1771/comments","review_comment_url":"https://api.github.com/repos/dotnet/docfx/pulls/comments{/number}","comments_url":"https://api.github.com/repos/dotnet/docfx/issues/1771/comments","statuses_url":"https://api.github.com/repos/dotnet/docfx/statuses/2c176a757cdfb28ff2344f62bc1d3b01b5f0d9e5","head":{"label":"superyyrrzz:schema","ref":"schema","sha":"2c176a757cdfb28ff2344f62bc1d3b01b5f0d9e5","user":{"login":"superyyrrzz","id":3831744,"avatar_url":"https://avatars2.githubusercontent.com/u/3831744?v=3","gravatar_id":"","url":"https://api.github.com/users/superyyrrzz","html_url":"https://github.com/superyyrrzz","followers_url":"https://api.github.com/users/superyyrrzz/followers","following_url":"https://api.github.com/users/superyyrrzz/following{/other_user}","gists_url":"https://api.github.com/users/superyyrrzz/gists{/gist_id}","starred_url":"https://api.github.com/users/superyyrrzz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/superyyrrzz/subscriptions","organizations_url":"https://api.github.com/users/superyyrrzz/orgs","repos_url":"https://api.github.com/users/superyyrrzz/repos","events_url":"https://api.github.com/users/superyyrrzz/events{/privacy}","received_events_url":"https://api.github.com/users/superyyrrzz/received_events","type":"User","site_admin":false},"repo":{"id":55669383,"name":"docfx","full_name":"superyyrrzz/docfx","owner":{"login":"superyyrrzz","id":3831744,"avatar_url":"https://avatars2.githubusercontent.com/u/3831744?v=3","gravatar_id":"","url":"https://api.github.com/users/superyyrrzz","html_url":"https://github.com/superyyrrzz","followers_url":"https://api.github.com/users/superyyrrzz/followers","following_url":"https://api.github.com/users/superyyrrzz/following{/other_user}","gists_url":"https://api.github.com/users/superyyrrzz/gists{/gist_id}","starred_url":"https://api.github.com/users/superyyrrzz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/superyyrrzz/subscriptions","organizations_url":"https://api.github.com/users/superyyrrzz/orgs","repos_url":"https://api.github.com/users/superyyrrzz/repos","events_url":"https://api.github.com/users/superyyrrzz/events{/privacy}","received_events_url":"https://api.github.com/users/superyyrrzz/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/superyyrrzz/docfx","description":"Tools for building and publishing API documentation for .NET projects","fork":true,"url":"https://api.github.com/repos/superyyrrzz/docfx","forks_url":"https://api.github.com/repos/superyyrrzz/docfx/forks","keys_url":"https://api.github.com/repos/superyyrrzz/docfx/keys{/key_id}","collaborators_url":"https://api.github.com/repos/superyyrrzz/docfx/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/superyyrrzz/docfx/teams","hooks_url":"https://api.github.com/repos/superyyrrzz/docfx/hooks","issue_events_url":"https://api.github.com/repos/superyyrrzz/docfx/issues/events{/number}","events_url":"https://api.github.com/repos/superyyrrzz/docfx/events","assignees_url":"https://api.github.com/repos/superyyrrzz/docfx/assignees{/user}","branches_url":"https://api.github.com/repos/superyyrrzz/docfx/branches{/branch}","tags_url":"https://api.github.com/repos/superyyrrzz/docfx/tags","blobs_url":"https://api.github.com/repos/superyyrrzz/docfx/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/superyyrrzz/docfx/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/superyyrrzz/docfx/git/refs{/sha}","trees_url":"https://api.github.com/repos/superyyrrzz/docfx/git/trees{/sha}","statuses_url":"https://api.github.com/repos/superyyrrzz/docfx/statuses/{sha}","languages_url":"https://api.github.com/repos/superyyrrzz/docfx/languages","stargazers_url":"https://api.github.com/repos/superyyrrzz/docfx/stargazers","contributors_url":"https://api.github.com/repos/superyyrrzz/docfx/contributors","subscribers_url":"https://api.github.com/repos/superyyrrzz/docfx/subscribers","subscription_url":"https://api.github.com/repos/superyyrrzz/docfx/subscription","commits_url":"https://api.github.com/repos/superyyrrzz/docfx/commits{/sha}","git_commits_url":"https://api.github.com/repos/superyyrrzz/docfx/git/commits{/sha}","comments_url":"https://api.github.com/repos/superyyrrzz/docfx/comments{/number}","issue_comment_url":"https://api.github.com/repos/superyyrrzz/docfx/issues/comments{/number}","contents_url":"https://api.github.com/repos/superyyrrzz/docfx/contents/{+path}","compare_url":"https://api.github.com/repos/superyyrrzz/docfx/compare/{base}...{head}","merges_url":"https://api.github.com/repos/superyyrrzz/docfx/merges","archive_url":"https://api.github.com/repos/superyyrrzz/docfx/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/superyyrrzz/docfx/downloads","issues_url":"https://api.github.com/repos/superyyrrzz/docfx/issues{/number}","pulls_url":"https://api.github.com/repos/superyyrrzz/docfx/pulls{/number}","milestones_url":"https://api.github.com/repos/superyyrrzz/docfx/milestones{/number}","notifications_url":"https://api.github.com/repos/superyyrrzz/docfx/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/superyyrrzz/docfx/labels{/name}","releases_url":"https://api.github.com/repos/superyyrrzz/docfx/releases{/id}","deployments_url":"https://api.github.com/repos/superyyrrzz/docfx/deployments","created_at":"2016-04-07T06:28:32Z","updated_at":"2016-04-07T06:28:39Z","pushed_at":"2017-06-16T09:23:15Z","git_url":"git://github.com/superyyrrzz/docfx.git","ssh_url":"git@github.com:superyyrrzz/docfx.git","clone_url":"https://github.com/superyyrrzz/docfx.git","svn_url":"https://github.com/superyyrrzz/docfx","homepage":"http://dotnet.github.io/docfx/","size":146943,"stargazers_count":0,"watchers_count":0,"language":"C#","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"dev"}},"base":{"label":"dotnet:dev","ref":"dev","sha":"5cde139dca08d48f65d17c78377a372c60ba04a6","user":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars3.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"repo":{"id":38007053,"name":"docfx","full_name":"dotnet/docfx","owner":{"login":"dotnet","id":9141961,"avatar_url":"https://avatars3.githubusercontent.com/u/9141961?v=3","gravatar_id":"","url":"https://api.github.com/users/dotnet","html_url":"https://github.com/dotnet","followers_url":"https://api.github.com/users/dotnet/followers","following_url":"https://api.github.com/users/dotnet/following{/other_user}","gists_url":"https://api.github.com/users/dotnet/gists{/gist_id}","starred_url":"https://api.github.com/users/dotnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dotnet/subscriptions","organizations_url":"https://api.github.com/users/dotnet/orgs","repos_url":"https://api.github.com/users/dotnet/repos","events_url":"https://api.github.com/users/dotnet/events{/privacy}","received_events_url":"https://api.github.com/users/dotnet/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/dotnet/docfx","description":"Tools for building and publishing API documentation for .NET projects","fork":false,"url":"https://api.github.com/repos/dotnet/docfx","forks_url":"https://api.github.com/repos/dotnet/docfx/forks","keys_url":"https://api.github.com/repos/dotnet/docfx/keys{/key_id}","collaborators_url":"https://api.github.com/repos/dotnet/docfx/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/dotnet/docfx/teams","hooks_url":"https://api.github.com/repos/dotnet/docfx/hooks","issue_events_url":"https://api.github.com/repos/dotnet/docfx/issues/events{/number}","events_url":"https://api.github.com/repos/dotnet/docfx/events","assignees_url":"https://api.github.com/repos/dotnet/docfx/assignees{/user}","branches_url":"https://api.github.com/repos/dotnet/docfx/branches{/branch}","tags_url":"https://api.github.com/repos/dotnet/docfx/tags","blobs_url":"https://api.github.com/repos/dotnet/docfx/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/dotnet/docfx/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/dotnet/docfx/git/refs{/sha}","trees_url":"https://api.github.com/repos/dotnet/docfx/git/trees{/sha}","statuses_url":"https://api.github.com/repos/dotnet/docfx/statuses/{sha}","languages_url":"https://api.github.com/repos/dotnet/docfx/languages","stargazers_url":"https://api.github.com/repos/dotnet/docfx/stargazers","contributors_url":"https://api.github.com/repos/dotnet/docfx/contributors","subscribers_url":"https://api.github.com/repos/dotnet/docfx/subscribers","subscription_url":"https://api.github.com/repos/dotnet/docfx/subscription","commits_url":"https://api.github.com/repos/dotnet/docfx/commits{/sha}","git_commits_url":"https://api.github.com/repos/dotnet/docfx/git/commits{/sha}","comments_url":"https://api.github.com/repos/dotnet/docfx/comments{/number}","issue_comment_url":"https://api.github.com/repos/dotnet/docfx/issues/comments{/number}","contents_url":"https://api.github.com/repos/dotnet/docfx/contents/{+path}","compare_url":"https://api.github.com/repos/dotnet/docfx/compare/{base}...{head}","merges_url":"https://api.github.com/repos/dotnet/docfx/merges","archive_url":"https://api.github.com/repos/dotnet/docfx/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/dotnet/docfx/downloads","issues_url":"https://api.github.com/repos/dotnet/docfx/issues{/number}","pulls_url":"https://api.github.com/repos/dotnet/docfx/pulls{/number}","milestones_url":"https://api.github.com/repos/dotnet/docfx/milestones{/number}","notifications_url":"https://api.github.com/repos/dotnet/docfx/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/dotnet/docfx/labels{/name}","releases_url":"https://api.github.com/repos/dotnet/docfx/releases{/id}","deployments_url":"https://api.github.com/repos/dotnet/docfx/deployments","created_at":"2015-06-24T19:43:53Z","updated_at":"2017-06-19T01:00:42Z","pushed_at":"2017-06-19T05:58:38Z","git_url":"git://github.com/dotnet/docfx.git","ssh_url":"git@github.com:dotnet/docfx.git","clone_url":"https://github.com/dotnet/docfx.git","svn_url":"https://github.com/dotnet/docfx","homepage":"http://dotnet.github.io/docfx/","size":216303,"stargazers_count":688,"watchers_count":688,"language":"C#","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":false,"has_pages":true,"forks_count":193,"mirror_url":null,"open_issues_count":85,"forks":193,"open_issues":85,"watchers":688,"default_branch":"dev"}},"_links":{"self":{"href":"https://api.github.com/repos/dotnet/docfx/pulls/1771"},"html":{"href":"https://github.com/dotnet/docfx/pull/1771"},"issue":{"href":"https://api.github.com/repos/dotnet/docfx/issues/1771"},"comments":{"href":"https://api.github.com/repos/dotnet/docfx/issues/1771/comments"},"review_comments":{"href":"https://api.github.com/repos/dotnet/docfx/pulls/1771/comments"},"review_comment":{"href":"https://api.github.com/repos/dotnet/docfx/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/dotnet/docfx/pulls/1771/commits"},"statuses":{"href":"https://api.github.com/repos/dotnet/docfx/statuses/2c176a757cdfb28ff2344f62bc1d3b01b5f0d9e5"}}}}
{"actor":{"display_login":"hellosnow"}}