C.3  
 

JSON Data Interchange Format

This appendix contains examples of yosokumo protocol documents formatted in the JSON DIF. The canonical specification for the documents is given in ASN.1 in Appendix C.1. In general, the following conventions apply:

  1. JSON strings in protocol documents contain only UTF-8 characters.
  2. Each ASN.1 production and subproduction is identified by a JSON pair.
  3. SET OF or SEQUENCE OF attributes that may be repeated are represented as JSON arrays.
  4. When an attribute takes one of a set of enumerated values, the value in the JSON pair is set to a string containing the mnemonic value from the canonical list, not the numeric value.
  5. Numeric values must be formatted in a JSON compliant manner appropriate for their type; JSON does not permit a leading '+' sign for positive numbers.
  6. All time values are RFC 3339 formatted as 'YYYY-MM-DDThh:mm:ss.nnn', where 'nnn' represents milliseconds.
  7. When a 'null' value is permitted by the specification, the JSON pair is set to "string":null.

Normally, to reduce bandwidth usage, a JSON document contains no unecessary whitespace or control characters. For example, a study document is formatted:

{"study":{"study_identifier":"FEDCBA9876543210","study_name":"Trial study","type":"class","status":"running","location":"http://yosokumo.ws/study.FEDCBA9876543210","owner":{"user_identifier":"AAAABBBBCCCCDDDD","user_name":"User One" },"table":{"location":"http://yosokumo.ws/study.FEDCBA9876543210/table" },"model":{"location":"http://yosokumo.ws/study.FEDCBA9876543210/model"},"panel":{"location":"http://yosokumo.ws/study.FEDCBA9876543210/panel"},"roster":{"location":"http://yosokumo.ws/study.FEDCBA9876543210/roster"}}}

Below, documents are formatted for exposition with linebreaks and tabs that would not ordinarily appear. In addition, the documents here generally are shown with all attributes present. Consult the canonical specification for information about optional attributes and permitted values; consult the main text for contexts in which attributes are optional (or required) and the meaning of the permitted values.

A catalog document:

{
	"catalog" :
	{
		"user_identifier":"AAAABBBBCCCCDDDD" ,
		"user_name":"User One" , 
		"location":"http://yosokumo.ws/user.AAAABBBBCCCCDDDD/catalog" ,
		"study" :
		[
			{
				"study_identifier":"FEDCBA9876543210" ,
				"study_name":"Trial study" ,
				"type":"class" , 
				"status":"running" , 
				"visibility":"public" , 
				"location":"http://yosokumo.ws/study.FEDCBA9876543210" ,
				"owner" : { "user_identifier":"AAAABBBBCCCCDDDD" , "user_name":"User One" } ,
				"table" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/table" } ,
				"model" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/model" } ,
				"panel" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/panel" } ,
				"roster" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/roster" }
			}
			,
			{
				"study_identifier":"ABCDEF0123456789" ,
				"study_name":"Panel Study" ,
				"type":"number" , 
				"status":"paused" , 
				"visibility":"private" , 
				"location":"http://yosokumo.ws/study.ABCDEF0123456789" ,
				"owner" : { "user_identifier":"1111222233334444" , "user_name":"User Two" } ,
				"table" : { "location":"http://yosokumo.ws/study.ABCDEF0123456789/table" } ,
				"model" : { "location":"http://yosokumo.ws/study.ABCDEF0123456789/model" } ,
				"panel" : { "location":"http://yosokumo.ws/study.ABCDEF0123456789/panel" } ,
				"roster" : { "location":"http://yosokumo.ws/study.ABCDEF0123456789/roster" }
			}
		]
	}
}

A standalone study document:

{
	"study" :
	{
		"study_identifier":"FEDCBA9876543210" ,
		"study_name":"Trial study" ,
		"type":"class" , 
		"status":"running" , 
		"visibility":"public" , 
		"location":"http://yosokumo.ws/study.FEDCBA9876543210" ,
		"owner" : { "user_identifier":"AAAABBBBCCCCDDDD" , "user_name":"User One" } ,
		"table" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/table" } ,
		"model" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/model" } ,
		"panel" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/panel" } ,
		"roster" : { "location":"http://yosokumo.ws/study.FEDCBA9876543210/roster" }
	}
}

A roster document:

{
	"roster" : 
	{
		"study_identifier" : "ABCDEF0123456789" ,
		"study_name" : "Panel Study" ,
		"location":"http://yosokumo.ws/study.ABCDEF0123456789/roster" ,
		"role" :
		[
			{
				"location":"http://yosokumo.ws/user.1111222233334444/study.ABCDEF0123456789/role" ,
				"roleholder" :
				{
					"user_identifier":"1111222233334444" ,
					"user_name":"User Two"
				}
				,
				"privileges" :
				{
					"get_study":true ,
					"delete_study":true ,
					"get_roster":true , 
					"post_roster":true ,
					"get_role":true ,
					"put_role":true ,
					"delete_role":true ,
					"get_panel":true ,
					"get_control":true ,
					"put_control":true ,
					"post_table":true ,
					"get_model":true ,
					"post_model":true
				}
				,
				"study" :
				{
					"study_identifier":"ABCDEF0123456789" ,
					"study_name":"Panel Study"
				}
			}
			,
			{
				"location":"http://yosokumo.ws/user.AAAABBBBCCCCDDDD/study.ABCDEF0123456789/role" ,
				"roleholder" :
				{
					"user_identifier":"AAAABBBBCCCCDDDD" ,
					"user_name":"User One"
				}
				,
				"privileges" :
				{
					"get_study":true ,
					"delete_study":false ,
					"get_roster":false , 
					"post_roster":false ,
					"get_role":false ,
					"put_role":false ,
					"delete_role":false ,
					"get_panel":false ,
					"get_control":false ,
					"put_control":false ,
					"post_table":false ,
					"get_model":true ,
					"post_model":true
				}
				,
				"study" :
				{
					"study_identifier":"ABCDEF0123456789" ,
					"study_name":"Panel Study"
				}
			}
		]
	}
}

A standalone role document:

{
	"role" : 
	{
		"location":"http://yosokumo.ws/user.AAAABBBBCCCCDDDD/study.ABCDEF0123456789/role" ,
		"roleholder" :
		{
			"user_identifier":"AAAABBBBCCCCDDDD" ,
			"user_name":"User One"
		}
		,
		"privileges" :
		{
			"get_study":true ,
			"delete_study":false ,
			"get_roster":null , 
			"post_roster":false ,
			"get_role":null ,
			"put_role":false ,
			"delete_role":null ,
			"get_panel":false ,
			"get_control":null ,
			"put_control":false ,
			"post_table":null ,
			"get_model":true ,
			"post_model":true
		}
		,
		"study" :
		{
			"study_identifier":"ABCDEF0123456789" ,
			"study_name":"Panel Study"
		}
	}
}

A panel document:

{
	"panel" :
	{
		"study_identifier":"ABCDEF0123456789" ,
		"location":"http://yosokumo.ws/study.ABCDEF0123456789/panel" ,
		"control" :
		[
			{ "location":"http://yosokumo.ws/study.ABCDEF0123456789/panel.study_name" , "study_name":"Panel Study" } ,
			{ "type":"number" } ,
			{ "location":"http://yosokumo.ws/study.ABCDEF0123456789/panel.status" , "status":"paused" } ,
			{ "location":"http://yosokumo.ws/study.ABCDEF0123456789/panel.visibility" , "visibility":"private" } ,
			{ "block_count":64 } ,
			{ "cell_count":4194304 } ,
			{ "prospect_count":0 } ,
			{ "creation_time":"2009-10-24T01:04:16.064Z" } ,
			{ "latest_block_time":"2010-11-29T23:53:59.199Z" } ,
			{ "latest_prospect_time":null }
		]
	}
}

Standalone control documents:

{
	"control" :
	{
		"study_identifier":"ABCDEF0123456789" ,
		"status":"paused"
	}
}

{
	"control" :
	{
		"study_identifier":"ABCDEF0123456789" ,
		"visibility":"private"
	}
}

{
	"control" :
	{
		"study_identifier":"ABCDEF0123456789" ,
		"study_name":"Panel Study"
	}
}

Block documents:

{ "block" : { } }

{ "block" : { "type":"empty" } }

{
	"block" :
	{
		"study_identifier":"ABCDEF0123456789" ,
		"type":"row" ,
		"specimen" :
		[
			{
				"key":101 ,
				"weight":1 ,
				"status":"inactive" ,
				"type":"empty" ,
				"value":null ,
				"cell" :
				[
					{ "name":1 } ,
					{ "name":2 , "type":"natural" , "value":17365 } ,
					{ "name":3 , "type":"integer" , "value":528 } ,
					{ "name":4 , "type":"real" , "value":-93.37 } ,
					{ "name":5 , "type":"special" , "value":55 }
				]
			}
			,
			{
				"key":102 ,
				"weight":3 ,
				"status":"active" ,
				"type":"integer" ,
				"value":151 ,
				"cell" :
				[
					{ "name":1 , "type":"natural" , "value":0 } ,
					{ "name":2 , "type":"natural" , "value":4782 } ,
					{ "name":3 , "type":"integer" , "value":-4092 } ,
					{ "name":4 , "type":"real" , "value":2181.92 } ,
					{ "name":5 , "type":"special" , "value":50 }
				]
			}
		]
	}
}

{
	"block" :
	{
		"type":"column" ,
		"predictor" :
		[
			{ "name":1 , "status":"active" , "type":"categorical" , "level":"nominal" } ,
			{ "name":2 , "status":"active" , "type":"categorical" , "level":"ordinal" } ,
			{ "name":3 , "status":"active" , "type":"continuous" , "level":"interval" } ,
			{ "name":4 , "status":"active" , "type":"continuous" , "level":"ratio" } ,
			{ "name":5 , "status":"inactive" }
		]
	}
}

{
	"block" :
	{
		"study_identifier":"ABCDEF0123456789" ,
		"type":"column" ,
		"predictor" :
		[
			{
				"name":4 , 
				"cell" :
				[
					{ "key":1001 , "type":"integer" , "value":7 } ,
					{ "key":1002 , "type":"real" , "value":4.3 } ,
					{ "key":1003 , "type":"integer" , "value":5 } ,
					{ "key":1004 , "type":"real" , "value":-10.01 } ,
				]
			}
		]
	}
}

Standalone specimen documents:

{ "specimen" : { "key":101 , "type":"real" , "value":1.0123 } }

{
	"specimen" :
	{
		"key":102 ,
		"weight":3 ,
		"status":"active" ,
		"type":"integer" ,
		"value":151 ,
		"cell" :
		[
			{ "name":1 , "type":"natural" , "value":0 } ,
			{ "name":2 , "type":"natural" , "value":4782 } ,
			{ "name":3 , "type":"integer" , "value":-4092 } ,
			{ "name":4 , "type":"real" , "value":2181.92 } ,
			{ "name":5 , "type":"special" , "value":50 }
		]
	}
}

A message:

{ "message" : { "type":"error" , "text":"Message body." } }