This project is read-only.

JSDL specification

Specification as JSON schema: https://jsdl.svn.codeplex.com/svn/-%20Specification/Specification.json
Sample JSDL file: http://rsuter.com/Services/Jsdl/SampleService.php?operation=jsdl&pretty

{
	"operations": {
		"sum": {
			target: "index.aspx?operation=sum", 
			...
		}
	},
	"types": [{
		type: "object", 
		...
	}]
}

Operation properties:
  • target: Relative or absolute path to the web service operation
  • transport: HTTP transport method
    • get
    • post
    • put
    • delete
  • envelope (default: json)
    • json (not allowed if transport = GET): Parameters are encoded as a JSON array and transmitted as POST content (as a JSON array of objects, defined in the "parameters" property; a JSON object if using the "parameter" property)
    • query: Parameters are encoded as GET / POST query. When using this envelope type, only primitive/value types can be used.
    • url: Parameters are inserted into the target string with the same order as specified. When using this envelope type, only primitive/value types can be used. The target string must be of the following syntax: "/person/details/{0}/order/{1}" where the first parameter is inserted into the {0} placeholder, and the second parameter into the {1} placeholder.
  • contentType (default: application/json): The type of the return value. If not returning JSON, set the content type and set the return type (the "returns" property) to type "string".
  • parameters: Defines the parameters of the operation
    • Important: In contrast to the JSON Schema rules, all parameters are by default required (default of required = true) (in JSON Schema definitions, a property is by default not required)
  • parameter: Defines a single JSON object as operation parameter (either "parameters" or "parameter" is allowed, but not both at the same time).
    • Important: The "parameter" property is only allowed if "transport" != "get", "envelope" = "json" and the "parameters" property is not used!
  • returns: Defines the return type of the operation

Important: The "required" attribute of JSON Schema types specifies whether an object's attribute is nullable (can be set to null) or not. By default an attribute is not required (exception: parameters, see note above). In C# a nullable integer is generated as "Nullable<Int32>".

Error handling and exceptions

Error handling is done with HTTP status codes. If the status code is >= 400, the response content MAY contain an exception object (if the response is empty, a generic exception object is created on the client). The exception object has to be in the following form:

{
	"code": "file_not_found", 
	"message": "The file 'sample' could not be found. ", 
	"stackTrace": "...", 
	"data": { any JSON object } 
}

The properties "message", "stackTrace" and "data" are optional.

JSON Schema extensions

Dictionary type

To be more flexible, the JSON Schema has been extended with the "dictionary" type which can be used the same way as "array" but each object also has a string as key.

Sample JSON:
{
	"German": {
		"title": "myGermanTitle", 
		"text": "myGermanText"
	}, 
	"French": {
		"title": "myFrenchTitle", 
		"text": "myFrenchText"
	}, 
	"English": {
		"title": "myEnglishTitle", 
		"text": "myEnglishText"
	}		
}

Sample JSON Schema:
{
	"type": "dictionary", 
	"items": {
		"type": "object", 
		"properties": {
			"title": {
				"type": "string"
			}, 
			"text": {
				"type": "string"
			}
		}
	}
}




Last edited Oct 31, 2013 at 9:08 PM by rsuter, version 41

Comments

No comments yet.