{"_id":"579a54f67bf55c0e0013a732","category":{"_id":"579a382265f89a170099946f","project":"573f3f6c87cbd20e00208e41","version":"573f3f6c87cbd20e00208e42","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-28T16:51:46.560Z","from_sync":false,"order":9999,"slug":"schemas","title":"Schemas"},"project":"573f3f6c87cbd20e00208e41","user":"5564f227f0f70f0d00a9ab20","__v":0,"version":{"_id":"573f3f6c87cbd20e00208e42","__v":2,"project":"573f3f6c87cbd20e00208e41","createdAt":"2016-05-18T20:59:16.635Z","releaseDate":"2016-05-18T20:59:16.635Z","categories":["573f3f6c87cbd20e00208e44","573f3f6c87cbd20e00208e43","573f3f6c87cbd20e00208e45","573f3f6c87cbd20e00208e46","573f3f6c87cbd20e00208e47","573f3f6c87cbd20e00208e48","573f3f6c87cbd20e00208e49","573f3f6c87cbd20e00208e4a","573f3f6c87cbd20e00208e4b","579a382265f89a170099946f","57bce03036eff81700666963"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-28T18:54:46.370Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":999,"body":"The Configure schema allows a device to control what properties are editable, and control the type of data stored to those properties. We support much of [JSON Schema](http://json-schema.org/), but not all the options are available.\n\nOctoblu provides some specific extensions to the standard JSON Schema. This guide will cover some of the Octoblu specific ideas, and will not be a general JSON Schema tutorial.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Multiple Configurations\"\n}\n[/block]\nThis first thing you will notice is that Octoblu supports multiple configuration schemas. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"schemas\\\": {\\n    \\\"configure\\\": {\\n      \\\"first\\\": { ... },\\n      \\\"second\\\": { ... },\\n      \\\"third\\\": { ... }\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Multiple Config Example\"\n    }\n  ]\n}\n[/block]\nWhen the user views this configuration in Octoblu, they will be presented a choice between the schemas. This allows the schema author to provide different configurations, `Basic` and `Advanced` for example.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Grouping\"\n}\n[/block]\nOctoblu will allow you to group configurations together. For example, if a device offers different types of shells to the user, the schema author could group them by operating system.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"schemas\\\": {\\n    \\\"configure\\\": {\\n      \\\"powershell\\\": {\\n        \\\"x-group-name\\\": \\\"Windows\\\"\\n      },\\n      \\\"cmd.exe\\\": {\\n        \\\"x-group-name\\\": \\\"Windows\\\"        \\n      },\\n      \\\"bash\\\": {\\n        \\\"x-group-name\\\": \\\"UNIX-ish\\\"\\n      }\\n    }\\n  }\\n}\\n    \",\n      \"language\": \"json\",\n      \"name\": \"Grouping Example\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Form Schema\"\n}\n[/block]\n `x-form-schema` is required in order to reference a [Form](doc:schema-form) schema. Octoblu will search the `schemas.form` object for a matching key and apply that form schema.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"schemas\\\": {\\n    \\\"version\\\": \\\"2.0.0\\\",\\n    \\\"configure\\\": {\\n      \\\"default\\\": {\\n        \\\"type\\\": \\\"object\\\",\\n        \\\"properties\\\": {\\n          \\\"enabled\\\": {\\n            \\\"type\\\": \\\"boolean\\\",\\n            \\\"default\\\": false\\n          }\\n        },\\n        \\\"x-form-schema\\\": {\\n          \\\"angular\\\": \\\"configure.default.angular\\\"\\n        }\\n      }\\n    },\\n    \\\"form\\\": {\\n      \\\"configure\\\": {\\n        \\\"default\\\": {\\n          \\\"angular\\\": [ ... ]\\n        }\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Form Schema Example\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Default Configure Schema\"\n}\n[/block]\nAny schema named `default` will be selected unless you override the `schemas.selected.configure` property of your device and set it to the key of the configure schema object.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"name\\\": \\\"Device A\\\",\\n  \\\"schemas\\\": {\\n    \\\"configure\\\": {\\n      \\\"not-the-default\\\": { ... }\\n    },\\n    \\\"selected\\\": {\\n      \\\"configure\\\": \\\"not-the-default\\\"\\n\\t  }\\n  }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Default Example\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Reference an external schema\"\n}\n[/block]\nOctoblu supports the standard `$ref` capability of JSON Schema. Octoblu will resolve the reference and apply the schema to the device.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"schemas\\\": {\\n    \\\"configure\\\": {\\n      \\\"device-a\\\": {\\n        \\\"$ref\\\": \\\"https://data-forwarder-mongodb.octoblu.com/schemas/v1/configure.json\\\"\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"External Schema Reference\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Reference another device schema\"\n}\n[/block]\nOctoblu allows you to reference a schema on another device, provided the device is given proper permissions. You can reference any property of the device and it will be used as the configuration schema.\n\nThe URI follows this pattern: `meshbludevice://uuid/#/path/to/property`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Device A\\n{\\n  \\\"name\\\": \\\"Device A\\\",\\n  \\\"meshblu\\\": {\\n    \\\"version\\\": \\\"2.0.0\\\",\\n\\t  \\\"whitelists\\\": {\\n      \\\"discover\\\": {\\n        \\\"view\\\": [\\n          { \\\"uuid\\\": \\\"device-b\\\" }\\n        ]\\n      } \\n\\t  }\\n  },\\n  \\\"friendSchemas\\\": {\\n\\t  \\\"deviceB\\\": { ... }\\n  }\\n}\\n\\n// Device B\\n{\\n  \\\"name\\\": \\\"Device B\\\",\\n  \\\"schemas\\\": {\\n    \\\"configure\\\": {\\n      \\\"device-a\\\": {\\n        \\\"$ref\\\": \\\"meshbludevice://device-a/#/friendSchemas/deviceB\\\"\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Cross-Device Schema Example\"\n    }\n  ]\n}\n[/block]","excerpt":"Configure Schema Options","slug":"schema-configure","type":"basic","title":"Configure"}

Configure

Configure Schema Options

The Configure schema allows a device to control what properties are editable, and control the type of data stored to those properties. We support much of [JSON Schema](http://json-schema.org/), but not all the options are available. Octoblu provides some specific extensions to the standard JSON Schema. This guide will cover some of the Octoblu specific ideas, and will not be a general JSON Schema tutorial. [block:api-header] { "type": "basic", "title": "Multiple Configurations" } [/block] This first thing you will notice is that Octoblu supports multiple configuration schemas. [block:code] { "codes": [ { "code": "{\n \"schemas\": {\n \"configure\": {\n \"first\": { ... },\n \"second\": { ... },\n \"third\": { ... }\n }\n }\n}", "language": "json", "name": "Multiple Config Example" } ] } [/block] When the user views this configuration in Octoblu, they will be presented a choice between the schemas. This allows the schema author to provide different configurations, `Basic` and `Advanced` for example. [block:api-header] { "type": "basic", "title": "Grouping" } [/block] Octoblu will allow you to group configurations together. For example, if a device offers different types of shells to the user, the schema author could group them by operating system. [block:code] { "codes": [ { "code": "{\n \"schemas\": {\n \"configure\": {\n \"powershell\": {\n \"x-group-name\": \"Windows\"\n },\n \"cmd.exe\": {\n \"x-group-name\": \"Windows\" \n },\n \"bash\": {\n \"x-group-name\": \"UNIX-ish\"\n }\n }\n }\n}\n ", "language": "json", "name": "Grouping Example" } ] } [/block] [block:api-header] { "type": "basic", "title": "Form Schema" } [/block] `x-form-schema` is required in order to reference a [Form](doc:schema-form) schema. Octoblu will search the `schemas.form` object for a matching key and apply that form schema. [block:code] { "codes": [ { "code": "{\n \"schemas\": {\n \"version\": \"2.0.0\",\n \"configure\": {\n \"default\": {\n \"type\": \"object\",\n \"properties\": {\n \"enabled\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"x-form-schema\": {\n \"angular\": \"configure.default.angular\"\n }\n }\n },\n \"form\": {\n \"configure\": {\n \"default\": {\n \"angular\": [ ... ]\n }\n }\n }\n }\n}", "language": "json", "name": "Form Schema Example" } ] } [/block] [block:api-header] { "type": "basic", "title": "Default Configure Schema" } [/block] Any schema named `default` will be selected unless you override the `schemas.selected.configure` property of your device and set it to the key of the configure schema object. [block:code] { "codes": [ { "code": "{\n \"name\": \"Device A\",\n \"schemas\": {\n \"configure\": {\n \"not-the-default\": { ... }\n },\n \"selected\": {\n \"configure\": \"not-the-default\"\n\t }\n }\n}\n", "language": "json", "name": "Default Example" } ] } [/block] [block:api-header] { "type": "basic", "title": "Reference an external schema" } [/block] Octoblu supports the standard `$ref` capability of JSON Schema. Octoblu will resolve the reference and apply the schema to the device. [block:code] { "codes": [ { "code": "{\n \"schemas\": {\n \"configure\": {\n \"device-a\": {\n \"$ref\": \"https://data-forwarder-mongodb.octoblu.com/schemas/v1/configure.json\"\n }\n }\n }\n}", "language": "json", "name": "External Schema Reference" } ] } [/block] [block:api-header] { "type": "basic", "title": "Reference another device schema" } [/block] Octoblu allows you to reference a schema on another device, provided the device is given proper permissions. You can reference any property of the device and it will be used as the configuration schema. The URI follows this pattern: `meshbludevice://uuid/#/path/to/property`. [block:code] { "codes": [ { "code": "// Device A\n{\n \"name\": \"Device A\",\n \"meshblu\": {\n \"version\": \"2.0.0\",\n\t \"whitelists\": {\n \"discover\": {\n \"view\": [\n { \"uuid\": \"device-b\" }\n ]\n } \n\t }\n },\n \"friendSchemas\": {\n\t \"deviceB\": { ... }\n }\n}\n\n// Device B\n{\n \"name\": \"Device B\",\n \"schemas\": {\n \"configure\": {\n \"device-a\": {\n \"$ref\": \"meshbludevice://device-a/#/friendSchemas/deviceB\"\n }\n }\n }\n}", "language": "json", "name": "Cross-Device Schema Example" } ] } [/block]