{"action":"created","comment":{"url":"https://api.github.com/repos/mongodb/specifications/pulls/comments/98061714","pull_request_review_id":18691952,"id":98061714,"diff_hunk":"@@ -0,0 +1,618 @@\n+=============\n+Extended JSON\n+=============\n+\n+:Spec: 587\n+:Spec-ticket: SPEC-587\n+:Title: Extended JSON\n+:Author: Luke Lovett\n+:Spec Lead: David Golden\n+:Advisory Group: Mike O'Brien, Christian Kvalheim, Hannes Magnusson\n+:Status: Draft\n+:Type: Standards\n+:Last Modified: January 23, 2017\n+:Version: 1.0.0\n+\n+.. contents::\n+\n+--------\n+\n+Abstract\n+========\n+\n+MongoDB extended JSON is a string format for representing BSON documents. This\n+specification defines the canonical format for representing each BSON type in\n+the extended JSON format. Thus, a tool that implements extended JSON will be\n+able to parse the output of any tool that emits canonical extended JSON.\n+\n+META\n+====\n+\n+The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,\n+“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be\n+interpreted as described in `RFC 2119 <https://www.ietf.org/rfc/rfc2119.txt>`_.\n+\n+Terms\n+=====\n+\n+*Historical extended JSON* - A string format based on the JSON standard that\n+describes a BSON document. The historical extended JSON format does not describe\n+a specific, standardized format, and many tools, drivers, and libraries\n+implement extended JSON in conflicting ways.\n+\n+*Extended JSON* - A string format based on the JSON standard that describes BSON\n+documents. This specification gives a formal definition to this format.\n+\n+Specification\n+=============\n+\n+Parsers\n+-------\n+\n+An extended JSON parser (hereafter just \"parser\") is a tool that transforms an\n+extended JSON string into another representation, such as BSON or a\n+language-specific data structure. A parser MUST accept all strings in the\n+canonical extended JSON format. A parser MAY also accept strings that adhere to\n+other formats, such as historical extended JSON formats emitted by old versions\n+of mongoexport. A parser SHOULD support at least 200 levels of nesting in an\n+extended JSON document but MAY set other limits on strings it can accept as\n+defined in `section 9`_ of the `JSON specification`_.\n+\n+.. _section 9: https://tools.ietf.org/html/rfc7159#section-9\n+\n+A parser can generally distinguish JSON representations of BSON types by the\n+presence of a key that starts with the ``$`` symbol. For example: ``{\"$symbol\":\n+\"banana\"}``. However, not every key that starts with $ will indicate the element\n+represents some BSON value. If such key names of the element do not exactly\n+match those of a format given in the `Canonical Format Table`_, the element MUST\n+be interpreted as an ordinary JSON element. If the key names match, but the\n+element cannot be parsed for other reasons (e.g. ``{\"$timestamp\": \"-4\"}``), then\n+the parser MUST report an error.\n+\n+When parsing an extended JSON document, parsers MUST NOT consider key ordering\n+as having significance. For example, the document ``{\"$code\": \"function(){}\",\n+\"$scope\": {}}`` must be considered identical to ``{\"$scope\": {}, \"$code\":\n+\"function(){}\"}``.\n+\n+.. _JSON specification: https://tools.ietf.org/html/rfc7159\n+\n+Generators\n+----------\n+\n+An extended JSON generator (hereafter just \"generator\") produces strings in\n+extended JSON. A generator MUST be able to produce strings that conform strictly\n+to the canonical extended JSON format. Such generators SHOULD produce such\n+strings by default. If a generator does not produce strings in the canonical\n+format by default, then that generator MUST be configurable to use the canonical\n+format. A generator MAY be capable of exporting strings that adhere to other\n+formats, such as historical extended JSON formats emitted by old versions of\n+mongoexport. A generator MUST support at least 100 levels of nesting in a BSON\n+document.\n+\n+Transforming BSON\n+.................\n+\n+When transforming a BSON value into extended JSON text, a generator MUST use the\n+corresponding format for the BSON type given in the `Canonical Format\n+Table`_. When transforming a BSON document into extended JSON text, a generator\n+SHOULD emit the JSON keys and values in the same order as given in the BSON\n+document.\n+\n+Transforming Language-Specific Data Structures\n+..............................................\n+\n+When transforming a language-specific data structure, such as one emitted by a\n+BSON parser, into extended JSON, a generator MUST emit the extended JSON form\n+for the BSON type corresponding to the type of the data structure. For example,\n+a Python ``datetime`` object must be represented the same as a BSON datetime\n+type.","path":"source/extended-json.rst","position":null,"original_position":108,"commit_id":"abba4296a3c9f67fb11b5a8a1224b4128ac60fd5","original_commit_id":"a09c98a3e1258a694e76f2fef21c523db7f36349","user":{"login":"llvtt","id":5168837,"avatar_url":"https://avatars.githubusercontent.com/u/5168837?v=3","gravatar_id":"","url":"https://api.github.com/users/llvtt","html_url":"https://github.com/llvtt","followers_url":"https://api.github.com/users/llvtt/followers","following_url":"https://api.github.com/users/llvtt/following{/other_user}","gists_url":"https://api.github.com/users/llvtt/gists{/gist_id}","starred_url":"https://api.github.com/users/llvtt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/llvtt/subscriptions","organizations_url":"https://api.github.com/users/llvtt/orgs","repos_url":"https://api.github.com/users/llvtt/repos","events_url":"https://api.github.com/users/llvtt/events{/privacy}","received_events_url":"https://api.github.com/users/llvtt/received_events","type":"User","site_admin":false},"body":"Done.","created_at":"2017-01-26T18:44:39Z","updated_at":"2017-01-26T19:04:32Z","html_url":"https://github.com/mongodb/specifications/pull/131#discussion_r98061714","pull_request_url":"https://api.github.com/repos/mongodb/specifications/pulls/131","_links":{"self":{"href":"https://api.github.com/repos/mongodb/specifications/pulls/comments/98061714"},"html":{"href":"https://github.com/mongodb/specifications/pull/131#discussion_r98061714"},"pull_request":{"href":"https://api.github.com/repos/mongodb/specifications/pulls/131"}}},"pull_request":{"url":"https://api.github.com/repos/mongodb/specifications/pulls/131","id":103195167,"html_url":"https://github.com/mongodb/specifications/pull/131","diff_url":"https://github.com/mongodb/specifications/pull/131.diff","patch_url":"https://github.com/mongodb/specifications/pull/131.patch","issue_url":"https://api.github.com/repos/mongodb/specifications/issues/131","number":131,"state":"open","locked":false,"title":"SPEC-587 - Extended JSON","user":{"login":"llvtt","id":5168837,"avatar_url":"https://avatars.githubusercontent.com/u/5168837?v=3","gravatar_id":"","url":"https://api.github.com/users/llvtt","html_url":"https://github.com/llvtt","followers_url":"https://api.github.com/users/llvtt/followers","following_url":"https://api.github.com/users/llvtt/following{/other_user}","gists_url":"https://api.github.com/users/llvtt/gists{/gist_id}","starred_url":"https://api.github.com/users/llvtt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/llvtt/subscriptions","organizations_url":"https://api.github.com/users/llvtt/orgs","repos_url":"https://api.github.com/users/llvtt/repos","events_url":"https://api.github.com/users/llvtt/events{/privacy}","received_events_url":"https://api.github.com/users/llvtt/received_events","type":"User","site_admin":false},"body":"","created_at":"2017-01-25T20:15:02Z","updated_at":"2017-01-26T19:04:32Z","closed_at":null,"merged_at":null,"merge_commit_sha":"12d25fda68aa9f284839641245d3bcc27aaee338","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/mongodb/specifications/pulls/131/commits","review_comments_url":"https://api.github.com/repos/mongodb/specifications/pulls/131/comments","review_comment_url":"https://api.github.com/repos/mongodb/specifications/pulls/comments{/number}","comments_url":"https://api.github.com/repos/mongodb/specifications/issues/131/comments","statuses_url":"https://api.github.com/repos/mongodb/specifications/statuses/abba4296a3c9f67fb11b5a8a1224b4128ac60fd5","head":{"label":"llvtt:extjson-specification","ref":"extjson-specification","sha":"abba4296a3c9f67fb11b5a8a1224b4128ac60fd5","user":{"login":"llvtt","id":5168837,"avatar_url":"https://avatars.githubusercontent.com/u/5168837?v=3","gravatar_id":"","url":"https://api.github.com/users/llvtt","html_url":"https://github.com/llvtt","followers_url":"https://api.github.com/users/llvtt/followers","following_url":"https://api.github.com/users/llvtt/following{/other_user}","gists_url":"https://api.github.com/users/llvtt/gists{/gist_id}","starred_url":"https://api.github.com/users/llvtt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/llvtt/subscriptions","organizations_url":"https://api.github.com/users/llvtt/orgs","repos_url":"https://api.github.com/users/llvtt/repos","events_url":"https://api.github.com/users/llvtt/events{/privacy}","received_events_url":"https://api.github.com/users/llvtt/received_events","type":"User","site_admin":false},"repo":{"id":79847910,"name":"specifications","full_name":"llvtt/specifications","owner":{"login":"llvtt","id":5168837,"avatar_url":"https://avatars.githubusercontent.com/u/5168837?v=3","gravatar_id":"","url":"https://api.github.com/users/llvtt","html_url":"https://github.com/llvtt","followers_url":"https://api.github.com/users/llvtt/followers","following_url":"https://api.github.com/users/llvtt/following{/other_user}","gists_url":"https://api.github.com/users/llvtt/gists{/gist_id}","starred_url":"https://api.github.com/users/llvtt/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/llvtt/subscriptions","organizations_url":"https://api.github.com/users/llvtt/orgs","repos_url":"https://api.github.com/users/llvtt/repos","events_url":"https://api.github.com/users/llvtt/events{/privacy}","received_events_url":"https://api.github.com/users/llvtt/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/llvtt/specifications","description":"Specifications related to MongoDB","fork":true,"url":"https://api.github.com/repos/llvtt/specifications","forks_url":"https://api.github.com/repos/llvtt/specifications/forks","keys_url":"https://api.github.com/repos/llvtt/specifications/keys{/key_id}","collaborators_url":"https://api.github.com/repos/llvtt/specifications/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/llvtt/specifications/teams","hooks_url":"https://api.github.com/repos/llvtt/specifications/hooks","issue_events_url":"https://api.github.com/repos/llvtt/specifications/issues/events{/number}","events_url":"https://api.github.com/repos/llvtt/specifications/events","assignees_url":"https://api.github.com/repos/llvtt/specifications/assignees{/user}","branches_url":"https://api.github.com/repos/llvtt/specifications/branches{/branch}","tags_url":"https://api.github.com/repos/llvtt/specifications/tags","blobs_url":"https://api.github.com/repos/llvtt/specifications/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/llvtt/specifications/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/llvtt/specifications/git/refs{/sha}","trees_url":"https://api.github.com/repos/llvtt/specifications/git/trees{/sha}","statuses_url":"https://api.github.com/repos/llvtt/specifications/statuses/{sha}","languages_url":"https://api.github.com/repos/llvtt/specifications/languages","stargazers_url":"https://api.github.com/repos/llvtt/specifications/stargazers","contributors_url":"https://api.github.com/repos/llvtt/specifications/contributors","subscribers_url":"https://api.github.com/repos/llvtt/specifications/subscribers","subscription_url":"https://api.github.com/repos/llvtt/specifications/subscription","commits_url":"https://api.github.com/repos/llvtt/specifications/commits{/sha}","git_commits_url":"https://api.github.com/repos/llvtt/specifications/git/commits{/sha}","comments_url":"https://api.github.com/repos/llvtt/specifications/comments{/number}","issue_comment_url":"https://api.github.com/repos/llvtt/specifications/issues/comments{/number}","contents_url":"https://api.github.com/repos/llvtt/specifications/contents/{+path}","compare_url":"https://api.github.com/repos/llvtt/specifications/compare/{base}...{head}","merges_url":"https://api.github.com/repos/llvtt/specifications/merges","archive_url":"https://api.github.com/repos/llvtt/specifications/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/llvtt/specifications/downloads","issues_url":"https://api.github.com/repos/llvtt/specifications/issues{/number}","pulls_url":"https://api.github.com/repos/llvtt/specifications/pulls{/number}","milestones_url":"https://api.github.com/repos/llvtt/specifications/milestones{/number}","notifications_url":"https://api.github.com/repos/llvtt/specifications/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/llvtt/specifications/labels{/name}","releases_url":"https://api.github.com/repos/llvtt/specifications/releases{/id}","deployments_url":"https://api.github.com/repos/llvtt/specifications/deployments","created_at":"2017-01-23T21:04:11Z","updated_at":"2017-01-23T21:04:14Z","pushed_at":"2017-01-26T18:39:54Z","git_url":"git://github.com/llvtt/specifications.git","ssh_url":"git@github.com:llvtt/specifications.git","clone_url":"https://github.com/llvtt/specifications.git","svn_url":"https://github.com/llvtt/specifications","homepage":null,"size":920,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"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":"master"}},"base":{"label":"mongodb:master","ref":"master","sha":"e36319b395707d3da5447c77a65f442e98f61774","user":{"login":"mongodb","id":45120,"avatar_url":"https://avatars.githubusercontent.com/u/45120?v=3","gravatar_id":"","url":"https://api.github.com/users/mongodb","html_url":"https://github.com/mongodb","followers_url":"https://api.github.com/users/mongodb/followers","following_url":"https://api.github.com/users/mongodb/following{/other_user}","gists_url":"https://api.github.com/users/mongodb/gists{/gist_id}","starred_url":"https://api.github.com/users/mongodb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mongodb/subscriptions","organizations_url":"https://api.github.com/users/mongodb/orgs","repos_url":"https://api.github.com/users/mongodb/repos","events_url":"https://api.github.com/users/mongodb/events{/privacy}","received_events_url":"https://api.github.com/users/mongodb/received_events","type":"Organization","site_admin":false},"repo":{"id":19244865,"name":"specifications","full_name":"mongodb/specifications","owner":{"login":"mongodb","id":45120,"avatar_url":"https://avatars.githubusercontent.com/u/45120?v=3","gravatar_id":"","url":"https://api.github.com/users/mongodb","html_url":"https://github.com/mongodb","followers_url":"https://api.github.com/users/mongodb/followers","following_url":"https://api.github.com/users/mongodb/following{/other_user}","gists_url":"https://api.github.com/users/mongodb/gists{/gist_id}","starred_url":"https://api.github.com/users/mongodb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mongodb/subscriptions","organizations_url":"https://api.github.com/users/mongodb/orgs","repos_url":"https://api.github.com/users/mongodb/repos","events_url":"https://api.github.com/users/mongodb/events{/privacy}","received_events_url":"https://api.github.com/users/mongodb/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/mongodb/specifications","description":"Specifications related to MongoDB","fork":false,"url":"https://api.github.com/repos/mongodb/specifications","forks_url":"https://api.github.com/repos/mongodb/specifications/forks","keys_url":"https://api.github.com/repos/mongodb/specifications/keys{/key_id}","collaborators_url":"https://api.github.com/repos/mongodb/specifications/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/mongodb/specifications/teams","hooks_url":"https://api.github.com/repos/mongodb/specifications/hooks","issue_events_url":"https://api.github.com/repos/mongodb/specifications/issues/events{/number}","events_url":"https://api.github.com/repos/mongodb/specifications/events","assignees_url":"https://api.github.com/repos/mongodb/specifications/assignees{/user}","branches_url":"https://api.github.com/repos/mongodb/specifications/branches{/branch}","tags_url":"https://api.github.com/repos/mongodb/specifications/tags","blobs_url":"https://api.github.com/repos/mongodb/specifications/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/mongodb/specifications/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/mongodb/specifications/git/refs{/sha}","trees_url":"https://api.github.com/repos/mongodb/specifications/git/trees{/sha}","statuses_url":"https://api.github.com/repos/mongodb/specifications/statuses/{sha}","languages_url":"https://api.github.com/repos/mongodb/specifications/languages","stargazers_url":"https://api.github.com/repos/mongodb/specifications/stargazers","contributors_url":"https://api.github.com/repos/mongodb/specifications/contributors","subscribers_url":"https://api.github.com/repos/mongodb/specifications/subscribers","subscription_url":"https://api.github.com/repos/mongodb/specifications/subscription","commits_url":"https://api.github.com/repos/mongodb/specifications/commits{/sha}","git_commits_url":"https://api.github.com/repos/mongodb/specifications/git/commits{/sha}","comments_url":"https://api.github.com/repos/mongodb/specifications/comments{/number}","issue_comment_url":"https://api.github.com/repos/mongodb/specifications/issues/comments{/number}","contents_url":"https://api.github.com/repos/mongodb/specifications/contents/{+path}","compare_url":"https://api.github.com/repos/mongodb/specifications/compare/{base}...{head}","merges_url":"https://api.github.com/repos/mongodb/specifications/merges","archive_url":"https://api.github.com/repos/mongodb/specifications/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/mongodb/specifications/downloads","issues_url":"https://api.github.com/repos/mongodb/specifications/issues{/number}","pulls_url":"https://api.github.com/repos/mongodb/specifications/pulls{/number}","milestones_url":"https://api.github.com/repos/mongodb/specifications/milestones{/number}","notifications_url":"https://api.github.com/repos/mongodb/specifications/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/mongodb/specifications/labels{/name}","releases_url":"https://api.github.com/repos/mongodb/specifications/releases{/id}","deployments_url":"https://api.github.com/repos/mongodb/specifications/deployments","created_at":"2014-04-28T16:04:56Z","updated_at":"2017-01-25T22:22:30Z","pushed_at":"2017-01-26T18:39:55Z","git_url":"git://github.com/mongodb/specifications.git","ssh_url":"git@github.com:mongodb/specifications.git","clone_url":"https://github.com/mongodb/specifications.git","svn_url":"https://github.com/mongodb/specifications","homepage":null,"size":918,"stargazers_count":63,"watchers_count":63,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":34,"mirror_url":null,"open_issues_count":3,"forks":34,"open_issues":3,"watchers":63,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/mongodb/specifications/pulls/131"},"html":{"href":"https://github.com/mongodb/specifications/pull/131"},"issue":{"href":"https://api.github.com/repos/mongodb/specifications/issues/131"},"comments":{"href":"https://api.github.com/repos/mongodb/specifications/issues/131/comments"},"review_comments":{"href":"https://api.github.com/repos/mongodb/specifications/pulls/131/comments"},"review_comment":{"href":"https://api.github.com/repos/mongodb/specifications/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/mongodb/specifications/pulls/131/commits"},"statuses":{"href":"https://api.github.com/repos/mongodb/specifications/statuses/abba4296a3c9f67fb11b5a8a1224b4128ac60fd5"}}}}
{"actor":{"display_login":"llvtt"}}