{"_id":"59d83ade46041d0026f517e0","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":19,"createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"59d5a5e323e6e800103defb2","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-10-05T03:24:19.328Z","from_sync":false,"order":3,"slug":"data-modeling-with-service-classes","title":"Data Modeling With Service Classes"},"user":"58cc41f21751ce2f003be3b7","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-10-07T02:24:30.756Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"# Introduction\n\nService 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.\n\n# Class Structure Example\n\nThe following service class defines a property called “state,” a method called “doAction,” and an event called “somethingHappened.”\n\n```\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## Properties Definitions\n\nProperties 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.\n\nIn the previous example, the properties definitions look like the following.\n\n```\n\"properties\": {\n    \"state\": {\n        \"description\": \"Whether the device state is true or false\",\n        \"type\": \"boolean\"\n    }\n}\n```\n\n## Methods Definitions\n\nMethods 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.\n\nIn the previous example, the methods definitions look like the following.\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```\n\n## Events Definitions\n\nEvents 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.\n\nIn the previous example, the events definitions look like the following.\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# Service Member Key-Value Refernece\n\n## title\nA short-form description of the service member. This is not required, but recommended for getting quick summaries of functinality at a glance.\n\n## description\nA full description of the service member. This is required for all members.\n\n## type\nA string showing the data type of the parameter. Acceptable values are one of the following.\n* string\n* number\n* integer\n* object\n* array\n* boolean\n\nTypes 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.\n\n```\n{ \"type\": [ \"number\", \"string\" ] }\n```\n\n## readOnly\nThis 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.\n\n## enum\nThis key is an array representing a fixed set of values the parameter may be. These values may be of any valid type.\n\n```\n\"expiryType\": {\n    \"in\": \"query\",\n    \"type\": \"string\",\n    \"required\": false,\n    \"enum\": [ \"Infinite\", \"FixedTtl\", \"SlidingTtl\" ]\n}\n```\n\nEnums may include values of multiple types, and each value must be unique.\n\n## format\nThis 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.\n\n- date-time\n- email\n- hostname\n- ipv4\n- ipv6\n- uri\n\n## minLength\nThis 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.\n\n## maxLength\nThis 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.\n\n## pattern\nThis key may only be present if the member type is a “string.” It requires the string to conform to a particular regular expression.\n\n## multipleOf\nThis 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.\n\n## minimum\nThis key may only be present if the member type is “number” or “integer.” It describes the minimum value (inclusive) that the member may be.\n\n## maximum\nThis key may only be present if the member type is “number” or “integer.” It describes the maximum value (inclusive) that the member may be.\n\n## properties, additionalProperties, and required\nThese keys are used when the member type is “object.”\n\n“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.\n\nThe “additionalProperties” denotes whether properties beyond those specified are allowed in the object.\n\nThe “required” uses an array of property names to define which properties must be present inside an object.\n\n```\n{\n    \"type\": \"object\",\n    \"properties\": {\n        \"foo\": { \"type\": \"boolean\" },\n        \"bar\": { \"type\": \"string\" }\n    },\n    \"additionalProperties\": false,\n    \"required\": [ \"foo\" ]\n}\n```\n\n## items, minItems, maxItems, uniqueItems\nThese keys are used when the member type is “array.”\n\nAs an object, “items” defines a general rule for every item in the array.\n\n```\n{\n    \"type\": \"array\",\n    \"items\": {\n        \"type\": \"number\"\n    }\n}\n```\n\nAs an array, “items&fdquo; represents a rule for each index of the array.\n\n```\n{\n    \"type\": \"array\",\n    \"items\": [\n        {\n            \"type\": \"number\"\n        },\n        {\n            \"type\": \"string\",\n            \"enum\": [ \"foo\", \"bar\" ]\n        }\n    ]\n}\n```\n\nThe “minItems&fdquo; and “maxItems&fdquo; keys define the minimum and maximum lengths of an array. Both keywords must be a positive number.\n\nThe “uniqueItems&fdquo; key defines whether all items in an array must be unique. It must be a boolean value.","excerpt":"","slug":"service-class-specification","type":"basic","title":"Service Class Specification"}

Service Class Specification


# 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.