Using JSON Schema for instead of Web IDL

[acrofts84]

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"                    
                },
            }   
        },
    }
}

[wonsuk73]

Thanks! @acrofts84 and sorry for late reply! This is the OCF spec for their resource type. Please refer this. https://openconnectivity.org/specs/OIC_Resource_Type_Specification_v1.1.0.pdf

For this comment on your JSON schema example I will get back to you soon :-)

[rstreif]

@wonsuk73, @acrofts84 During my talk at the GENIVI AMM in Burlingame just a couple of weeks ago I also touched on the subject of integration with OCF and IoTivity. The triangle of GENIVI, W3C and OCF is forming a powerful ecosystem of the connected car. A GENIVI-OCF demonstrator that integrates the OCF Object Model with RVI has been shown at the Paris AMM and at an OCF event in late June in Portland. Videos can be found at [https://blogs.s-osg.org/osg-ocf-automotive-fortnight]. We have been continuing the discussion between GENIVI and OCF. OCF is working on representing VSS as OCF data models. The idea is to also develop a generator that creates OCF data models directly from VSS. That generator would be hosted at the GENIVI Github VSS repo [https://github.com/GENIVI/vehicle_signal_specification].

[wonsuk73]

@rstreif Thanks for sharing the information!

[acrofts84]

Thanks @wonsuk73, @rstreif .

I agree that the GENIVI, W3C, OCF triangle will be very powerful. As a result using a self describing JSON schema for our spec will make adoption much easier. Having said that, I believe the existing specification is much more human friendly, I personally find it much easier to interpret. If appropriate we could develop a JSON Schema note alongside the spec. The only difficulty there would be ensuring there are no discrepancies between the two specs and maintenance, so we would require some rigorous checks.

[rstreif]

Per Working Group Meeting: consent to accompany the specification with the JSON schema metadata for the API specification; @drkevg and @acrofts84 to add JSON schema and WebIDL definitions in 1/2017

[rstreif]

AR: @acrofts84 and @drkevg, as we have a consensus on this already, pleas make sure that the JSON schema is updated and follows any changes of the specification.

[acrofts84]

JSON Schema has been merged. See #201 for further discussion, removing WebIDL