Hi All,
I've had a look at the JSON Schema idea instead of WebIDL:
http://json-schema.org/
https://openconnectivity.org/resources/specifications
Taking the authorize messages as my examples, I have written the following schemas. JSON Schema allows the use of references, but it is traditionally either within an interface or within a separate JSON document, not within a larger document. I believe we can still however provide these definitions separately to make our documentation more readable, as in the example below.
I'm happy to elaborate on this idea if this is appropriate.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Authorize Request",
"description": "Enables the user to set access controls for the vehicle signals",
"type": "object",
"required": ["action", "tokens", "requestId"],
"properties": {
"action": {
"enum": [ "authorize" ],
"description": "The identifier for the authorize request",
},
"tokens": {
"description": "Name of the product",
"type": "object",
"properties": {
"authorization": {
"description": "The user token, for the user that the client is making requests on behalf of",
"type": "string"
},
"www-vehicle-device": {
"description": "The device token for the originating device that is making the request to the server",
"type": "string"
}
}
},
"requestId": {
"description": "The unique identifier as specified by the client",
"type": "string"
},
},
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Authorize Success Response",
"description": "The response sent from the server upon a successful authorization request",
"type": "object",
"required": ["action", "TTL", "requestId"],
"properties": {
"action": {
"enum": [ "authorize" ],
"description": "The identifier for the authorize request",
},
"TTL": {
"description": "The time to live of the authorization token",
"type": "integer"
},
"requestId": {
"type": "string"
},
},
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Authorize Error Response",
"description": "The response sent from the server upon an unsuccessful authorization request",
"type": "object",
"required": ["action", "error", "requestId"],
"properties": {
"action": {
"enum": [ "authorize" ],
"description": "The identifier for the authorize request",
},
"error": {
"$ref": "#/definitions/error"
},
"requestId": {
"type": "string"
},
},
}
{
"definitions": {
"error": {
"description": "Server response for error cases",
"type": "object",
"properties": {
"number": {
"description": "HTTP Status Code Number",
"type": "integer"
},
"reason": {
"description": "Pre-defined string value that can be used to distinguish between errors that have the same code",
"type": "string"
},
"message": {
"description": "Message text describing the cause in more detail",
"type": "string"
},
}
},
}
}