{"_id":"59d8037847ed910010ada8d2","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-06T22:28:08.726Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"# Overview\n\nThe following examples of service classes illustrate how to group functionalities so they are reusable and modular, which are essential components of proper service classes.\n\n# Uniqueness: BinarySwitch\n\nAll service members must be unique within the service. For example, a service cannot have both a `switch` property and a `switch` method.\n\n```\n{\n    \"name\":\"BinarySwitch\",\n    \"properties\": {\n        \"switch\": {\n            \"values\": [\"on\", \"off\"]\n        }\n    },\n    \"methods\": {\n        \"switchOn\": {\n            \"description\": \"Sets switch to on\"\n        },\n        \"switchOff\": {\n            \"description\": \"Sets switch to off\"\n        }\n    }\n}\n```\n\n# Modularity: MediaControl, MediaInfo, and AudioOutput\n\nProperly defined modular services should be re-usable for other devices. While a smart speaker might have volume, play/pause, and album info, each of these things may also exist independently on other devices. A traditional Bluetooth speaker would be able to change volume, and play/pause the media, but wouldn’t know what track is playing. Some Bluetooth speakers can simply change volume; and not pause or skip the track.\n\nThe MediaControl service controls the play queue of a smart speaker.\n\n```\n{\n    \"name\": \"MediaControl\",\n    \"properties\": [\n        {\n            \"state\": {\n                \"values\": [\"play\", \"pause\", \"stop\"]\n            }\n        }\n    ],\n    \"methods\": {\n        \"next\": {\n            \"description\": \"Plays next track\"\n        },\n        \"pause\": {\n            \"description\": \"Pauses the audio\"\n        },\n        \"play\": {\n            \"description\": \"Plays the audio\"\n        },\n        \"previous\": {\n            \"description\": \"Plays previous track\"\n        }\n    }\n}\n```\n\nThe MediaInfo service provides information about the current media.\n\n```\n{\n    \"name\": \"MediaInfo\",\n    \"properties\": {\n        \"albumArt\": {\n            \"valueType\": \"uri\",\n            \"access\": \"read\"\n        },\n        \"albumTitle\": {\n            \"valueType\": \"string\",\n            \"access\": \"read\"\n        },\n        \"artist\": {\n            \"valueType\": \"string\",\n            \"access\": \"read\"\n        },\n        \"nextAlbumTitle\": {\n            \"valueType\": \"string\",\n            \"access\": \"read\"\n        },\n        \"nextArtist\": {\n            \"valueType\": \"string\",\n            \"access\": \"read\"\n        },\n        \"nextTrackName\": {\n            \"valueType\": \"string\",\n            \"access\": \"read\"\n        },\n        \"trackName\": {\n            \"valueType\": \"string\",\n            \"access\": \"read\"\n        }\n    },\n    \"methods\": {},\n    \"events\": {\n        \"trackChanged\": {\n            \"description\": \"Indicates the currently playing track has changed\"\n        }\n    }\n}\n```\n\nThe AudioOutput service controls the volume of a speaker.\n\n```\n{\n    \"name\": \"AudioOutput\",\n    \"properties\": {\n        \"volume\": {\n            \"value-min\": 0,\n            \"value-max\": 100\n        },\n        \"mute\": {\n            \"values\": [true, false]\n        }\n    },\n    \"methods\": {\n        \"mute\": {\n            \"description\": \"Mutes the audio\"\n        },\n        \"stepUp\": {\n            \"description\": \"Increment the volume one level\"\n        },\n        \"stepDown\": {\n            \"description\": \"Decrement the volume one level\"\n        },\n        \"unmute\": {\n            \"description\": \"Unmutes the audio\"\n        }\n    }\n}\n```\n\nPutting these three services together, it is clear how each service controls something different about a smart speaker, without overlap. These services together create the complete model of the speaker. The BinarySwitch service could be applied to the speaker as well to handle on/off switch states, depending on the capabilities of the speaker. This is possible because, like the existing speaker services, BinarySwitch has no overlap with other services modeled in the speaker.\n\n![smart speaker](https://droplit.box.com/shared/static/cbw56hdo0kh7gxq9dka9kxn3joqpsxvi.png)\n\n# Reusability: DimmableLight, MulticolorLight\n\nA well-defined service definition should consider how it would be reused by other devices.\n\nUsing smart lighting as an example, some lights can change in brightness while others can change in both color and brightness, while others can change in brightness and color temperature within the white spectrum.\n\n![smart lights](https://droplit.box.com/shared/static/hras6h42jksp60q04jkh7cns3297yq62.png)\n\n# Indexed Services\n\nAs previously described, devices can implement multiple instances of the same service when there are multiple parts of the device that function in the same way. For example, in a power strip with 5 different BinarySwitch services defining the outlets, specifying specific service indexes with service selectors facilitates precise control over individual outlets.\n\n![smart power strip](https://droplit.box.com/shared/static/3t7zw8cok4t5vjvxhfakyoi9zmmv6sqr.png)\n\nFor more on service selectors, see the next section.","excerpt":"","slug":"service-examples","type":"basic","title":"Service Examples"}
# Overview The following examples of service classes illustrate how to group functionalities so they are reusable and modular, which are essential components of proper service classes. # Uniqueness: BinarySwitch All service members must be unique within the service. For example, a service cannot have both a `switch` property and a `switch` method. ``` { "name":"BinarySwitch", "properties": { "switch": { "values": ["on", "off"] } }, "methods": { "switchOn": { "description": "Sets switch to on" }, "switchOff": { "description": "Sets switch to off" } } } ``` # Modularity: MediaControl, MediaInfo, and AudioOutput Properly defined modular services should be re-usable for other devices. While a smart speaker might have volume, play/pause, and album info, each of these things may also exist independently on other devices. A traditional Bluetooth speaker would be able to change volume, and play/pause the media, but wouldn’t know what track is playing. Some Bluetooth speakers can simply change volume; and not pause or skip the track. The MediaControl service controls the play queue of a smart speaker. ``` { "name": "MediaControl", "properties": [ { "state": { "values": ["play", "pause", "stop"] } } ], "methods": { "next": { "description": "Plays next track" }, "pause": { "description": "Pauses the audio" }, "play": { "description": "Plays the audio" }, "previous": { "description": "Plays previous track" } } } ``` The MediaInfo service provides information about the current media. ``` { "name": "MediaInfo", "properties": { "albumArt": { "valueType": "uri", "access": "read" }, "albumTitle": { "valueType": "string", "access": "read" }, "artist": { "valueType": "string", "access": "read" }, "nextAlbumTitle": { "valueType": "string", "access": "read" }, "nextArtist": { "valueType": "string", "access": "read" }, "nextTrackName": { "valueType": "string", "access": "read" }, "trackName": { "valueType": "string", "access": "read" } }, "methods": {}, "events": { "trackChanged": { "description": "Indicates the currently playing track has changed" } } } ``` The AudioOutput service controls the volume of a speaker. ``` { "name": "AudioOutput", "properties": { "volume": { "value-min": 0, "value-max": 100 }, "mute": { "values": [true, false] } }, "methods": { "mute": { "description": "Mutes the audio" }, "stepUp": { "description": "Increment the volume one level" }, "stepDown": { "description": "Decrement the volume one level" }, "unmute": { "description": "Unmutes the audio" } } } ``` Putting these three services together, it is clear how each service controls something different about a smart speaker, without overlap. These services together create the complete model of the speaker. The BinarySwitch service could be applied to the speaker as well to handle on/off switch states, depending on the capabilities of the speaker. This is possible because, like the existing speaker services, BinarySwitch has no overlap with other services modeled in the speaker. ![smart speaker](https://droplit.box.com/shared/static/cbw56hdo0kh7gxq9dka9kxn3joqpsxvi.png) # Reusability: DimmableLight, MulticolorLight A well-defined service definition should consider how it would be reused by other devices. Using smart lighting as an example, some lights can change in brightness while others can change in both color and brightness, while others can change in brightness and color temperature within the white spectrum. ![smart lights](https://droplit.box.com/shared/static/hras6h42jksp60q04jkh7cns3297yq62.png) # Indexed Services As previously described, devices can implement multiple instances of the same service when there are multiple parts of the device that function in the same way. For example, in a power strip with 5 different BinarySwitch services defining the outlets, specifying specific service indexes with service selectors facilitates precise control over individual outlets. ![smart power strip](https://droplit.box.com/shared/static/3t7zw8cok4t5vjvxhfakyoi9zmmv6sqr.png) For more on service selectors, see the next section.