{"_id":"5827ead5dfc7c80f00f4e78d","user":"568bdbc4fe6fcc0d006dc970","project":"568bdc1483d2061900d86cdc","parentDoc":null,"category":{"_id":"587c422af45e2d0f005e200d","__v":0,"version":"582789aabe5c080f00a5a7fe","project":"568bdc1483d2061900d86cdc","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-01-16T03:46:50.263Z","from_sync":false,"order":2,"slug":"device-modeling","title":"Device Modeling"},"__v":0,"version":{"_id":"582789aabe5c080f00a5a7fe","__v":10,"project":"568bdc1483d2061900d86cdc","createdAt":"2016-11-12T21:29:14.915Z","releaseDate":"2016-11-12T21:29:14.915Z","categories":["582789abbe5c080f00a5a7ff","582789abbe5c080f00a5a800","582789abbe5c080f00a5a801","582789abbe5c080f00a5a802","582789abbe5c080f00a5a803","582789abbe5c080f00a5a804","582789abbe5c080f00a5a805","582789abbe5c080f00a5a806","582789abbe5c080f00a5a807","582789abbe5c080f00a5a808","5827ea984ca29e0f00137a9e","583df597887db62f00644283","583df5d9c622791900e78da5","5845cd8763c11b250037967d","5845d13063c11b2500379681","5859e859e3306d1900126725","587aeb9a01cf3a0f008359eb","587c422af45e2d0f005e200d","587d84dc82f6f30f004ceee5"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta2","version_clean":"0.0.0","version":"0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-11-13T04:23:49.353Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"# Introduction\nService class definitions schemas define the composite interface of a device, describing the the signatures for its properties, methods, and events. The schema structure uses a subset of JSON Schema for parameter definitions used within property, method, and event definitions; Service Class definitions should be an easy learn for anyone with a pre-existing knowledge of JSON Schema.\n\n# Schema structure\nA service class _must_ define a name and optionally, named event, method, and property defintions. Property, method, and event definitions take the form of key-value pairs, where the key is the property name and the value is an object using the parameter schema. By convention, property names are writtern in the camelCase capitalization style.\n\nThe following schema defines a property called _state_, a method called _doAction_, and an event called _somethingHappened_.\n``` JSON\n{\n    \"name\": \"ExampleClass\",\n    \"properties\": {\n        \"state\": {\n            \"description\": \"Whether the device state is true or false\",\n            \"type\": \"boolean\"\n        }\n    },\n    \"methods\": {\n        \"doAction\": {\n            \"description\": \"An action that does something\",\n            \"parameters\": [\n                {\n                    \"description\": \"The first parameter\",\n                    \"type\": \"string\"\n                },\n                {\n                    \"description\": \"The second parameter\",\n                    \"type\": \"boolean\"\n                }\n            ]\n        }\n    },\n    \"events\": {\n        \"somethingHappened\": {\n            \"description\": \"The device did something\",\n            \"values\": [\n                {\n                    \"description\": \"The first value\",\n                    \"type\": \"string\"\n                }\n            ]\n        }\n    }\n}\n```\n\n## name\nThe unique name of the service class. The `name` key is the only required top-level key. The `name` value may not contain spaces. By convention, the name is written using the PascalCase capitalization style.\n\nThe simplist valid schema:\n``` JSON\n{\n    \"name\": \"ExampleClass\"\n}\n```\n\n## properties\nA service class may contain named `properties`. Properies are primarily used to represent stateful information about the class it is applied to. These interfaces to the device state will allow the state to be read or written to. Any changes to a device’s underlaying state will also propagate a state change notification through its exposed properties.\n\nThe parameter schema is attached directly to the value of the named property key.\n``` JSON\n{\n    \"name\": \"ExampleClass\",\n    \"properties\": {\n        \"state\": {\n            \"description\": \"The device state\",\n            \"enum\": [ \"ready\", \"running\", \"paused\" ],\n            \"type\": \"string\"\n        }\n    }\n}\n```\n\n## methods\nA service class may contain named `methods`. Methods are primarily used to represent actions that device may do. Methods _may_ overlap with properties insofar that actions may cause state change; however, there is no requirement that a method is tied to a single state or any at all.\n\nMethod definitions contain a `description` and may contain an ordered array of `parameters` representing the parameters that may be passed to the method.\n``` JSON\n{\n    \"name\": \"ExampleClass\",\n    \"methods\": {\n        \"doAction\": {\n            \"description\": \"An action that does something\",\n            \"parameters\": [\n                {\n                    \"description\": \"The first parameter\",\n                    \"type\": \"string\"\n                },\n                {\n                    \"description\": \"The second parameter\",\n                    \"type\": \"boolean\"\n                }\n            ]\n        }\n    }\n}\n```\n\n## events\nA service class may contain named `events`. Events are primarily used to notify observers of a device of things that the device has done. While events may be used to notify observers of changes to device state, it may be more appropriate to use a property instead; properties will emit state changes independant of events making an explicit event doing the same redundant.\n\nEvent definitions contain a `description` and may contain an ordered array of `values` representing the values that may be attached to the event.\n``` JSON\n{\n    \"name\": \"ExampleClass\",\n    \"events\": {\n        \"somethingHappened\": {\n            \"description\": \"The device did something\",\n            \"values\": [\n                {\n                    \"description\": \"The first value\",\n                    \"type\": \"string\"\n                }\n            ]\n        }\n    }\n}\n```\n\n# Base parameter schema\nEach property, method, and event is defined with a parameter schema. This section describes the keys that are common across all three.\n\n## title\nA short-form description of the parameter.\n\n## description\nA full description of the parameter.\n\n## types\nThe `type` keyword restricts properties to a particular type or set of types. The types used here mirror the types used in JSON Schema. The type used may be any of the following basic data types:\n- string\n- integer\n- number\n- object\n- array\n- boolean\n\nThe type keyword may either be a string, using one of the above basic types, or an array of the same basic types with each element being unique.\n\nA simple example would be:\n``` JSON\n{ \"type\": \"number\" }\n```\nThis indicates that the property may accept any numeric value such as 1729 or 2.71828; however, it would not accept a string, such as `\"Not a Number\"`.\n\nAn example using arrays:\n``` JSON\n{ \"type\": [ \"number\", \"string\" ] }\n```\nThis indicates that the property may accept any numeric value or string.\n\n### string types\nThe `string` type is used for strings of text.\n\n#### length\nThe allowed length of a string type property may be constrained using the `minLength` and `maxLength` keywords. Both keywords must use a non-negative number.\n\nExample:\n``` JSON\n{\n    \"type\": \"string\",\n    \"minLength\": 1,\n    \"maxLength\": 3\n}\n```\n\n#### Regular expressions\nThe allowed string may be restricted to a particular regular expression using the `pattern` keyword.\nExample:\n``` JSON\n{\n    \"type\": \"string\",\n    \"pattern\": \"^[A-Z]{1}[a-z0-9]{24}$\"\n}\n```\n\n#### Format\nThe `format` keyword will validate a string across commonly used patterns. The recognized formats are:\n- `date-time`\n- `email`\n- `hostname`\n- `ipv4`\n- `ipv6`\n- `uri`\n\n### numeric types\nThere are two numeric types: `integer` and `number`. `integer` is used for integral numbers whereas `number` denotes any numeric type.\n#### multiples\nNumbers may be restricted to a multiple of a given number with the `multipleOf` keyword, which may be set to any positive number.\n\nExample:\n``` JSON\n{\n    \"type\": \"number\",\n    \"multipleOf\": 10\n}\n```\n\n#### ranges\nNumbers may be restricted to a particular range of values using a combination of `maximum`, `minimum`, `exclusiveMaximum`, and `exclusiveMinimum` keywords.\n\n`maximum` and `minimum` specify a `maximum` and `minimum` numeric value.\n`exclusiveMaximum` and `exclusiveMinimum` are booleans that specifiy whether the range excludes that `maximum` and `minimum` value accordingly. When false or not included, it indicates that the range includes the value.\n\nExample:\n``` JSON\n{\n    \"type\": \"number\",\n    \"minimum\": 0,\n    \"maximum\": 100,\n    \"excludeMaximum\": true\n}\n```\n\n### object types\nThe `object` type is used for Javascript objects.\n\n#### properties\nThe definition for an `object` may be defined using the `properties` keyword. Properties are defined using key-value pairs of property schemas.\n\nExample:\n``` JSON\n{\n    \"type\": \"object\",\n    \"properties\": {\n        \"foo\": { \"type\": \"boolean\" },\n        \"bar\": { \"type\": \"string\" }\n    }\n}\n```\n\n#### additional properties\nThe `additionalProperties` keyword may be used to determine whether properties beyond those specified are allowed. By default, additional properties are allowed.\n\nExample:\n``` JSON\n{\n    \"type\": \"object\",\n    \"properties\": {\n        \"foo\": { \"type\": \"boolean\" },\n        \"bar\": { \"type\": \"string\" }\n    },\n    \"additionalProperties\": false\n}\n```\n\n#### required properties\nThe `required` keyword may be used to determine whether certain object properties are required using an array of property names. By default, no properties are required. Each name must be unique.\n\nExample:\n``` JSON\n{\n    \"type\": \"object\",\n    \"properties\": {\n        \"foo\": { \"type\": \"boolean\" },\n        \"bar\": { \"type\": \"string\" }\n    },\n    \"required\": [ \"foo\" ]\n}\n```\n\n### array types\nThe `array` type is for ordered elements.\n\n#### array items\nBy default, array elements may be of any type. Elements may be restricted to a particular type using the `items` keyword.\n\nThe `type` keyword may be either an object or an array of objects.\n\nAs an object, `items` represents a rules that each item in the array (of arbitrary length) follows.\nExample of an array for which each items is a numeric value:\n``` JSON\n{\n    \"type\": \"array\",\n    \"items\": {\n        \"type\": \"number\"\n    }\n}\n```\n\nAs an array, `items` represents a rule for each index of the array.\nExample:\n``` JSON\n{\n    \"type\": \"array\",\n    \"items\": [\n        {\n            \"type\": \"number\"\n        },\n        {\n            \"type\": \"string\",\n            \"enum\": [ \"foo\", \"bar\" ]\n        }\n    ]\n}\n```\n\n#### Array length\nThe allowed length of an array may be set with the `maxItems` and `minItems` keywords. Both keywords must use a non-negative number.\n\nExample:\n``` JSON\n{\n    \"type\": \"array\",\n    \"minItems\": 1,\n    \"maxItems\": 5\n}\n```\n\n#### Unique items\nWhether the values in an array must be unique may be determined with the `uniqueItems` keyword.\n\nExample:\n``` JSON\n{\n    \"type\": \"array\",\n    \"uniqueItems\": true\n}\n```\n\n### boolean types\nBoolean type match only `true` and `false`.\n\n## Enumerated values\nA property value may be restricted to a fixed set of values using the `enum` keyword. These values must be unique.\n\nExample restricting a property to one of three animal names:\n``` JSON\n{\n    \"type\": \"string\",\n    \"enum\": [ \"dog\", \"cat\", \"aardvark\" ]\n}\n```\n\nEnums may include values of multiple types.\n\n## Property-specific schema keys\nProperties may have some key used in thier parameter definition that do not apply to methods or events.\n\n## Read only\nThe `readOnly` key indicates a property that may be read but not set with a boolean value. By default, properties are not read only.\n\n``` JSON\n{\n    \"readOnly\": true\n}\n```","excerpt":"","slug":"service-class-specification","type":"basic","title":"Service Class Specification"}

Service Class Specification


# Introduction Service class definitions schemas define the composite interface of a device, describing the the signatures for its properties, methods, and events. The schema structure uses a subset of JSON Schema for parameter definitions used within property, method, and event definitions; Service Class definitions should be an easy learn for anyone with a pre-existing knowledge of JSON Schema. # Schema structure A service class _must_ define a name and optionally, named event, method, and property defintions. Property, method, and event definitions take the form of key-value pairs, where the key is the property name and the value is an object using the parameter schema. By convention, property names are writtern in the camelCase capitalization style. The following schema defines a property called _state_, a method called _doAction_, and an event called _somethingHappened_. ``` JSON { "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" } ] } } } ``` ## name The unique name of the service class. The `name` key is the only required top-level key. The `name` value may not contain spaces. By convention, the name is written using the PascalCase capitalization style. The simplist valid schema: ``` JSON { "name": "ExampleClass" } ``` ## properties A service class may contain named `properties`. Properies are primarily used to represent stateful information about the class it is applied to. These interfaces to the device state will allow the state to be read or written to. Any changes to a device’s underlaying state will also propagate a state change notification through its exposed properties. The parameter schema is attached directly to the value of the named property key. ``` JSON { "name": "ExampleClass", "properties": { "state": { "description": "The device state", "enum": [ "ready", "running", "paused" ], "type": "string" } } } ``` ## methods A service class may contain named `methods`. Methods are primarily used to represent actions that device may do. Methods _may_ overlap with properties insofar that actions may cause state change; however, there is no requirement that a method is tied to a single state or any at all. Method definitions contain a `description` and may contain an ordered array of `parameters` representing the parameters that may be passed to the method. ``` JSON { "name": "ExampleClass", "methods": { "doAction": { "description": "An action that does something", "parameters": [ { "description": "The first parameter", "type": "string" }, { "description": "The second parameter", "type": "boolean" } ] } } } ``` ## events A service class may contain named `events`. Events are primarily used to notify observers of a device of things that the device has done. While events may be used to notify observers of changes to device state, it may be more appropriate to use a property instead; properties will emit state changes independant of events making an explicit event doing the same redundant. Event definitions contain a `description` and may contain an ordered array of `values` representing the values that may be attached to the event. ``` JSON { "name": "ExampleClass", "events": { "somethingHappened": { "description": "The device did something", "values": [ { "description": "The first value", "type": "string" } ] } } } ``` # Base parameter schema Each property, method, and event is defined with a parameter schema. This section describes the keys that are common across all three. ## title A short-form description of the parameter. ## description A full description of the parameter. ## types The `type` keyword restricts properties to a particular type or set of types. The types used here mirror the types used in JSON Schema. The type used may be any of the following basic data types: - string - integer - number - object - array - boolean The type keyword may either be a string, using one of the above basic types, or an array of the same basic types with each element being unique. A simple example would be: ``` JSON { "type": "number" } ``` This indicates that the property may accept any numeric value such as 1729 or 2.71828; however, it would not accept a string, such as `"Not a Number"`. An example using arrays: ``` JSON { "type": [ "number", "string" ] } ``` This indicates that the property may accept any numeric value or string. ### string types The `string` type is used for strings of text. #### length The allowed length of a string type property may be constrained using the `minLength` and `maxLength` keywords. Both keywords must use a non-negative number. Example: ``` JSON { "type": "string", "minLength": 1, "maxLength": 3 } ``` #### Regular expressions The allowed string may be restricted to a particular regular expression using the `pattern` keyword. Example: ``` JSON { "type": "string", "pattern": "^[A-Z]{1}[a-z0-9]{24}$" } ``` #### Format The `format` keyword will validate a string across commonly used patterns. The recognized formats are: - `date-time` - `email` - `hostname` - `ipv4` - `ipv6` - `uri` ### numeric types There are two numeric types: `integer` and `number`. `integer` is used for integral numbers whereas `number` denotes any numeric type. #### multiples Numbers may be restricted to a multiple of a given number with the `multipleOf` keyword, which may be set to any positive number. Example: ``` JSON { "type": "number", "multipleOf": 10 } ``` #### ranges Numbers may be restricted to a particular range of values using a combination of `maximum`, `minimum`, `exclusiveMaximum`, and `exclusiveMinimum` keywords. `maximum` and `minimum` specify a `maximum` and `minimum` numeric value. `exclusiveMaximum` and `exclusiveMinimum` are booleans that specifiy whether the range excludes that `maximum` and `minimum` value accordingly. When false or not included, it indicates that the range includes the value. Example: ``` JSON { "type": "number", "minimum": 0, "maximum": 100, "excludeMaximum": true } ``` ### object types The `object` type is used for Javascript objects. #### properties The definition for an `object` may be defined using the `properties` keyword. Properties are defined using key-value pairs of property schemas. Example: ``` JSON { "type": "object", "properties": { "foo": { "type": "boolean" }, "bar": { "type": "string" } } } ``` #### additional properties The `additionalProperties` keyword may be used to determine whether properties beyond those specified are allowed. By default, additional properties are allowed. Example: ``` JSON { "type": "object", "properties": { "foo": { "type": "boolean" }, "bar": { "type": "string" } }, "additionalProperties": false } ``` #### required properties The `required` keyword may be used to determine whether certain object properties are required using an array of property names. By default, no properties are required. Each name must be unique. Example: ``` JSON { "type": "object", "properties": { "foo": { "type": "boolean" }, "bar": { "type": "string" } }, "required": [ "foo" ] } ``` ### array types The `array` type is for ordered elements. #### array items By default, array elements may be of any type. Elements may be restricted to a particular type using the `items` keyword. The `type` keyword may be either an object or an array of objects. As an object, `items` represents a rules that each item in the array (of arbitrary length) follows. Example of an array for which each items is a numeric value: ``` JSON { "type": "array", "items": { "type": "number" } } ``` As an array, `items` represents a rule for each index of the array. Example: ``` JSON { "type": "array", "items": [ { "type": "number" }, { "type": "string", "enum": [ "foo", "bar" ] } ] } ``` #### Array length The allowed length of an array may be set with the `maxItems` and `minItems` keywords. Both keywords must use a non-negative number. Example: ``` JSON { "type": "array", "minItems": 1, "maxItems": 5 } ``` #### Unique items Whether the values in an array must be unique may be determined with the `uniqueItems` keyword. Example: ``` JSON { "type": "array", "uniqueItems": true } ``` ### boolean types Boolean type match only `true` and `false`. ## Enumerated values A property value may be restricted to a fixed set of values using the `enum` keyword. These values must be unique. Example restricting a property to one of three animal names: ``` JSON { "type": "string", "enum": [ "dog", "cat", "aardvark" ] } ``` Enums may include values of multiple types. ## Property-specific schema keys Properties may have some key used in thier parameter definition that do not apply to methods or events. ## Read only The `readOnly` key indicates a property that may be read but not set with a boolean value. By default, properties are not read only. ``` JSON { "readOnly": true } ```