MySQL Bugs: #86875: Inconsistence in docs about what ¨basic datatype' JSON is

Bug #86875	Inconsistence in docs about what ¨basic datatype' JSON is
Submitted:	29 Jun 2017 18:15	Modified:	4 Aug 2017 9:06
Reporter:	Peter Laursen (Basic Quality Contributor)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.7+	OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
I find some inconsistence in docs about what ¨basic datatype' or 'datatype category' JSON is - a string type or not. 
 
1) Here https://dev.mysql.com/doc/refman/5.7/en/data-types.html, JSON datatype is listed a separate datatype category. 
2)  However storage requirements for JSON are listed under string types here https://dev.mysql.com/doc/refman/5.7/en/storage-requirements.html - but (strangely) omitted in the table on top of the paragraph on the same page identified by URL https://dev.mysql.com/doc/refman/5.7/en/storage-requirements.html#data-types-storage-reqs-....  
3) And further here https://dev.mysql.com/doc/refman/5.7/en/json.html#json-values it is described that JSON data ared stored using utf8mb4 character set. Encoding/charset would usaully apply to (non-binary) strings and no other datatypes (what I also believe docs are clear about elsewhere). 

How to repeat:
See above

Suggested fix:
Either JSON is a string type or not. And docs should be consistent with that all over. I think that JSON should consistently be described as a non-binary/encoded string with specific properties (ie: utf8mb4 is enforced no matter default server character set and no opther character set can be specified by user for a JSON column, as well as being a datatype having specific storage requirements (and please explain reasons for same), and what else is specific for JSON and different between char/varchar/text and JSON). 

It basically requires some rearrangements of various text-blocks (that are mostly and basically OK) describing JSON as well as removal of JSON as a separate datatype category in the first link I provided here. But also a little bit of elaboration about the particularity of JSON as compared to other non-binary string types - and the rationale for same.

Hello Peter,

Thank you for the report!

Thanks,
Umesh

There's nothing inconsistent with the documentation: MySQL has a JSON data type, whose string representation in MySQL uses utf8mb4.

Since JSON documents are represented as strings, it appeared to make sense to place the 2 paragraphs dealing with JSON storage requirements in the section covering string type storage requirements, and was not intended to invite question about matters already definitively covered elsewhere.

Nevertheless, for the removal of doubt, I've moved these paragraphs into their own JSON Storage Requirements section, which should appear online shortly.

Closed in mysqldoc rev 53269.