Introduction

Service class definitions define the composite interface of a device, describing signatures for its properties, methods, and events. The class structure uses a subset of JSON Schema for parameter definitions used within property, method, and event definitions. By convention, keys are written in the camelCase capitalization style.

Class Structure Example

The following service class defines a property called “state,” a method called “doAction,” and an event called “somethingHappened.”

{
    "name": "ExampleClass",
    "properties": {
        "state": {
            "description": "Whether the device state is true or false",
            "type": "boolean"
        }
    },
    "methods": {
        "doAction": {
            "description": "An action that does something",
            "parameters": [
                {
                    "description": "The first parameter",
                    "type": "string"
                },
                {
                    "description": "The second parameter",
                    "type": "boolean"
                }
            ]
        }
    },
    "events": {
        "somethingHappened": {
            "description": "The device did something",
            "values": [
                {
                    "description": "The first value",
                    "type": "string"
                }
            ]
        }
    }
}

Properties Definitions

Properties are defined as a key-value pair between the “properties” key and an object which contains property definitions. The property definitions object contains the names of properties as its keys, associated with objects that define the properties themselves. Each individual property object must contain a description of the property, as well as its type.

In the previous example, the properties definitions look like the following.

"properties": {
    "state": {
        "description": "Whether the device state is true or false",
        "type": "boolean"
    }
}

Methods Definitions

Methods are defined as a key-value pair between the “methods” key and an object which contains method definitions. The method definitions object contains the names of methods as its keys, associated with objects that define the methods themselves. Each individual methods object must contain a description. A method object may also, but is not required to, contain an array of parameters the method requires to run properly. These parameters must be specified as objects, which must contain a description of themselves and their type.

In the previous example, the methods definitions look like the following.

"methods": {
    "doAction": {
        "description": "An action that does something",
        "parameters": [
            {
                "description": "The first parameter",
                "type": "string"
            },
            {
                "description": "The second parameter",
                "type": "boolean"
            }
        ]
    }
}

Events Definitions

Events are defined as a key-value pair between the “events” key and an object which contains event definitions. The event definitions object contains the names of events as its keys, associated with objects that define the events themselves. Each individual events object must contain a description. An events object may also, but is not required to, contain an array of values that may be attached to the event. These value must be specified as objects, which must contain a description of themselves and their type.

In the previous example, the events definitions look like the following.

"events": {
    "somethingHappened": {
        "description": "The device did something",
        "values": [
            {
                "description": "The first value",
                "type": "string"
            }
        ]
    }
}

Service Member Key-Value Refernece

title

A short-form description of the service member. This is not required, but recommended for getting quick summaries of functinality at a glance.

description

A full description of the service member. This is required for all members.

type

A string showing the data type of the parameter. Acceptable values are one of the following.

• string
• number
• integer
• object
• array
• boolean

Types may also be specified as an array, specifying multiple basic data types that a member can accept. The following example specifies that a type can be either a numeric value or a string.

{ "type": [ "number", "string" ] }

readOnly

This key indicates a property that may be read, but not written. By default, properties are not read only. This key should be set with a boolean value.

enum

This key is an array representing a fixed set of values the parameter may be. These values may be of any valid type.

"expiryType": {
    "in": "query",
    "type": "string",
    "required": false,
    "enum": [ "Infinite", "FixedTtl", "SlidingTtl" ]
}

Enums may include values of multiple types, and each value must be unique.

format

This key may only be present if the member type is a “string.” It indicates that a string should be validated against a commonly used pattern. Recognized formats may be one of the following.

• date-time
• email
• hostname
• ipv4
• ipv6
• uri

minLength

This key may only be present if the member type is a “string.” It is an integer value representing the minimum length (inclusive) that the member may be.

maxLength

This key may only be present if the member type is a “string.” It is an integer value representing the maximum length (inclusive) that the member may be.

pattern

This key may only be present if the member type is a “string.” It requires the string to conform to a particular regular expression.

multipleOf

This key may only be present if the member type is a “number” or “integer.” It restricts a value to a multiple of a given number. This multiple can be any positive number greater than 0.

minimum

This key may only be present if the member type is “number” or “integer.” It describes the minimum value (inclusive) that the member may be.

maximum

This key may only be present if the member type is “number” or “integer.” It describes the maximum value (inclusive) that the member may be.

properties, additionalProperties, and required

These keys are used when the member type is “object.”

“properties” must be present when defining an object. It defines the properties present inside an object, using key-value pairs similar to service class property definitions.

The “additionalProperties” denotes whether properties beyond those specified are allowed in the object.

The “required” uses an array of property names to define which properties must be present inside an object.

{
    "type": "object",
    "properties": {
        "foo": { "type": "boolean" },
        "bar": { "type": "string" }
    },
    "additionalProperties": false,
    "required": [ "foo" ]
}

items, minItems, maxItems, uniqueItems

These keys are used when the member type is “array.”

As an object, “items” defines a general rule for every item in the array.

{
    "type": "array",
    "items": {
        "type": "number"
    }
}

As an array, “items&fdquo; represents a rule for each index of the array.

{
    "type": "array",
    "items": [
        {
            "type": "number"
        },
        {
            "type": "string",
            "enum": [ "foo", "bar" ]
        }
    ]
}

The “minItems&fdquo; and “maxItems&fdquo; keys define the minimum and maximum lengths of an array. Both keywords must be a positive number.

The “uniqueItems&fdquo; key defines whether all items in an array must be unique. It must be a boolean value.