[DOCS-11478] Updated Extended JSON docs to address v2 Created: 21/Mar/18  Updated: 30/Oct/23  Resolved: 12/Aug/19

Status: Closed
Project: Documentation
Component/s: manual, Server
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Bug Priority: Major - P3
Reporter: David Golden Assignee: Kay Kim (Inactive)
Resolution: Fixed Votes: 0
Labels: collector-298ba4e7
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

Issue Links:
Documented
documents TOOLS-2276 dump/export/files query should use ex... Closed
Duplicate
is duplicated by DOCS-12854 Document mongoimport --legacy Closed
Related
related to GODRIVER-289 Extended JSON parser expects $binary ... Closed
related to DOCS-12939 Docs for TOOLS-2276: dump/export/file... Closed
related to JAVA-3268 Bson JsonReader failed to parse the d... Closed
Participants:
Days since reply: 4 years, 26 weeks, 2 days ago
Epic Link: DOCSP-1769
Story Points: 2

 Description   

Scope

The manual page on Extended JSON needs to be updated to explain the difference between "v1" and "v2" Extended JSON.

Some drivers already use v2 and tools will be updated to do so when they are converted to the new in-house Go driver. We need to find a way to let users know about the different forms they might be seeing and about the transition.

I'm open to suggestions for the right way to do that.

Thanks!

drivers that use v2

  • C
  • C++
  • Go
  • Java
  • Node
  • Perl
  • PHPC
  • Python
  • Scala

From DOCSP-5366:

  • mongodump produces collection metadata in canonical extended JSON; mongorestore expects collection metadata in v2 extended JSON, not legacy (we only support restoring from the same version of the tools that were used to dump with, but someone who tries to restore old data may still be surprised)
  • Extended JSON v2 is used instead of the legacy format:
    • bsondump outputs canonical extended JSON
    • mongoexport outputs relaxed extended JSON by default or canonical by request using a new flag, --jsonFormat
    • mongoimport consumes relaxed/canonical unless the new --legacy flag is used
    • The extended JSON docs should also be updated to reflect v2 and not the legacy format

From DOCS-12939:

  • dump/export/files query should use extJSON v2 and ordered BSON

Out of Scope

  • the v1 extended json docs probably needs update both in content and presentation, but will not be tackled in this ticket
  • the use of bsontype label on these pages + bson type page + mention of mongo shell helpers – also needs overhaul, but not for this ticket.


 Comments   
Comment by Githook User [ 12/Aug/19 ]

Author:

{'name': 'Kay Kim', 'username': 'kay-kim', 'email': 'kay.kim@10gen.com'}

Message: DOCS-11478: extended json v2
Branch: master
https://github.com/mongodb/docs/commit/24c8ff60d4a67b9116158c7d99826159dd7091b0

Comment by Jeffrey Yemin [ 06/May/19 ]

Another bug report (JAVA-3268) partially caused by confusion over the current extended JSON documentation. Any chance to bump the priority on this?

Comment by David Golden [ 04/Apr/18 ]

That seems like a reasonable approach. That said, "v1" wasn't ever really consistent between server versions, tools versions, drivers, etc. so that probably needs a bit of extra caveat.

Comment by Shannon Bradshaw (Inactive) [ 04/Apr/18 ]

david.golden, it seems reasonable to me to have a page for v1 and a separate page for v2.
I suggest we also include a table in the Extended JSON docs that summarizes which drivers use v1 vs. v2.

Will the above address the issues you've identified here?

Generated at Thu Feb 08 08:02:54 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.