[Updated] 10 questions to ask and answer before designing JSON

Hi Folks,

I added an 11’th question to the list:

-------------------------------------------------------

11. Merge JSON Objects: Do you need to integrate/merge JSON from different sources? If yes, it will be important to address the real possibility of conflicting JSON keys.

-------------------------------------------------------

I also added a recommendation:

-------------------------------------------------------

Recommendation: If you are using JSON-LD, then don't use JSON Schema; if you are using JSON Schema, then don't use JSON-LD. Here's why: JSON-LD requires a bunch of datatype information be injected into JSON instances. For example, "@id" is used to denote that the value is a URL. Here's an example from the JSON-LD specification:

{
  "http://schema.org/homepage": { "@id": "http://manu.sporny.org/" }
}

The '@id' keyword means 'This value is an identifier that is a URL'.

So datatype information is encoded into the JSON instance.

If JSON Schema is used, there is no need to encode datatype information into JSON instances; datatype information is specified in a schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "http://schema.org/homepage": {
            "type": "string",
            "format": "uri"
        }
    }
}

JSON Schema is a very powerful constraint language. It has much greater power for specifying constraints than JSON-LD. If constraint checking is important to you, then use JSON Schema. If creating an interlinked web of resources (i.e., leverage RDF) is important to you, then use JSON-LD.

-------------------------------------------------------

I am eager to hear your thoughts on this recommendation.

Below is the complete list of questions, plus the recommendation and references.

------------------------------------------------------------------------------

      Get Answers to These Questions before Creating JSON

------------------------------------------------------------------------------

1. Interconvertibility: Is it important to be able to convert from XML to JSON and vice versa?

2. Emulate XML: Is it important that the JSON emulate the XML; i.e., is it important that there is a one-to-one correspondence between the XML and the JSON?

3. What's the Starting Point: Suppose you have a data model and you've serialized the data model to an XML encoding. Do you want to serialize the data model to a JSON encoding? Or, do you want to translate the XML encoding to JSON? In other words, what is your starting point for generating JSON: the data model or an XML encoding?

4. Processing Language: What programming language will you use to process the JSON?

5. Multiple Languages: Will the JSON be processed by multiple applications? Do all the applications use the same programming language or are various languages used?

6. Generic JSON Parser: Is it acceptable to process JSON with a general-purpose JSON parser (e.g., GSON)? A generic JSON parser understands JSON objects, arrays, strings, number, true, false, and null, but it doesn't understand "This special JSON object key indicates that the value is a URL" and "That special JSON object key indicates that the value is a datetime" and so forth.

7. Standards Organization: Is it important for you to use a W3C (ISO, IETF, etc.) standard when designing the JSON, e.g., the W3C JSON-LD standard.

8. Leverage RDF Tools: Is it important that the JSON is suitable for use with RDF and can be processed by the suite of RDF tools such as SPARQL?

9. JSON Schema: Will you validate your JSON against a JSON Schema?

10. Significantly Different: Is it acceptable for the JSON design to be significantly different than the XML design?

11. Merge JSON Objects: Do you need to integrate/merge JSON from different sources? If yes, it will be important to address the real possibility of conflicting JSON keys.

Recommendation: If you are using JSON-LD, then don't use JSON Schema; if you are using JSON Schema, then don't use JSON-LD. Here's why: JSON-LD requires a bunch of datatype information be injected into JSON instances. For example, "@id" is used to denote that the value is a URL. Here's an example from the JSON-LD specification:

{
  "http://schema.org/homepage": { "@id": "http://manu.sporny.org/" }
}

The '@id' keyword means 'This value is an identifier that is a URL'.

So datatype information is encoded into the JSON instance.

If JSON Schema is used, there is no need to encode datatype information into JSON instances; datatype information is specified in a schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "http://schema.org/homepage": {
            "type": "string",
            "format": "uri"
        }
    }
}

JSON Schema is a very powerful constraint language. It has much greater power for specifying constraints than JSON-LD. If constraint checking is important to you, then use JSON Schema. If creating an interlinked web of resources (i.e., leverage RDF) is important to you, then use JSON-LD.

References:

GSON: http://www.studytrails.com/java/json/java-google-json-introduction.jsp 

JSON Schema: http://json-schema.org/latest/json-schema-core.html