JSON Schema Standard

Columbia university has chosen JSON as standard representation for API and web services. Where needed we will also provide response as XML, but JSON is preferred, specifically following the {json:api} specification which is relatively lightweight and, the json-schema.org schema specification. 

JSON

JSON is an open standard format that uses human-readable text to transmit data objects consisting of attribute–value pairs. It is the most common data format used for browser/server communication primarily because it maps directly to JavaScript objects (JSON stands for JavaScript Object Notation), largely replacing XML which is used by AJAX.

YAML

YAML (Yet Another Markup Language) is a “is a human friendly data serialization standard for all programming languages.” YAML markup maps easily to JSON in a manner similar to XML markup mapping (not so easily) via AJAX.

JSON Schema Specifications

• json-schema.org (Mediatype for describing JSON)

  • RFC draft: JSON Schema: A Media Type for Describing JSON Documents (Expires: October 17, 2017)

JSON Schema Standard for Columbia

In addition to data bits which are ??, following self-describing meta-data must be provide with the every JSON response

TODO: More clearly explain relationship of {json:api} and json-schema.

Sample JSON Response

{
	"schema": "http://json-schema.org/schema#",
	"meta": {
                       "resourceType": "People",
                       "description": "People entity API",
                       "format": "jsonschema",
                       "version": "v##",
                       "Domain": "Identity Management",
                       "Release Date" : "01/02/2016",
                       "location": "https://api.columbia.edu/v1/People/ss1234"
		}
}

JSON Schema for above response

 {
   "$schema": "http://json-schema.org/draft-04/schema#",
   "id": "http://jsonschema.net",
   "type": "object",
   "properties": {
     "meta": {
       "id": "http://jsonschema.net/meta",
       "type": "object",
       "properties": {
         "resourceType": {
           "id": "http://jsonschema.net/meta/resourceType",
           "type": "string"
         },
         "description": {
           "id": "http://jsonschema.net/meta/description",
           "type": "string"
         },
         "format": {
           "id": "http://jsonschema.net/meta/format",
           "type": "string"
         },
         "version": {
           "id": "http://jsonschema.net/meta/version",
           "type": "string"
         },
         "Domain": {
           "id": "http://jsonschema.net/meta/Domain",
           "type": "string"
         },
         "Release Date": {
           "id": "http://jsonschema.net/meta/Release Date",
           "type": "string"
         },
         "location": {
           "id": "http://jsonschema.net/meta/location",
           "type": "string"
         }
       }
     }
   },
   "required": [
     "$schema",
     "meta"
   ]
 } 

• Understanding JSON Schema

• Self describing Schemas

• Elegent Schemas