37

The blog published an article called A beginner’s guide to JSON, the data format for the internet in which it talks about the JavaScript Object Notation (JSON) serialisation format. It shows examples such as

The basic structure is built from one or more keys and values:

{
  key: value
}

and

For example, the following is valid JSON:

{
  key: "String",
  Number: 1,
  array: [1,2,3], 
  nested: {
        literals: true
  }   
}

Among other ones. However, the only example of valid JSON in the entire article is this one:

{
  "hello": "world"
}

Per the standard keys have to be enclosed in double quotes. If they are not, it is invalid.

For reference:

Please fix the article at the very least to have valid JSON since it talks about JSON.

Improve this question
3
  • 6
    Also, the article gives the false impression that key-value-pairs is the only possible value for a valid JSON, which isn't true. Any JSON Value is a valid JSON Text (according to RFC 8259 and ECMA 404), so an array ([1, 2, 3]) or even a int/string/boolean literal (42, or "foo" or true) would be a valid JSON. Just because key-value-pairs is the most common choice, it doesn't mean is the only possibility.
    – hkotsubo
    Commented Jun 2, 2022 at 18:43
  • 6
    (And all of this information is readily available and better presented with linked references to further reading resources on MDN)
    – Kevin B
    Commented Jun 2, 2022 at 19:24
  • 10
    sigh These seem like fairly typical types of issues with the blog. It's seemed that there being substantial issues with blog articles is normal, rather than an exception. Unfortunately, I've seen way more than enough issues with things I'm quite familiar with on the blog for me to realize that I just can't trust the information in the blog to be accurate, certainly not enough for me to trust learning from the blog about something I don't already know. Since I can't trust the blog, I find it's better to just ignore it.
    – Makyen
    Commented Jun 2, 2022 at 20:25

3 Answers 3

Reset to default
19

I appreciate the feedback and corrections on the post, as always. I rely on my writers to be technically accurate, but I'm glad I can count on the community to be the second line of defense. I've made most of the edits suggested here.

Improve this answer
6
  • 7
    It's a tough crowd, the slightest technical inaccuracy will get nitpicked and you're writing for an audience mixing lifelong experts with total beginners. The editorial criteria in such circumstances can't be easy.
    – bad_coder
    Commented Jun 2, 2022 at 21:57
  • 2
    @OlegValteriswithUkraine -- I added a line that says "JSON doesn’t have to have only key:value pairs; the specification allows to any value to be passed without a key. However, almost all of the JSON objects that you see will contain key:value pairs." Does that cover it or is there something still missing?
    – Ryan Donovan Staff
    Commented Jun 3, 2022 at 15:53
  • 3
    @bad_coder It is a tough crowd, sure, but I appreciate the folks here keeping my details in line. I just wish some of these lifelong experts would pitch me some articles ;)
    – Ryan Donovan Staff
    Commented Jun 3, 2022 at 15:55
  • 1
    Yup, @RyanDonovan, I noticed (thanks for following up anyways) :) Looks better now. However, if you ask me, I would change that to something like "A JSON value can be either an object (unordered set of key-value pairs), an array (ordered collection of values), a number, string, true, false, or null. One of the most common, though, is the object structure". This would both conform to the spec and be educative as to what JSON actually is (a link to the spec would make the article even better).
    – Oleg Valter is with Ukraine
    Commented Jun 3, 2022 at 16:30
  • 2
    eh, I dunno. I'm not a writer, and most of the useful articles the blog has pushed, particularly in the javascript realm... are ones that are already done very well elsewhere. I don't support spreading this kind of content across more platforms, particularly in the form of a blog post that can't be collaboratively edited when things change.
    – Kevin B
    Commented Jun 3, 2022 at 17:16
  • @RyanDonovan there appear to be some issues with the latest blog post: meta.stackexchange.com/questions/380436/…
    – Luuklag
    Commented Jul 15, 2022 at 7:13
23

Other issues:

  • Referring to "serialized JSON—JST and JWT" doesn't really make sense. JSON is a serialization format. All JSON is, by definition, serialized. You can serialize it again (by base64-encoding it), but grouping them under a special category of "serialized JSON" isn't really accurate.

  • It's also somewhat confusing to treat JWS/JWT as somehow relevant to a beginner's understanding of JSON. Most applications of JSON will never use these.

  • The post repeatedly talks up how "lightweight" and "small" JSON is as one of its big advantages. That's only true if the only other serialization format you've ever heard of is XML. JSON is generally considered a relatively heavyweight format compared to binary wire protocols like Protocol Buffers or FlatBuffers (disclosure: both created by my employer), trading size for human-readability.

  • "XML is part of a major API standard, Simple Object Access Protocol (SOAP)." makes it sound like the SOAP standard defines XML.

  • The graph in the middle has the alt text set to an empty string, treating it as a purely decorative image with no informational content.

  • "Using  JSON in API calls" has two spaces between "Using" and "JSON".

  • data[“key”] has smart quotes.

Improve this answer
1
  • 2
    Also, it'd be good to mention that all JSON is valid YAML, but that's not a problem so much as something I'd add.
    – Ryan M
    Commented Jun 2, 2022 at 16:12
16

There are still some issues:

  • "the key is an alphanumeric string" — The key can be any string, it doesn't need to be alphanumeric
  • "it really took off as the major format after its first standards were published in 2013" — This is presumably referring to ECMA-404, which was published in October 2013. But the actual first standard was RFC 4627, which was published in July 2006. And the causality is backwards here: JSON taking off led to standards being created, not the other way around.
  • Minor nitpick, but foo{ in the GraphQL example would normally be written as foo {, which looks nicer. Same with "foo":{ (which should be "foo": {) in the result.
  • Indentation is really inconsistent throughout the post: the first snippet is 2 spaces, the next one mixes two spaces and tabs, the next two are back to two spaces, the next one is 3 spaces
Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .