Upload
phamdieu
View
226
Download
1
Embed Size (px)
Citation preview
CONTACT [email protected]
Copyright Open Connectivity Foundation, Inc. © 2016-2017.
All Rights Reserved.
OCF Core Specifiation
VERSION 1.0.0 | June 2017Part 1
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 2
Legal Disclaimer 2
3
NOTHING CONTAINED IN THIS DOCUMENT SHALL BE DEEMED AS GRANTING YOU ANY 4
KIND OF LICENSE IN ITS CONTENT, EITHER EXPRESSLY OR IMPLIEDLY, OR TO ANY 5
INTELLECTUAL PROPERTY OWNED OR CONTROLLED BY ANY OF THE AUTHORS OR 6
DEVELOPERS OF THIS DOCUMENT. THE INFORMATION CONTAINED HEREIN IS PROVIDED 7
ON AN "AS IS" BASIS, AND TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, 8
THE AUTHORS AND DEVELOPERS OF THIS SPECIFICATION HEREBY DISCLAIM ALL OTHER 9
WARRANTIES AND CONDITIONS, EITHER EXPRESS OR IMPLIED, STATUTORY OR AT 10
COMMON LAW, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF 11
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. OPEN CONNECTIVITY 12
FOUNDATION, INC. FURTHER DISCLAIMS ANY AND ALL WARRANTIES OF NON-13
INFRINGEMENT, ACCURACY OR LACK OF VIRUSES. 14
The OCF logo is a trademark of Open Connectivity Foundation , Inc. in the United States or other 15
countries. *Other names and brands may be claimed as the property of others. 16
Copyright © 2016-2017 Open Connectivity Foundation, Inc. All rights reserved. 17
Copying or other form of reproduction and/or distribution of these works are strictly prohibited. 18
19
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 3
CONTENTS 20
21
1 Scope ........................................................................................................................... 15 22
2 Normative references .................................................................................................... 15 23
3 Terms, definitions, symbols and abbreviations .............................................................. 18 24
3.1 Terms and definitions ........................................................................................... 18 25
3.2 Symbols and abbreviations ................................................................................... 21 26
3.3 Conventions ......................................................................................................... 22 27
3.4 Data types ............................................................................................................ 22 28
4 Document conventions and organization ....................................................................... 23 29
5 Architecture................................................................................................................... 24 30
5.1 Overview .............................................................................................................. 24 31
5.2 Principle ............................................................................................................... 25 32
5.3 Functional block diagram ...................................................................................... 26 33
5.4 Framework ........................................................................................................... 27 34
5.5 Example Scenario with roles ................................................................................. 27 35
5.6 Example Scenario: Bridging to Non- OCF ecosystem............................................ 28 36
6 Identification and addressing ......................................................................................... 29 37
6.1 Introduction .......................................................................................................... 29 38
6.2 Identification ......................................................................................................... 30 39
Resource identification and addressing ......................................................... 30 40
6.3 Namespace: ......................................................................................................... 31 41
6.4 Network addressing .............................................................................................. 31 42
7 Resource model ............................................................................................................ 31 43
7.1 Introduction .......................................................................................................... 31 44
7.2 Resource .............................................................................................................. 32 45
7.3 Property ............................................................................................................... 33 46
Introduction ................................................................................................... 33 47
Common Properties ....................................................................................... 34 48
7.4 Resource Type ..................................................................................................... 35 49
Introduction ................................................................................................... 35 50
Resource Type Property ................................................................................ 36 51
Resource Type definition ............................................................................... 36 52
Multi-value "rt" Resource ............................................................................... 38 53
7.5 Device Type ......................................................................................................... 38 54
7.6 Interface ............................................................................................................... 39 55
Introduction ................................................................................................... 39 56
Interface Property ......................................................................................... 39 57
Interface methods ......................................................................................... 40 58
7.7 Resource representation ...................................................................................... 52 59
7.8 Structure .............................................................................................................. 52 60
Introduction ................................................................................................... 52 61
Resource Relationships ................................................................................. 52 62
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 4
Collections .................................................................................................... 57 63
7.9 Third (3rd) party specified extensions .................................................................... 60 64
8 CRUDN ......................................................................................................................... 61 65
8.1 Overview .............................................................................................................. 61 66
8.2 CREATE ............................................................................................................... 62 67
CREATE request ........................................................................................... 63 68
Processing by the Server .............................................................................. 63 69
CREATE response ........................................................................................ 63 70
8.3 RETRIEVE ........................................................................................................... 63 71
RETRIEVE request ........................................................................................ 64 72
Processing by the Server .............................................................................. 64 73
RETRIEVE response ..................................................................................... 64 74
8.4 UPDATE ............................................................................................................... 64 75
UPDATE request ........................................................................................... 65 76
Processing by the Server .............................................................................. 65 77
UPDATE response ........................................................................................ 65 78
8.5 DELETE ............................................................................................................... 65 79
DELETE request ........................................................................................... 66 80
Processing by the Server .............................................................................. 66 81
DELETE response ......................................................................................... 66 82
8.6 NOTIFY ................................................................................................................ 66 83
9 Network and connectivity .............................................................................................. 67 84
9.1 Introduction .......................................................................................................... 67 85
9.2 Architecture .......................................................................................................... 67 86
9.3 IPv6 network layer requirements ........................................................................... 68 87
Introduction ................................................................................................... 68 88
IPv6 node requirements ................................................................................ 69 89
10 Endpoint ....................................................................................................................... 69 90
10.1 Endpoint definition ................................................................................................ 69 91
10.2 Endpoint information ............................................................................................. 70 92
Introduction ................................................................................................... 70 93
“ep” ............................................................................................................... 70 94
“pri” ............................................................................................................... 70 95
Endpoint information in "eps" Parameter ....................................................... 71 96
10.3 Endpoint discovery ............................................................................................... 71 97
Introduction ................................................................................................... 71 98
Implicit discovery ........................................................................................... 71 99
Explicit discovery with “/oic/res” response ..................................................... 71 100
10.4 CoAP based Endpoint discovery ........................................................................... 75 101
11 Functional interactions .................................................................................................. 76 102
11.1 Introduction .......................................................................................................... 76 103
11.2 Onboarding, Provisioning and Configuration ......................................................... 76 104
11.3 Resource discovery .............................................................................................. 78 105
Introduction ................................................................................................... 78 106
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 5
Resource based discovery: mechanisms ....................................................... 78 107
Resource based discovery: Information publication process .......................... 80 108
Resource based discovery: Finding information ............................................. 81 109
Resource discovery using “/oic/res” ............................................................... 87 110
Resource directory (RD) based discovery ...................................................... 89 111
11.4 Notification ......................................................................................................... 103 112
Overview ..................................................................................................... 103 113
Observe ...................................................................................................... 103 114
11.5 Device management ........................................................................................... 105 115
Overview ..................................................................................................... 105 116
Diagnostics and maintenance ...................................................................... 105 117
11.6 Scenes ............................................................................................................... 106 118
Introduction ................................................................................................. 106 119
Scenes ........................................................................................................ 106 120
Security considerations ............................................................................... 110 121
11.7 Icons .................................................................................................................. 110 122
Overview ..................................................................................................... 110 123
Resource..................................................................................................... 111 124
11.8 Introspection....................................................................................................... 111 125
Overview ..................................................................................................... 111 126
Usage of introspection................................................................................. 113 127
12 Messaging................................................................................................................... 114 128
12.1 Introduction ........................................................................................................ 114 129
12.2 Mapping of CRUDN to CoAP .............................................................................. 115 130
Overview ..................................................................................................... 115 131
URIs ............................................................................................................ 115 132
CoAP method with request and response .................................................... 115 133
Content-Format negotiation ......................................................................... 117 134
OCF-Content-Format-Version information ................................................... 118 135
Content-Format policy ................................................................................. 118 136
CRUDN to CoAP response codes ................................................................ 119 137
CoAP block transfer .................................................................................... 119 138
12.3 CoAP serialization over TCP .............................................................................. 120 139
12.4 Payload Encoding in CBOR ................................................................................ 121 140
13 Security ....................................................................................................................... 121 141
Annex A (informative) Operation Examples ........................................................................ 123 142
A.1 Introduction ........................................................................................................ 123 143
A.2 When at home: From smartphone turn on a single light ...................................... 123 144
A.3 GroupAction execution ....................................................................................... 124 145
A.4 When garage door opens, turn on lights in hall; also notify smartphone .............. 124 146
A.5 Device management ........................................................................................... 124 147
Annex B (informative) OCF interaction scenarios and deployment models ......................... 126 148
B.1 OCF interaction scenarios .................................................................................. 126 149
B.2 Deployment model .............................................................................................. 127 150
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 6
Annex C (informative) Other Resource Models and OCF Mapping ..................................... 129 151
C.1 Multiple resource models .................................................................................... 129 152
C.2 OCF approach for support of multiple resource models ....................................... 129 153
C.3 Resource model indication.................................................................................. 130 154
C.4 An Example Profile (IPSO profile) ....................................................................... 130 155
C.4.1 Conceptual equivalence .............................................................................. 130 156
Annex D (normative) Resource Type definitions ................................................................ 133 157
D.1 List of Resource Type definitions ........................................................................ 133 158
D.2 OCF Collection ................................................................................................... 134 159
D.2.1 Introduction ................................................................................................. 134 160
D.2.2 Example URI ............................................................................................... 134 161
D.2.3 Resource Type ............................................................................................ 134 162
D.2.4 RAML Definition .......................................................................................... 134 163
D.2.5 Property Definition ...................................................................................... 138 164
D.2.6 CRUDN behavior ......................................................................................... 140 165
D.2.7 Referenced JSON schemas ......................................................................... 140 166
D.2.8 oic.oic-link-schema.json .............................................................................. 140 167
D.3 Device Configuration .......................................................................................... 142 168
D.3.1 Introduction ................................................................................................. 142 169
D.3.2 Example URI ............................................................................................... 142 170
D.3.3 Resource Type ............................................................................................ 142 171
D.3.4 RAML Definition .......................................................................................... 142 172
D.3.5 Property Definition ...................................................................................... 146 173
D.3.6 CRUDN behavior ......................................................................................... 147 174
D.4 Platform Configuration ........................................................................................ 147 175
D.4.1 Introduction ................................................................................................. 147 176
D.4.2 Example URI ............................................................................................... 147 177
D.4.3 Resource Type ............................................................................................ 147 178
D.4.4 RAML Definition .......................................................................................... 147 179
D.4.5 Property Definition ...................................................................................... 150 180
D.4.6 CRUDN behavior ......................................................................................... 150 181
D.5 Device ................................................................................................................ 150 182
D.5.1 Introduction ................................................................................................. 150 183
D.5.2 Wellknown URI ............................................................................................ 150 184
D.5.3 Resource Type ............................................................................................ 150 185
D.5.4 RAML Definition .......................................................................................... 150 186
D.5.5 Property Definition ...................................................................................... 153 187
D.5.6 CRUDN behavior ......................................................................................... 153 188
D.6 Maintenance ....................................................................................................... 153 189
D.6.1 Introduction ................................................................................................. 153 190
D.6.2 Wellknown URI ............................................................................................ 154 191
D.6.3 Resource Type ............................................................................................ 154 192
D.6.4 RAML Definition .......................................................................................... 154 193
D.6.5 Property Definition ...................................................................................... 156 194
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 7
D.6.6 CRUDN behavior ......................................................................................... 156 195
D.7 Platform .............................................................................................................. 156 196
D.7.1 Introduction ................................................................................................. 156 197
D.7.2 Wellknown URI ............................................................................................ 156 198
D.7.3 Resource Type ............................................................................................ 156 199
D.7.4 RAML Definition .......................................................................................... 157 200
D.7.5 Property Definition ...................................................................................... 158 201
D.7.6 CRUDN behavior ......................................................................................... 159 202
D.8 Ping .................................................................................................................... 159 203
D.8.1 Introduction ................................................................................................. 159 204
D.8.2 Wellknown URI ............................................................................................ 159 205
D.8.3 Resource Type ............................................................................................ 160 206
D.8.4 RAML Definition .......................................................................................... 160 207
D.8.5 Property Definition ...................................................................................... 162 208
D.8.6 CRUDN behavior ......................................................................................... 162 209
D.9 Discoverable Resources Baseline Interface ........................................................ 162 210
D.9.1 Introduction ................................................................................................. 162 211
D.9.2 Wellknown URI ............................................................................................ 162 212
D.9.3 Resource Type ............................................................................................ 162 213
D.9.4 RAML Definition .......................................................................................... 162 214
D.9.5 Property Definition ...................................................................................... 164 215
D.9.6 CRUDN behavior ......................................................................................... 164 216
D.10 Discoverable Resources Link List interface ......................................................... 164 217
D.10.1 Introduction ................................................................................................. 164 218
D.10.2 Wellknown URI ............................................................................................ 164 219
D.10.3 Resource Type ............................................................................................ 165 220
D.10.4 RAML Definition .......................................................................................... 165 221
D.10.5 Property Definition ...................................................................................... 166 222
D.10.6 CRUDN behavior ......................................................................................... 167 223
D.10.7 Referenced JSON schemas ......................................................................... 167 224
D.10.8 oic.oic-link-schema.json .............................................................................. 167 225
D.11 Scenes (Top level) ............................................................................................. 169 226
D.11.1 Introduction ................................................................................................. 169 227
D.11.2 Example URI ............................................................................................... 170 228
D.11.3 Resource Type ............................................................................................ 170 229
D.11.4 RAML Definition .......................................................................................... 170 230
D.11.5 Property Definition ...................................................................................... 171 231
D.11.6 CRUDN behavior ......................................................................................... 172 232
D.12 Scene Collections ............................................................................................... 172 233
D.12.1 Introduction ................................................................................................. 172 234
D.12.2 Example URI ............................................................................................... 172 235
D.12.3 Resource Type ............................................................................................ 172 236
D.12.4 RAML Definition .......................................................................................... 172 237
D.12.5 Property Definition ...................................................................................... 176 238
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 8
D.12.6 CRUDN behavior ......................................................................................... 177 239
D.13 Scene Member ................................................................................................... 177 240
D.13.1 Introduction ................................................................................................. 177 241
D.13.2 Example URI ............................................................................................... 177 242
D.13.3 Resource Type ............................................................................................ 177 243
D.13.4 RAML Definition .......................................................................................... 177 244
D.13.5 Property Definition ...................................................................................... 179 245
D.13.6 CRUDN behavior ......................................................................................... 179 246
D.14 Resource directory resource ............................................................................... 179 247
D.14.1 Introduction ................................................................................................. 179 248
D.14.2 Wellknown URI ............................................................................................ 179 249
D.14.3 Resource Type ............................................................................................ 179 250
D.14.4 RAML Definition .......................................................................................... 179 251
D.14.5 Property Definition ...................................................................................... 184 252
D.14.6 CRUDN behavior ......................................................................................... 185 253
D.15 Icon .................................................................................................................... 186 254
D.15.1 Introduction ................................................................................................. 186 255
D.15.2 Example URI ............................................................................................... 186 256
D.15.3 Resource Type ............................................................................................ 186 257
D.15.4 RAML Definition .......................................................................................... 186 258
D.15.5 Property Definition ...................................................................................... 187 259
D.15.6 CRUDN behavior ......................................................................................... 187 260
D.16 Introspection Resource ....................................................................................... 187 261
D.16.1 Introduction ................................................................................................. 187 262
D.16.2 Example URI ............................................................................................... 187 263
D.16.3 Resource Type ............................................................................................ 187 264
D.16.4 RAML Definition .......................................................................................... 187 265
D.16.5 Property Definition ...................................................................................... 189 266
D.16.6 CRUDN behavior ......................................................................................... 189 267
Annex E (informative) Swagger2.0 definitions ................................................................... 190 268
E.1 Icon .................................................................................................................... 190 269
E.1.1 Introduction ................................................................................................. 190 270
E.1.2 Example URI ............................................................................................... 190 271
E.1.3 Resource Type ............................................................................................ 190 272
E.1.4 Swagger2.0 Definition ................................................................................. 190 273
E.1.5 Property Definition ...................................................................................... 192 274
E.1.6 CRUDN behavior ......................................................................................... 192 275
E.2 Introspection Resource ....................................................................................... 193 276
E.2.1 Introduction ................................................................................................. 193 277
E.2.2 Example URI ............................................................................................... 193 278
E.2.3 Resource Type ............................................................................................ 193 279
E.2.4 Swagger2.0 Definition ................................................................................. 193 280
E.2.5 Property Definition ...................................................................................... 195 281
E.2.6 CRUDN behavior ......................................................................................... 195 282
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 9
E.3 OCF Collection ................................................................................................... 196 283
E.3.1 Introduction ................................................................................................. 196 284
E.3.2 Example URI ............................................................................................... 196 285
E.3.3 Resource Type ............................................................................................ 196 286
E.3.4 Swagger2.0 Definition ................................................................................. 196 287
E.3.5 Property Definition ...................................................................................... 208 288
E.3.6 CRUDN behavior ......................................................................................... 211 289
E.4 Platform Configuration ........................................................................................ 212 290
E.4.1 Introduction ................................................................................................. 212 291
E.4.2 Example URI ............................................................................................... 212 292
E.4.3 Resource Type ............................................................................................ 212 293
E.4.4 Swagger2.0 Definition ................................................................................. 212 294
E.4.5 Property Definition ...................................................................................... 215 295
E.4.6 CRUDN behavior ......................................................................................... 216 296
E.5 Device Configuration .......................................................................................... 216 297
E.5.1 Introduction ................................................................................................. 216 298
E.5.2 Example URI ............................................................................................... 216 299
E.5.3 Resource Type ............................................................................................ 216 300
E.5.4 Swagger2.0 Definition ................................................................................. 216 301
E.5.5 Property Definition ...................................................................................... 220 302
E.5.6 CRUDN behavior ......................................................................................... 221 303
E.6 Device ................................................................................................................ 221 304
E.6.1 Introduction ................................................................................................. 221 305
E.6.2 Wellknown URI ............................................................................................ 221 306
E.6.3 Resource Type ............................................................................................ 221 307
E.6.4 Swagger2.0 Definition ................................................................................. 221 308
E.6.5 Property Definition ...................................................................................... 224 309
E.6.6 CRUDN behavior ......................................................................................... 225 310
E.7 Maintenance ....................................................................................................... 225 311
E.7.1 Introduction ................................................................................................. 225 312
E.7.2 Wellknown URI ............................................................................................ 225 313
E.7.3 Resource Type ............................................................................................ 225 314
E.7.4 Swagger2.0 Definition ................................................................................. 226 315
E.7.5 Property Definition ...................................................................................... 228 316
E.7.6 CRUDN behavior ......................................................................................... 228 317
E.8 Platform .............................................................................................................. 228 318
E.8.1 Introduction ................................................................................................. 228 319
E.8.2 Wellknown URI ............................................................................................ 228 320
E.8.3 Resource Type ............................................................................................ 229 321
E.8.4 Swagger2.0 Definition ................................................................................. 229 322
E.8.5 Property Definition ...................................................................................... 231 323
E.8.6 CRUDN behavior ......................................................................................... 232 324
E.9 Ping .................................................................................................................... 232 325
E.9.1 Introduction ................................................................................................. 232 326
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 10
E.9.2 Wellknown URI ............................................................................................ 233 327
E.9.3 Resource Type ............................................................................................ 233 328
E.9.4 Swagger2.0 Definition ................................................................................. 233 329
E.9.5 Property Definition ...................................................................................... 235 330
E.9.6 CRUDN behavior ......................................................................................... 235 331
E.10 Resource directory resource ............................................................................... 235 332
E.10.1 Introduction ................................................................................................. 235 333
E.10.2 Wellknown URI ............................................................................................ 235 334
E.10.3 Resource Type ............................................................................................ 235 335
E.10.4 Swagger2.0 Definition ................................................................................. 235 336
E.10.5 Property Definition ...................................................................................... 243 337
E.10.6 CRUDN behavior ......................................................................................... 244 338
E.11 Discoverable Resources ..................................................................................... 244 339
E.11.1 Introduction ................................................................................................. 244 340
E.11.2 Wellknown URI ............................................................................................ 244 341
E.11.3 Resource Type ............................................................................................ 244 342
E.11.4 Swagger2.0 Definition ................................................................................. 244 343
E.11.5 Property Definition ...................................................................................... 251 344
E.11.6 CRUDN behavior ......................................................................................... 253 345
E.12 Scenes ............................................................................................................... 253 346
E.12.1 Introduction ................................................................................................. 253 347
E.12.2 Example URI ............................................................................................... 253 348
E.12.3 Resource Type ............................................................................................ 253 349
E.12.4 Swagger2.0 Definition ................................................................................. 253 350
E.12.5 Property Definition ...................................................................................... 270 351
E.12.6 CRUDN behavior ......................................................................................... 273 352
353
354
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 11
355
Figures 356
357
Figure 1: Architecture - concepts .......................................................................................... 25 358
Figure 2: Functional block diagram ....................................................................................... 26 359
Figure 3: Communication layering model .............................................................................. 27 360
Figure 4: Example illustrating the Roles ............................................................................... 28 361
Figure 5: Framework - Architecture Detail ............................................................................. 28 362
Figure 6: Server bridging to Non- OCF device ...................................................................... 29 363
Figure 7: Example of a Resource .......................................................................................... 33 364
Figure 8: Example - "Heater" Resource (for illustration only) ................................................ 50 365
Figure 9: Example - Actuator Interface ................................................................................. 50 366
Figure 10: Example of a Link ................................................................................................ 52 367
Figure 11: Example of distinct Links ..................................................................................... 52 368
Figure 12: Example of use of anchor in Link ......................................................................... 53 369
Figure 13: Example of “eps Parameter ................................................................................. 56 370
Figure 14: List of Links in a Resource ................................................................................... 57 371
Figure 15: Example showing Collection and Links ................................................................ 59 372
Figure 16. CREATE operation .............................................................................................. 63 373
Figure 17. RETRIEVE operation ........................................................................................... 64 374
Figure 18. UPDATE operation .............................................................................................. 65 375
Figure 19. DELETE operation ............................................................................................... 66 376
Figure 20. High Level Network & Connectivity Architecture ................................................... 68 377
Figure 21: Example of "ep" ................................................................................................... 70 378
Figure 22: Example of Link with "eps" Parameter .................................................................. 71 379
Figure 23: Example of “/oic/res” with Endpoint information ................................................... 75 380
Figure 24. Resource based discovery: Information publication process ................................. 81 381
Figure 25. Resource based discovery: Finding information .................................................. 81 382
Figure 26. Indirect discovery of resource by resource directory ............................................ 90 383
Figure 27. RD discovery and RD supported query of resources support ................................ 92 384
Figure 28. Resource Direction Deployment Scenarios .......................................................... 93 385
Figure 29. Example of POST request payload ...................................................................... 97 386
Figure 30. Example of POST response payload .................................................................... 98 387
Figure 31. Example of DELETE request with "di" or "ins" query ............................................ 99 388
Figure 32. Observe Mechanism .......................................................................................... 104 389
Figure 33 Generic scene resource structure ....................................................................... 107 390
Figure 34 Interactions to check Scene support and setup of specific scenes ...................... 108 391
Figure 35 Client interactions on a specific scene ................................................................ 109 392
Figure 36 Interaction overview due to a Scene change ....................................................... 110 393
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 12
Figure 37 Interactions to check Introspection support and download the Introspection 394
Device Data. ....................................................................................................................... 114 395
Figure 38 Content-Format Policy ........................................................................................ 119 396
Figure 39. When at home: from smartphone turn on a single light ....................................... 124 397
Figure 40. Device management (maintenance) ................................................................... 125 398
Figure 41. Direct interaction between Server and Client ..................................................... 126 399
Figure 42. Interaction between Client and Server using another Server .............................. 126 400
Figure 43. Interaction between Client and Server using Intermediary .................................. 126 401
Figure 44. Interaction between Client and Server using support from multiple Servers and 402
Intermediary ....................................................................................................................... 127 403
Figure 45. Example of Devices ........................................................................................... 127 404
405
406
407
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 13
Tables 408
409
Table 1. Additional OCF Types ............................................................................................. 22 410
Table 2. Name Property Definition ........................................................................................ 35 411
Table 3. Resource Identity Property Definition ...................................................................... 35 412
Table 4. Resource Type Common Property definition ........................................................... 36 413
Table 5. Example foobar Resource Type .............................................................................. 37 414
Table 6. Example foobar properties ...................................................................................... 37 415
Table 7. Resource Interface Property definition .................................................................... 39 416
Table 8. OCF standard Interfaces ......................................................................................... 40 417
Table 9. Common Properties for Collections (in addition to Common Properties defined in 418
section 7.3.2) ....................................................................................................................... 60 419
Table 10. 3rd party defined Resource elements ................................................................... 61 420
Table 11. Parameters of CRUDN messages ......................................................................... 62 421
Table 12. “ep” value for Transport Protocol Suite .................................................................. 70 422
Table 13. List of Core Resources ......................................................................................... 76 423
Table 14. Configuration Resource ........................................................................................ 76 424
Table 15. “oic.wk.con” Resource Type definition ................................................................... 77 425
Table 16. “oic.wk.con.p” Resource Type definition ................................................................ 78 426
Table 17. Mandatory discovery Core Resources ................................................................... 82 427
Table 18. “oic.wk.res” Resource Type definition ................................................................... 83 428
Table 19. Protocol scheme registry ....................................................................................... 83 429
Table 20. “oic.wk.d” Resource Type definition ...................................................................... 84 430
Table 21. “oic.wk.p” Resource Type definition ...................................................................... 86 431
Table 22. “oic.wk.rd” Resource Type definition ..................................................................... 90 432
Table 23. “oic.wk.rd” Properties ............................................................................................ 91 433
Table 24: Selection parameters ............................................................................................ 94 434
Table 25. Optional diagnostics and maintenance device management Core Resources ...... 105 435
Table 26. “oic.wk.mnt” Resource Type definition ................................................................. 106 436
Table 27 list of Resource Types for Scenes ........................................................................ 110 437
Table 28. Optional Icon Core Resource .............................................................................. 111 438
Table 29. “oic.r.icon” Resource Type definition ................................................................... 111 439
Table 30. Introspection Resource ....................................................................................... 113 440
Table 31. “oic.wk.introspection” Resource Type definition .................................................. 113 441
Table 32. CoAP request and response ............................................................................... 115 442
Table 33. OCF Content-Formats ......................................................................................... 117 443
Table 34. OCF-Content-Format-Version and OCF-Accept-Content-Format-Version Option 444
Numbers ............................................................................................................................. 118 445
Table 35. OCF-Accept-Content-Format-Version and the OCF-Content-Format-Version 446
Representation ................................................................................................................... 118 447
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 14
Table 36. Examples of OCF-Content-Format-Version and OCF-Accept-Content-Format-448
Version Representation ...................................................................................................... 118 449
Table 37. Ping resource ..................................................................................................... 120 450
Table 38. “oic.wk.ping” Resource Type definition ................................................................ 121 451
Table 39. oic.example.light Resource Type definition ......................................................... 123 452
Table 40. oic.example.garagedoor Resource Type definition .............................................. 123 453
Table 41. Light control Resource Type definition ................................................................ 131 454
Table 42. Light control Resource Type definition ................................................................ 131 455
Table 43. Alphabetized list of core resources ..................................................................... 133 456
457
458
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 15
1 Scope 459
The OCF specifications are divided into two sets of documents: 460
Core Specification documents: The Core Specification documents specify the Framework, i.e., 461
the OCF core architecture, interfaces, protocols and services to enable OCF profiles 462
implementation for Internet of Things (IoT) usages and ecosystems. 463
Vertical Profiles Specification documents: The Vertical Profiles Specification documents 464
specify the OCF profiles to enable IoT usages for different market segments such as smart 465
home, industrial, healthcare, and automotive. The Application Profiles Specification is built 466
upon the interfaces and network security of the OCF core architecture defined in the Core 467
Specification. 468
This document is the OCF Core specification which specifies the Framework and core architecture. 469
470
2 Normative references 471
The following documents, in whole or in part, are normatively referenced in this document and are 472
indispensable for its application. For dated references, only the edition cited applies. For undated 473
references, the latest edition of the referenced document (including any amendments) applies. 474
ISO 8601, Data elements and interchange formats – Information interchange –Representation of 475
dates and times, International Standards Organization, December 3, 2004 476
IEEE 754, IEEE Standard for Floating-Point Arithmetic, August 2008 477
IETF RFC 1981, Path MTU Discovery for IP version 6, August 1996 478
https://tools.ietf.org/rfc/rfc1981.txt 479
IETF RFC 2460, Internet Protocol, version 6 (IPv6), December, 1998 480
https://tools.ietf.org/rfc/rfc2460.txt 481
IETF RFC 2616, Hypertext Transfer Protocol – HTTP/1.1, June 1999. 482
http://www.ietf.org/rfc/rfc2616.txt 483
IETF RFC 3810, Multicast Listener Discovery Version 2 (MLDv2) for IPv6 , June 2004 484
http://www.ietf.org/rfc/rfc3810.txt 485
IETF RFC 3986, Uniform Resource Identifier (URI): General Syntax, January 2005 . 486
http://www.ietf.org/rfc/rfc3986.txt 487
IETF RFC 4122, A Universally Unique IDentifier (UUID) URN Namespace , July 2005 488
http://www.ietf.org/rfc/rfc4122.txt 489
IETF RFC 4287, The Atom Syndication Format, December 2005, 490
http://www.ietf.org/rfc/rfc4287.txt 491
IETF RFC 4193, Unique Local IPv6 Unicast Addresses , October 2005 492
http://www.ietf.org/rfc/rfc4193.txt 493
IETF RFC 4291, IP Version 6 Addressing Architecture, February 2006 494
http://www.ietf.org/rfc/rfc4291.txt 495
IETF RFC 4443, Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 496
(IPv6) Specification, March 2006 497
http://www.ietf.org/rfc/rfc4443.txt 498
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 16
IETF RFC 4861, Neighbor Discovery for IP version 6 (IPv6) , September 2007 499
http://www.ietf.org/rfc/rfc4861.txt 500
IETF RFC 4862, IPv6 Stateless Address Autoconfiguration , September 2007 501
http://www.ietf.org/rfc/rfc4862.txt 502
IETF RFC 4941, Privacy Extensions for Stateless Address Autoconfiguration in IPv6 , September 503
2007 504
http://www.ietf.org/rfc/rfc4941.txt 505
IETF RFC 4944, Transmission of IPv6 Packets over IEEE 802.15.4 Networks , September 2007 506
http://www.ietf.org/rfc/rfc4944.txt 507
IETF RFC 5646, Tags for Identifying Languages, September 2009 508
http://www.ietf.org/rfc/rfc5646.txt 509
IETF RFC 5988, Web Linking: General Syntax, October 2010 510
http://www.ietf.org/rfc/rfc5988.txt 511
IETF RFC 6434, IPv6 Node Requirements, December 2011 512
http://www.ietf.org/rfc/rfc6434.txt 513
IETF RFC 6455, The WebSocket Protocol, December 2011 514
https://www.ietf.org/rfc/rfc6455.txt 515
IETF RFC 6573, The Item and Collection Link Relations , April 2012 516
http://www.ietf.org/rfc/rfc6573.txt 517
IETF RFC 6690, Constrained RESTful Environments (CoRE) Link Format , August 2012 518
http://www.ietf.org/rfc/rfc6690.txt 519
IETF RFC 6762, Multicast DNS February 2013 520
http://www.ietf.org/rfc/rfc6762.txt 521
IETF RFC 6763, DNS-Based Service Discovery , February 2013 522
http://www.ietf.org/rfc/rfc6763.txt 523
IETF RFC 6775, Neighbor Discovery Optimization for IPv6 over Low-Power Wireless Personal 524
Area Networks (6LoWPANs), November 2012 525
http://www.ietf.org/rfc/rfc6775.txt 526
IETF RFC 7049, Concise Binary Object Representation (CBOR) , October 2013 527
http://www.ietf.org/rfc/rfc7049.txt 528
IETF RFC 7084, Basic Requirements for IPv6 Customer Edge Routers, November 2013 529
http://www.ietf.org/rfc/rfc7084.txt 530
IETF RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format , March 2014 531
http://tools.ietf.org/rfc/rfc7159.txt 532
IETF RFC 7252, The Constrained Application Protocol (CoAP) , June 2014 533
http://tools.ietf.org/rfc/rfc7252.txt 534
IETF RFC 7301, Transport Layer Security (TLS) Application-Layer Protocol Negotiation 535
Extension, July 2014 536
https://tools.ietf.org/html/rfc7301 537
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 17
IETF RFC 7428, Transmission of IPv6 Packets over ITU-T G.9959 Networks, February 2015 538
http://www.ietf.org/rfc/rfc7428.txt 539
IETF RFC 7641, Observing Resources in the Constrained Application Protocol 540
(CoAP), September 2015 541
https://tools.ietf.org/html/rfc7641 542
IETF RFC 7668, IPv6 over BLUETOOTH(r) Low Energy, October 2015 543
https://tools.ietf.org/html/rfc7668 544
IETF RFC 7721, Security and Privacy Considerations for IPv6 Address Generation Mechanisms , 545
March 20016 546
https://tools.ietf.org/html/rfc7721 547
IETF RFC 7959, Block-Wise Transfers in the Constrained Application Protocol (CoAP) , August 548
2016 549
https://tools.ietf.org/html/rfc7959 550
IETF draft-ietf-core-coap-tcp-tls-07, CoAP over TCP, TLS, and WebSockets , June 10 2015 551
https://datatracker.ietf.org/doc/draft-ietf-core-coap-tcp-tls/ 552
ECMA-4-4, The JSON Data Interchange Format, October 2013. 553
http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf 554
OCF Security, Open Connectivity Foundation Security Capabilities, Version 1.0, 555
IANA IPv6 Multicast Address Space Registry 556
http://www.iana.org/assignments/ipv6-multicast-addresses/ipv6-multicast-addresses.xhtml 557
IANA Media Types Assignment, March 2017 558
http://www.iana.org/assignments/media-types/media-types.xhtml 559
560
561
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 18
OpenAPI specification, fka Swagger RESTful API Documentation Specification 562
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md 563
W3C XML character escaping, Extensible Markup Language (XML) 1.0, November 2008 564
http://www.w3.org/TR/2008/REC-xml-20081126/#syntax 565
3 Terms, definitions, symbols and abbreviations 566
3.1 Terms and definitions 567
568
Client 569
a logical entity that accesses a Resource on a Server 570
571
Collection 572
a Resource that contains zero or more Links 573
574
Configuration Source 575
a cloud or service network or a local read-only file which contains and provides 576
configuration related information to the Devices 577
578
Core Resources 579
those Resources that are defined in this specification 580
581
Default Interface 582
an Interface used to generate the response when an Interface is omitted in a request 583
584
Device 585
a logical entity that assumes one or more Roles (e.g., Client, Server) 586
Note 1 to entry: More than one Device can exist on a physical platform. 587
588
Device Type 589
a uniquely named definition indicating a minimum set of Resource Types that a Device supports 590
Note 1 to entry: A Device Type provides a hint about what the Device is, such as a light or a fan, for use during 591 Resource discovery. 592
593
Endpoint 594
the source or destination of a request and response messages for a given Transport Protocol Suite 595
Note 1 to entry: Example of a Transport Protocol Suite would be CoAP over UDP over IPv6. 596
597
Entity 598
an aspect of the physical world that is exposed through a Device 599
Note 1 to entry: Example of an entity is an LED. 600
601
Framework 602
a set of related functionalities and interactions defined in this specification, which enable 603
interoperability across a wide range of networked devices, including IoT 604
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 19
605
Interface 606
provides a view and permissible responses on a Resource 607
3.1.12 608
Introspection 609
mechanism to determine the capabilities of the hosted Resources of a Device 610
3.1.13 611
Introspection Device Data 612
data that describes the payloads per implemented method of the Resources that makes up the 613
Device 614
Note 1 to entry: See section 11.8 for all requirements and exceptions 615
616
Links 617
extends typed web links according to IETF RFC 5988 618
619
Non-OCF Device 620
A device which does not comply with the OCF Device requirements 621
622
Notification 623
the mechanism to make a Client aware of resource state changes in a Resource 624
625
Observe 626
the act of monitoring a Resource by sending a RETRIEVE request which is cached by the Server 627
hosting the Resource and reprocessed on every change to that Resource 628
629
Parameter 630
an element that provides metadata about a Resource referenced by the target URI of a Link 631
632
Partial UPDATE 633
an UPDATE request to a Resource that includes a subset of the Properties that are visible via the 634
Interface being applied for the Resource Type 635
636
Platform 637
a physical device containing one or more Devices 638
639
Remote Access Endpoint (RAE) Client 640
a Client which supports XMPP functionality in order to access a Server from a remote location 641
642
Remote Access Endpoint (RAE) Server 643
a Server which supports XMPP and can publish its resource(s) to an XMPP server in the cloud, 644
thus becoming remotely addressable and accessible 645
Note 1 to entry: An RAE Server also supports ICE/STUN/TURN. 646
647
Resource 648
represents an Entity modelled and exposed by the Framework 649
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 20
650
Resource Directory 651
a set of descriptions of Resources where the actual Resources are held on Servers external to the 652
Device hosting the Resource Directory, allowing lookups to be performed for those resources 653
Note 1 to entry: This functionality can be used by sleeping Servers or Servers that choose not to listen/respond to 654 multicast requests directly. 655
656
Resource Interface 657
a qualification of the permitted requests on a Resource 658
659
Resource Property 660
a significant aspect or parameter of a resource, including metadata, that is exposed through the 661
Resource 662
663
Resource Type 664
a uniquely named definition of a class of Resource Properties and the interactions that are 665
supported by that class 666
Note 1 to entry: Each Resource has a Property “rt” whose value is the unique name of the Resource Type. 667
668
Scene 669
a static entity that stores a set of defined Resource property values for a collection of Resources 670
Note 1 to entry: A Scene is a prescribed setting of a set of resources with each having a predetermined value for the 671 property that has to change. 672
673
Scene Collection 674
a collection Resource that contains an enumeration of possible Scene Values and the current 675
Scene Value 676
Note 1 to entry: The member values of the Scene collection Resource are Scene Members. 677
678
Scene Member 679
a Resource that contains mappings of Scene Values to values of a property in the resource 680
681
Scene Value 682
a Scene enumerator representing the state in which a Resource can be 683
684
Server 685
a Device with the role of providing resource state information and facilitating remote interaction 686
with its resources 687
Note 1 to entry: A Server can be implemented to expose non-OCF Device resources to Clients (section 5.6) 688
689
Vertical Resource Type 690
a Resource Type in a vertical domain specification 691
Note 1 to entry: An example of a Vertical Resource Type would be “oic.r.switch.binary”. 692
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 21
3.2 Symbols and abbreviations 693
694
ACL 695
Access Control List 696
Note 1 to entry: The details are defined in OCF Security. 697
698
CBOR 699
Concise Binary Object Representation 700
701
CoAP 702
Constrained Application Protocol 703
704
EXI 705
Efficient XML Interchange 706
707
IRI 708
Internationalized Resource Identifiers 709
710
ISP 711
Internet Service Provider 712
713
JSON 714
JavaScript Object Notation 715
716
mDNS 717
Multicast Domain Name Service 718
719
MTU 720
Maximum Transmission Unit 721
722
NAT 723
Network Address Translation 724
725
OCF 726
Open Connectivity Foundation 727
the organization that created this specification 728
729
RAML 730
RESTful API Modeling Language 731
732
REST 733
Representational State Transfer 734
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 22
735
RESTfull 736
REST-compliant Web services 737
738
URI 739
Uniform Resource Identifier 740
741
URN 742
Uniform Resource Name 743
744
UTC 745
Coordinated Universal Time 746
747
UUID 748
Universal Unique Identifier 749
750
XML 751
Extensible Markup Language 752
3.3 Conventions 753
In this specification a number of terms, conditions, mechanisms, sequences, parameters, events, 754
states, or similar terms are printed with the first letter of each word in uppercase and the rest 755
lowercase (e.g., Network Architecture). Any lowercase uses of these words have the normal 756
technical English meaning. 757
3.4 Data types 758
Resources are defined using data types derived from JSON values as defined in ECMA-4-4. 759
However, a Resource can overload a JSON defined value to specify a particular subset of the 760
JSON value, using validation keywords defined in [JSON Schema Validation]. 761
762
Among other validation keywords, section 7 of [JSON Schema Validation] defines a “format” 763
keyword with a number of format attributes such as “uri” and “date -time”, and a “pattern” keyword 764
with a regular expression that can be used to validate a string. This section defines pat terns that 765
are available for use in describing OCF Resources. The pattern names can be used in specification 766
text where JSON format names can occur. The actual JSON schemas shall use the JSON type 767
and pattern instead. 768
769
For all rows defined in Table 1 below, the JSON type is string. 770
Table 1. Additional OCF Types 771
Pattern Name Pattern Description
csv <none> A comma separated list of values encoded within a string. The value type in the csv is described by the property where the csv is used. For example a csv of integers.
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 23
Note: csv is considered deprecated and an array of strings should be used instead for new Resources.
date ^([0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|2[0-9]|1[0-9]|0[1-9])$
As defined in ISO 8601. The format is [yyyy]-[mm]-[dd].
int64 ^0|(-?[1-9][0-9]{0,18})$ A string instance is valid against this attribute if it contains an integer in the range [-(2**63), (2**63)-1]
Note: IETF RFC 7159 section 6 explains that JSON integers outside the range [-(2**53)+1, (2**53)-1] are not interoperable and so JSON numbers cannot be used for 64-bit numbers.
language-tag ^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$
An IETF language tag formatted according to IETF RFC 5646 section 2.1.
uint64 ^0|([1-9][0-9]{0,19})$ A string instance is valid against this attribute if it contains an integer in the range [0, (2**64)-1]
Also see note for int64
uuid ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
A UUID string representation formatted according to IETF RFC 4122 section 3.
772
Strings shall be encoded as UTF-8 unless otherwise specified. 773
774
In a JSON schema, “maxLength” for a string indicates the maximum number of characters not 775
octets. However, “maxLength” shall also indicate the maximum number of octets. If no “maxLength” 776
is defined for a string, then the maximum length shall be 64 octets. 777
4 Document conventions and organization 778
In this document, features are described as required, recommended, allowed or DEPRECATED as 779
follows: 780
Required (or shall or mandatory)(M). 781
These basic features shall be implemented to comply with Core Architecture. The phrases 782
“shall not”, and “PROHIBITED” indicate behaviour that is prohibited, i.e. that if performed 783
means the implementation is not in compliance. 784
Recommended (or should)(S). 785
These features add functionality supported by Core Architecture and should be implemented. 786
Recommended features take advantage of the capabilities Core Architecture, usually without 787
imposing major increase of complexity. Notice that for compliance testing, if a recommended 788
feature is implemented, it shall meet the specified requirements to be in compliance with these 789
guidelines. Some recommended features could become requirements in the future. The phrase 790
“should not” indicates behaviour that is permitted but not recommended. 791
Allowed (may or allowed)(O). 792
These features are neither required nor recommended by Core Architecture, but if the feature 793
is implemented, it shall meet the specified requirements to be in compliance with these 794
guidelines. 795
DEPRECATED. 796
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 24
Although these features are still described in this specification, they should not be implemented 797
except for backward compatibility. The occurrence of a deprecated feature during operation of 798
an implementation compliant with the current specification has no effect on the 799
implementation’s operation and does not produce any error conditions. Backward compatibility 800
may require that a feature is implemented and functions as specified but it shall never be used 801
by implementations compliant with this specification. 802
Conditionally allowed (CA) 803
The definition or behaviour depends on a condition. If the specified condition is met, then the 804
definition or behaviour is allowed, otherwise it is not allowed. 805
Conditionally required (CR) 806
The definition or behaviour depends on a condition. If the specified condition is met, then the 807
definition or behaviour is required. Otherwise the definition or behaviour is allowed as default 808
unless specifically defined as not allowed. 809
810
Strings that are to be taken literally are enclosed in “double quotes”. 811
Words that are emphasized are printed in italic. 812
5 Architecture 813
5.1 Overview 814
The architecture enables resource based interactions among IoT artefacts, i.e. physical devices 815
or applications. The architecture leverages existing industry standards and technologies and 816
provides solutions for establishing connections (either wireless or wired) and managing the flow of 817
information among devices, regardless of their form factors, operating systems or service providers. 818
Specifically, the architecture provides: 819
A communication and interoperability framework for multiple market segments (Consumer, 820
Enterprise, Industrial, Automotive, Health, etc.), OSs, platforms, modes of communication, 821
transports and use cases 822
A common and consistent model for describing the environment and enabling information 823
and semantic interoperability 824
Common communication protocols for discovery and connectivity 825
Common security and identification mechanisms 826
Opportunity for innovation and product differentiation 827
A scalable solution addressing different device capabilities, applicable to smart devices as 828
well as the smallest connected things and wearable devices 829
The architecture is based on the Resource Oriented Architecture design principles and described 830
in the sections 5.2 through 5.6 respectively. Section 5.2 presents the guiding principles for OCF 831
operations. Section 5.3 defines the functional block diagram and Framework. Section 5.5 provides 832
an example scenario with roles. Section 5.6 provides an example scenario of bridging to non- OCF 833
ecosystem. 834
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 25
5.2 Principle 835
In the architecture, Entities in the physical world (e.g., temperature sensor, an electric light or a 836
home appliance) are represented as resources. Interactions with an Entity are achieved through 837
its resource representations (section 7.7) using operations that adhere to Representational State 838
Transfer (REST) architectural style, i.e., RESTful interactions. 839
The architecture defines the overall structure of the Framework as an information system and the 840
interrelationships of the Entities that make up OCF. Entities are exposed as Resources, with their 841
unique identifiers (URIs) and support interfaces that enable RESTful operations on the Resources. 842
Every RESTful operation has an initiator of the operation (the client) and a responder to the 843
operation (the server). In the Framework, the notion of the client and server is realized through 844
roles (section 5.5). Any Device can act as a Client and initiate a RESTful operation on any Device 845
acting as a Server. Likewise, any Device that exposes Entities as Resources acts as a Server. 846
Conformant to the REST architectural style, each RESTful operation contains all the information 847
necessary to understand the context of the interaction and is driven using a small set of generic 848
operations, i.e., CREATE, RETRIEVE, UPDATE, DELETE and NOTIFY (CRUDN) defined in 849
section 8, which include representations of Resources. 850
Figure 1 depicts the architecture. 851
OIC Device
OIC Client
Protocol specificImplementation ofCRUDN Operations
(e.g. CoAP, HTTP, XMPP)
OIC Device
OIC Server
Protocol specific implementation of
Server
OIC Resource
CRUDN OperationsOIC RESTfulResource Model
Layer
Specific Implementation of
Data Protocol/Messaging
OIC RolesP
roto
col M
app
ing
Entity(e.g. light bulb,
Heart rate monitor)
Resource Mapping
OICAbstractions
COAP Request
E.g. GET /s/data
{ “bulb”: “on” }
COAP Response
852 853
Figure 1: Architecture - concepts 854
855
The architecture is organized conceptually into three major aspects that provide overall separation 856
of concern: resource model, RESTful operations and abstractions. 857
Resource model: The resource model provides the abstractions and concepts required to 858
logically model, and logically operate on the application and its environment. The core resource 859
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 26
model is common and agnostic to any specific application domain such as smart home, 860
industrial or automotive. For example, the resource model defines a Resource which abstracts 861
an Entity and the representation of a Resource maps the Entity’s state. Other resource model 862
concepts can be used to model other aspects, for example behaviour. 863
RESTful operations: The generic CRUDN operations are defined using the RESTful paradigm 864
to model the interactions with a Resource in a protocol and technology agnostic way. The 865
specific communication or messaging protocols are part of the protocol abstraction and 866
mapping of Resources to specific protocols is provided in section 11.8. 867
Abstraction: The abstractions in the resource model and the RESTful operations are mapped 868
to concrete elements using abstraction primitives. An entity handler is used to map an Entity 869
to a Resource and connectivity abstraction primitives are used to map logical RESTful 870
operations to data connectivity protocols or technologies. Entity handlers may also be used to 871
map Resources to Entities that are reached over protocols that are not natively supported by 872
OCF. 873
874
5.3 Functional block diagram 875
The functional block diagram encompasses all the functionalities required for operation. These 876
functionalities are categorized as L2 connectivity, networking, transport, Framework, and 877
application profiles. The functional blocks are depicted in Figure 2 and listed below. 878
879
Figure 2: Functional block diagram 880
L2 connectivity: Provides the functionalities required for establishing physical and data 881
link layer connections (e.g., Wi-FiTM or Bluetooth® connection) to the network. 882
Networking: Provides functionalities required for Devices to exchange data among 883
themselves over the network (e.g., Internet). 884
Transport: Provides end-to-end flow transport with specific QoS constraints. Examples of 885
a transport protocol include TCP and UDP or new Transport protocols under development 886
in the IETF, e.g., Delay Tolerant Networking (DTN). 887
Framework: Provides the core functionalities as defined in this specification. The 888
functional block is the source of requests and responses that are the content of the 889
communication between two Devices. 890
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 27
Application profile: Provides market segment specific data model and functionalities, e.g., 891
smart home data model and functions for the smart home market segment. 892
When two Devices communicate with each other, each functional block in a Device interacts with 893
its counterpart in the peer Device as shown in Figure 3. 894
895
Figure 3: Communication layering model 896
5.4 Framework 897
Framework consists of functions which provide core functionalities for operation. 898
1) Identification and addressing. Defines the identifier and addressing capability. The 899
Identification and addressing function is defined in section 6. 900
2) Discovery. Defines the process for discovering available 901
a) Devices (Endpoint Discovery in section 10) and 902
b) Resources (Resource discovery in section 11.3) 903
3) Resource model. Specifies the capability for representation of Entities in terms of resources 904
and defines mechanisms for manipulating the resources. The resource model function is 905
defined in section 7. 906
4) CRUDN. Provides a generic scheme for the interactions between a Client and Server as 907
defined in section 8. 908
5) Messaging. Provides specific message protocols for RESTful operation, i.e. CRUDN. For 909
example, CoAP is a primary messaging protocol. The messaging function is defined in section 910
11.8. 911
6) Device management. Specifies the discipline of managing the capabilities of a Device, and 912
includes device provisioning and initial setup as well as device monitoring and diagnostics. 913
The device management function is defined in section 11.5. 914
7) Security. Includes authentication, authorization, and access control mechanisms required for 915
secure access to Entities. The security function is defined in section 13. 916
5.5 Example Scenario with roles 917
Interactions are defined between logical entities known as Roles. Three roles are defined: Client, 918
Server and Intermediary. 919
Figure 4 illustrates an example of the Roles in a scenario where a smart phone sends a request 920
message to a thermostat; the original request is sent over HTTP, but is translated into a CoAP 921
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 28
request message by a gateway in between, and then delivered to the thermostat. In this example , 922
the smart phone takes the role of a Client, the gateway takes the role of an Intermediary and the 923
thermostat takes the role of a Server. 924
925
Figure 4: Example illustrating the Roles 926
5.6 Example Scenario: Bridging to Non- OCF ecosystem 927
The use case for this scenario is a display (like a wrist watch) that is used to monitor a heart rate 928
sensor that implements a protocol that is not OCF supported. 929
Figure 5 provides a detailed logical view of the concepts described in Figure 1. 930
931
Figure 5: Framework - Architecture Detail 932
933
The details may be implemented in many ways, for example, by using a Server with an entity 934
handler to interface directly to a non- OCF device as shown in Figure 6. 935
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 29
OIC Device (as OIC Client)
OIC Device(as OIC Server)
Heart Rate SensorDevice
OIC Framework OIC Framework Non-OIC ecosystem
OICNon-OICProtocol
936 937
Figure 6: Server bridging to Non- OCF device 938
On start-up the Server runs the entity handlers which discover the non- OCF systems (e.g., Heart 939
Rate Sensor Device) and create resources for each device or functionality discovered. The entity 940
handler creates a Resource for each discovered device or functionality and binds itself to that 941
Resource. These resources are made discoverable by the Server. 942
Once the resources are created and made discoverable, then the Display Device can discover 943
these resources and operate on them using the mechanisms described in this specification. The 944
requests to a resource on the Server are then in terpreted by the entity handler and forwarded to 945
the non- OCF device using the protocol supported by the non-OCF device. The returned 946
information from the non- OCF device is then mapped to the appropriate response for that resource. 947
6 Identification and addressing 948
6.1 Introduction 949
Facilitating proper and efficient interactions between elements in the Framework, requires a means 950
to identify, name and address these elements. 951
The identifier unambiguously and identif ies an element in a context or domain. The context or 952
domain may be determined by the use or the application. The identifier is expected to be immutable 953
over the lifecycle of that element and is unambiguous within a context or domain. 954
The address is used to define a place, way or means of reaching or accessing the element in order 955
to interact with it. An address may be mutable based on the context. 956
The name is a handle that distinguishes the element from other elements in the framework. The 957
name may be changed over the lifecycle of that element. 958
There may be methods or resolution schemes that allow determining any of these based on the 959
knowledge of one or more of others (e.g. , determine name from address or address from name). 960
Each of these aspects may be defined separately for multiple contexts (e.g., a context could be a 961
layer in a stack). So an address may be a URL for addressing resource and an IP address for 962
addressing at the connectivity layer. In some situations, both these addresses would be required. 963
For example, to do RETRIEVE (section 8.3) operation on a particular resource representation, the 964
client needs to know the address of the target resource and the address of the server through 965
which the resource is exposed. 966
In a context or domain of use, a name or address could be used as identifier or vice versa . For 967
example, a URL could be used as an identifier for a resource and designated as a URI. 968
The remainder of this section discusses the identifier, address and naming from the point of view 969
of the resource model and the interactions to be supported by the resource model. Examples of 970
interactions are the RESTful interactions, i.e. CRUDN operation (section 8) on a resource. Also 971
the mapping of these to transport protocols , e.g., CoAP is described. 972
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 30
6.2 Identification 973
An identifier is unambiguous within the context or domain of use. There are many schemes that 974
may be used to generate an identifier that has the required properties. The identifier may be 975
context-specific in that the identifier is expected to be and guaranteed to be unambiguous only 976
within that context or domain. Identifier may also be context- independent where these identifiers 977
are guaranteed to be unambiguous across all contexts and domains both spatially and temporally. 978
The context-specific identifiers could be defined by simple schemes like monotonic enumeration 979
or may be defined by overloading an address or name, for example an IP address may be an 980
identifier within the private domain behind a gateway in a smart home. On the other hand, context -981
independent identifiers require a stronger scheme that derives universally unique identities , for 982
example any one of the versions of Universally Unique Identifiers (UUIDs). Context independent 983
identifier may also be generated using hierarchy of domains where the root of the hierarchy is 984
identified with a UUID and sub-domains may generate context independent identifier by 985
concatenating context-specific identifiers for that domain to the context-independent identifier of 986
their parent. 987
Resource identification and addressing 988
A resource may be identified using a URI and addressed by the same URI if the URI is a URL. In 989
some cases a resource may need an identifier that is different from a URI; in this case , the resource 990
may have a property whose value is the identifier. When the URI is in the form of a URL, then the 991
URI may be used to address the resource. 992
An OCF URI is based on the general form of a URI as defined in IETF RFC 3986 as follows: 993
<scheme>://<authority>/<path>?<query> 994
Specifically the OCF URI is specified in the following form: 995
ocf://<authority>/<path>?<query> 996
A description of values that each component takes is given below. 997
The scheme for the URI is ‘ocf’. The ‘ocf’ scheme represents the semantics, definitions and use 998
as defined in this document. If a URI has the portion preceding the ‘//’ (double slash) omitted , then 999
the ‘ocf’ scheme shall be assumed. 1000
Each transport binding is responsible for specifying how an OCF URI is converted to a transport 1001
protocol URI before sending over the network by the requestor. Similarly on the receiver side, each 1002
transport binding is responsible for specifying how an OCF URI is converted from a transport 1003
protocol URI before handing over to the resource model layer on the receiver. 1004
The authority of an OCF URI shall be the Device ID ("di") value, as defined in [OCF Security], of 1005
the Server. 1006
The path is a string that unambiguously identifies or references a resource within the context of 1007
the Server. In this version of the specification, a path shall not include pct -encoded non-ASCII 1008
characters or NUL characters. A path shall be preceded by a ‘/’ (slash). The path may have ‘/’ 1009
(slash) separated segments for human readability reasons. In the OCF context, the ‘/’ (slash) 1010
separated segments are treated as a single string that directly references the resources (i.e. a flat 1011
structure) and not parsed as a hierarchy. On the Server, the path or some substring in the path 1012
may be shortened by using hashing or some other scheme provided the resulting reference is 1013
unique within the context of the host. 1014
Once a path is generated, a Client accessing the resource or recipient of the URI should use that 1015
path as an opaque string and should not parse to infer a structure, organization or semantic. 1016
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 31
A query string shall contain a list of <name>=<value> segments (aka “name-value pair”) each 1017
separated by a ‘&’ (ampersand). The query string will be mapped to the appropriate syntax of the 1018
protocol used for messaging. (e.g., CoAP). 1019
A URI may be either 1020
Fully qualified or 1021
Relative 1022
Generation of URI: 1023
A URI may be defined by the Client which is the creator of that resource. Such a URI may be 1024
relative or absolute (fully qualified). A relative URI shall be relative to the Device on which it is 1025
hosted. Alternatively, a URI may be generated by the Server of that resource automatically based 1026
on a pre-defined convention or organization of the resources, based on an interface, based on 1027
some rules or with respect to different roots or bases. 1028
Use of URI: 1029
The absolute path reference of a URI is to be treated as an opaque string and a Client should not 1030
infer any explicit or implied structure in the URI – the URI is simply an address. It is also 1031
recommended that Devices hosting a resource treat the URI of each resource as an opaque string 1032
that addresses only that resource. (e.g. , URI's /a and /a/b are considered as distinct addresses 1033
and resource b cannot be construed as a child of resource a) . 1034
6.3 Namespace: 1035
The relative URI prefix “/oic/” is reserved as a namespace for URIs defined in OCF specifications 1036
and shall not be used for URIs that are not defined in OCF specifications. 1037
6.4 Network addressing 1038
The following are the addresses used in this specification: 1039
IP address 1040
An IP address is used when the device is using an IP configured interface. 1041
When a Device only has the identity information of its peer, a resolution mechanism is needed to 1042
map the identifier to the corresponding address. 1043
7 Resource model 1044
7.1 Introduction 1045
The Resource Model defines concepts and mechanisms that provide consistency and core 1046
interoperability between devices in the OCF ecosystems. The Resource Model concepts and 1047
mechanisms are then mapped to the transport protocols to enable communication between the 1048
devices – each transport provides the communication protocol interoperability. The Resource 1049
Model, therefore, allows for interoperability to be defined independen t of the transports. 1050
In addition, the concepts in the Resource Model support modelling of the primary artefacts and 1051
their relationships to one and another and capture the semantic information required for 1052
interoperability in a context. In this way, OCF goes beyond simple protocol interoperability to 1053
capture the rich semantics required for true interoperability in Wearable and Internet of Things 1054
ecosystems. 1055
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 32
The primary concepts in the Resource Model are: Entity, Resources, Uniform Resource Identifiers 1056
(URI), Resource Types, Properties, Representations, Interfaces, Collections and Links. In addition, 1057
the general mechanisms are CREATE, RETRIEVE, UPDATE, DELETE and NOTIFY. These 1058
concepts and mechanisms may be composed in various ways to define the rich semantics and 1059
interoperability needed for a diverse set of use cases that the OCF framework is applied to. 1060
In the OCF Resource Model framework, an Entity needs to be visible, interacted with or 1061
manipulated, it is represented by an abstraction called a Resource. A Resource encapsulates and 1062
represents the state of an Entity. A Resource is identified, addressed and named using URIs. 1063
Properties are "key=value" pairs and represent state of the Resource. A snapshot of these 1064
Properties is the Representation of the Resource. A specific view of the Representation and the 1065
mechanisms applicable in that view are specified as Interfaces. Interactions with a Resource are 1066
done as Requests and Responses containing Representations. 1067
A resource instance is derived from a Resource Type. The uni-directional relationship between 1068
one Resource and another Resource is defined as a Link. A Resource that has Properties and 1069
Links is a Collection. 1070
A set of Properties can be used to define a state of a Resource. This state may be retrieved or 1071
updated using appropriate Representations respectively in the response from and request to that 1072
Resource. 1073
A Resource (and Resource Type) could represent and be used to expose a capability. Interactions 1074
with that Resource can be used to exercise or use that capability. Such capabilities can be used 1075
to define processes like discovery, management, advertisement etc. For example: “discovery of 1076
resources on a device” can be defined as the retrieval of a representation of a specific resource 1077
where a property or properties have values that describe or reference the resources on the device. 1078
The information for Request or Response with the Representation may be communicated “on the 1079
wire” by serializing using a transfer protocol or encapsulated in the payload of the tr ansport 1080
protocol – the specific method is determined by the normative mapping of the Request or Response 1081
to the transport protocol. See section 11.8 for transport protocols supported. 1082
The RAML definitions used in this document are normative. This also includes that all defined 1083
JSON payloads shall comply with the indicated JSON schema. See Annex D for Resource Types 1084
defined in this specification. 1085
7.2 Resource 1086
A Resource shall be defined by one or more Resource Type(s) – see Annex D for Resource Type. 1087
A request to CREATE a Resource shall specify one or more Resource Types that define that 1088
Resource. 1089
A Resource is hosted in a Device. A Resource shall have a URI as defined in section 6. The URI 1090
may be assigned by the Authority at the creation of the Resource or may be pre -defined by the 1091
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 33
specification of the Resource Type.1092
1093
Figure 7: Example of a Resource 1094
1095
Core Resources are the Resources defined in this specification to enable functional interactions 1096
as defined in section 10 (e.g., Discovery, Device Management, etc). Among the Core Resources, 1097
“/oic/res”, “/oic/p”, and “/oic/d” shall be supported on all Devices. Devices may support other Core 1098
Resources depending on the functional interactions they support. 1099
7.3 Property 1100
Introduction 1101
A Property describes an aspect that is exposed through a Resource including meta-information 1102
related to that resource. 1103
A Property shall have a name i.e. Property Name and a value i.e. Property Value. The Property is 1104
expressed as a key-value pair where key is the Property Name and value the Property Value like 1105
<Property Name> = <Property Value>. For example if the “temperature” Property has a Property 1106
Name “temp” and a Property Value “30F”, then the Property is expressed as “temp=30F”. The 1107
specific format of the Property depends on the encoding scheme. For example, in JSON, Property 1108
is represented as "key": value (e.g., "temp": 30). 1109
In addition, the Property definition shall have a 1110
Value Type – the Value Type defines the values that a Property Value may take. The Value 1111
Type may be a simple data type (e.g. string, Boolean) as defined in section 3.4 or may be a 1112
complex data type defined with a schema. The Value Type may define 1113
o Value Rules define the rules for the set of values that the Property Value may tak e. 1114
Such rules may define the range of values, the min-max, formulas, set of 1115
enumerated values, patterns, conditional values and even dependencies on values 1116
of other Properties. The rules may be used to validate the specific values in a 1117
Property Value and flag errors. 1118
Mandatory – specifies if the Property is mandatory or not for a given Resource Type. 1119
Access modes – specifies whether the Property may be read, written or both. Updates are 1120
equivalent to a write. “r” is used for read and “w” is used for write – both may be specified. 1121
Write does not automatically imply read. 1122
The definition of a Property may include the following additional information – these items are 1123
informative: 1124
Property Title - a human-friendly name to designate the Property; usually not sent over the 1125
wire 1126
Description – descriptive text defining the purpose and expected use of this Property. 1127
/my/resource/example { "rt": ["oic.r.foobar"], "if": ["oic.if.a"],
"value": "foo value" }
Properties
URI
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 34
A Property may be used in the query part of an URI as one criterion for selection of a particular 1128
Resource. This is done by declaring the Property (i.e. <Property Name> = <desired Property 1129
Value>) as one of the segments of the query. In this version of the specification, only ASCII strings 1130
are permitted in query filters, and NUL characters are disallowed in query filters. This means that 1131
only property values with ASCII characters can be matched in a query filter . The Resource is 1132
selected when all the declared Properties in the query match the corresponding Properties in the 1133
full Representation of the target Resource. The full Representation is the snapshot that includes 1134
the union of all Properties in all Resource Types that define the target Resource. If the Property is 1135
declared in the “filter” segment of the query then the declared Property is matched to the 1136
Representation defined by the Interface to isolate certain parts of that Representation. 1137
In general, a property is meaningful only within the resource to which it is associated. However a 1138
base set of properties that may be supported by all Resources, known as Common Properties, 1139
keep their semantics intact across Resources i.e. their “key=value” pair means the same in any 1140
Resource. Detailed tables with the above fields for all common properties are defined in section 1141
7.3.2. 1142
Common Properties 1143
7.3.2.1 Introduction 1144
The Common Properties defined in this section may be specified for all Resources. The following 1145
Properties are defined as Common Properties: “Resource Type”, “Resource Interface”, “Name”, 1146
and “Resource Identity”. 1147
The name of a Common Property shall be unique and shall not be used by other properties. When 1148
defining a new Resource Type, its non-common properties shall not use the name of existing 1149
Common Properties (e.g., "rt", "if", "n", “id”). When defining a new "Common Property", it should 1150
be ensured that its name has not been used by any other properties. The uniqueness of a new 1151
Common Property name can be verified by checking all the Properties of all the existing OCF 1152
defined Resource Types. However, this may become cumbersome as the number of Resource 1153
Types grow. To prevent such name conflicts in the future, OCF may reserve a certain name space 1154
for common property. Potential approaches are (1) a specific prefix (e.g. "oic") may be designated 1155
and the name preceded by the prefix (e.g. "oic.psize") is only for Common Property; (2) the names 1156
consisting of one or two letters are reserved for Common Property and all other Properties shall 1157
have the name with the length larger than the 2 letters; (3) Common Properties may be nested 1158
under specific object to distinguish themselves. 1159
The ability to UPDATE a Common Property (that supports write as an access mode) is restricted 1160
to the “oic.if.rw” (read-write) Interface; thus a Common Property shall be updatable using the read-1161
write Interface if and only if the Property supports write access as defined by the Property definition 1162
and the associated schema for the read-write Interface. 1163
The following Common Properties for all Resources are specified in section 7.3.2.2 through section 1164
7.3.2.6 and summarized as follows: 1165
Resource Type ("rt") – this Property is used to declare the Resource Type of that Resource. 1166
Since a Resource could be define by more than one Resource Type the Property Value of the 1167
Resource Type Property can be used to declare more than one Resource type. For example: 1168
“rt”: [“oic.wk.d”, “oic.d.airconditioner”] declares that the Resource containing this Property is 1169
defined by either the “oic.wk.d” Resource Type or the “oic.d.airconditioner” Resource Type. 1170
See section 7.3.2.3 for details. 1171
Interface ("if") – this Property declares the Interfaces supported by the Resource. The Property 1172
Value of the Interface Property can be multi-valued and lists all the Interfaces supported. See 1173
section 7.3.2.4 for details. 1174
Name ("n") – the Property declares “human-readable” name assigned to the Resource. See 1175
section 7.3.2.5. 1176
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 35
Resource Identity ("id"): its Property Value shall be a unique (across the scope of the host 1177
Server) instance identifier for a specific instance of the Resource. The encoding of this identifier 1178
is device and implementation dependent. See section 7.3.2.6 for details. 1179
7.3.2.2 Property Name and Property Value definitions 1180
The Property Name and Property Value as used in this specification: 1181
Property Name– the key in "key=value” pair. Property Name is case sensitive and its data type 1182
is “string” but only ASCII characters are permitted, and embedded NUL characters are not 1183
permitted. 1184
Property Value – the value in "key=value” pair. Property Value is case sensitive when its data 1185
type is “string”. Any enum values shall be ASCII only. 1186
7.3.2.3 Resource Type 1187
Resource Type Property is specified in section 7.4. 1188
7.3.2.4 Interface 1189
Interface Property is specified in Section 7.5. 1190
7.3.2.5 Name 1191
A human friendly name for the Resource, i.e. a specific resource instance name (e.g., 1192
MyLivingRoomLight), The Name Property is as defined in Table 2 1193
Table 2. Name Property Definition 1194
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Name n string R, W no Human understandable name for the resource.
The ‘Name’ Property is read-write unless otherwise restricted by the Resource Type (i.e. the 1195
Resource Type does not support UPDATE or does not support UPDATE using read -write). 1196
7.3.2.6 Resource Identity 1197
The Resource Identity Property shall be a unique (across the scope of the host Server) instance 1198
identifier for a specific instance of the Resource. The encoding of this identifier is device and 1199
implementation dependent. The Resource Identity Property is as defined in Table 3. 1200
Table 3. Resource Identity Property Definition 1201
1202
Property title Property name
Value type
Value rule Unit Access mode
Mandatory Description
Resource Identity
id string Implementation Dependent
R No Unique identifier of the Resource (over all Resources in the Device)
1203
7.4 Resource Type 1204
Introduction 1205
Resource Type is a class or category of Resources and a Resource is an instance of one or more 1206
Resource Types. 1207
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 36
The Resource Types of a Resource is declared using the Resource Type Common Property as 1208
described in Section 7.3.2.3 or in a Link using the Resource Type Parameter. 1209
A Resource Type may either be pre-defined (Core Resource Types in this specification and Vertical 1210
Resource Types in vertical domain specifications) or in custom definitions by manufacturers, end 1211
users, or developers of Devices (vendor-defined Resource Types). Resource Types and their 1212
definition details may be communicated out of band ( i.e. in documentation) or be defined explicitly 1213
using a meta-language which may be downloaded and used by APIs or applications. OCF has 1214
adopted RAML and JSON Schema as the specification method for OCF’s RESTful interfaces and 1215
Resource definitions. 1216
Every Resource Type shall be identified with a Resource Type ID which shall be represented using 1217
the requirements and ABNF governing the Resource Type attribute in IETF RFC 6690(Section 2 1218
for ABNF and Section 3.1 for requirements) with the caveat that segments are separated by a "." 1219
(period). The entire string represents the Resource Type ID. When defining the ID each segment 1220
may represent any semantics that are appropriate to the Resource Type. For example, each 1221
segment could represent a namespace. Once the ID has been defined, the ID should be used 1222
opaquely and an implementations should not infer any information from the individual segments. 1223
The string "oic", when used as the first segment in the definition of the Resource Type ID, is 1224
reserved for OCF-defined Resource Types. All OCF defined Resource Types are to be registered 1225
with the IANA Core Parameters registry as described also in IETF RFC 6690. 1226
Resource Type Property 1227
A Resource when instantiated or created shall have one or more Resource Types that are the 1228
template for that Resource. The Resource Types that the Resource conforms to shall be declared 1229
using the “rt” Common Property for the Resource. The Property Value for the “rt” Common Property 1230
shall be the list of Resource Type IDs for the Resource Types used as templates (i.e., “rt”=<list of 1231
Resource Type IDs>). 1232
Table 4. Resource Type Common Property definition 1233
Property title Property name
Value type Value rule Unit Access mode
Mandatory Description
Resource type rt array Array of strings, conveying resource Type IDs
R yes The property name rt is as described in IETF RFC 6690
Resource Types may be explicitly discovered or implicitly shared between the user (i.e. Client) and 1234
the host (i.e. Server) of the Resource. 1235
Resource Type definition 1236
Resource Type is specified as follows: 1237
Pre-defined URI (optional) – a pre-defined URI may be specified for a specific Resource Type 1238
in an OCF specification. When a Resource Type has a pre-defined URI, all instances of that 1239
Resource Type shall use only the pre-defined URI. An instance of a different Resource Type 1240
shall not use the pre-defined URI. 1241
Resource Type Title (optional) – a human friendly name to designate the Resource Type. 1242
Resource Type ID – the value of "rt" property which identifies the Resource Type, (e.g., 1243
“oic.wk.p”). 1244
Resource Interfaces – list of the interfaces that may be supported by the Resource Type. 1245
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 37
Resource Properties – definition of all the properties that apply to the Resource Type. The 1246
Resource Type definition shall define whether a property is mandatory, conditional mandatory, 1247
or optional. 1248
Related Resource Types (optional) – the specification of other Resource Types that may be 1249
referenced as part of the Resource Type, applicable to collections. 1250
Mime Types (optional) – mime types supported by the resource inc luding serializations (e.g., 1251
application/cbor, application/json, application/xml). 1252
Table 5 and Table 6 provide an example description of an illustrative foobar Resource Type and 1253
its associated Properties. 1254
Table 5. Example foobar Resource Type 1255
Pre-defined
URI
Resource Type Title
Resource Type ID (“rt” value)
interfaces Description Related Functional Interaction
M/CR/O
none foobar oic.r.foobar “oic.if.a” Example "foobar" resource
Actuation O
Table 6. Example foobar properties 1256
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Resource Type rt array R yes Resource Type
Interface if array R yes Interface
Foo value value string R yes Foo value
1257
An instance of the foobar Resource Type is as shown below 1258
1259
An example schema for the foobar Resource Type is shown below 1260
1261
{
"rt": ["oic.r.foobar"],
"if": ["oic.if.a"],
"value": "foo value"
}
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"properties": {
"rt": {"type": "string"},
"if": {"type": "string"},
"value": {"type": "string"}
},
"required": ["rt", "if", "value"]
}
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 38
Multi-value "rt" Resource 1262
Multi-value "rt" Resource means a Resource with multiple Resource Types. Such a Resource is 1263
associated with multiple Resource Types and so has an "rt" Property Value of multiple Resource 1264
Type IDs (e.g. "rt": ["oic.r.switch.binary", "oic.r.light.brightness"]). The order of the Resource Type 1265
IDs in the “rt” Property Value is meaningless. For example, "rt": ["oic.r.switch.binary", 1266
"oic.r.light.brightness"] and "rt": ["oic.r.light.brightness", "oic.r.switch.binary"] have the same 1267
meaning. 1268
Resource Types for multi-value “rt” Resources shall sat isfy the following conditions. 1269
Property Name – Property Names for each Resource Type shall be unique (within the scope 1270
of the multi-value “rt” Resource) with the exception of Common Properties, otherwise there will 1271
be conflicting Property semantics. If two Resource Types have a Property with the same 1272
Property Name, a multi-value “rt” Resource shall not be composed of these Resource Types. 1273
A multi-value "rt" Resource satisfies all the requirements for each Resource Type and conforms to 1274
the RAML/JSON definitions for each component Resource Type. Thus the mandatory Properties 1275
of a multi-value "rt" Resource shall be the union of all the mandatory Properties of each Resource 1276
Type. For example, mandatory Properties of a Resource with "rt": ["oic.r.switch.binary", 1277
"oic.r.light.brightness"] are "value" and "brightness", where the former is mandatory for 1278
"oic.r.switch.binary" and the latter for "oic.r.light.brightness". 1279
The multi-value “rt” Resource Interface set shall be the union of the sets of interfaces from the 1280
component Resource Types. The Resource Representation in response to a CRUDN action on an 1281
Interface shall be the union of the schemas that are defined for that Interface. The Default Interface 1282
for a multi-value “rt” Resource shall be the baseline Interface ( “oic.if.baseline”) as that is the only 1283
guaranteed common Interface between the Resource Types. 1284
For clarity if each Resource Type supports the same set of Interfaces, then the resultant multi -1285
value "rt" Resource has that same set of Interfaces with a Default Interface of baseline 1286
(“oic.if.baseline”). 1287
An "rt" query for a multi-value "rt" Resource with the Default Interface of "oic.if.a", "oic.if.s", "oic.if.r", 1288
"oic.if.rw" or "oic.if.baseline" is an extension of a generic "rt" query. When a Server receives a 1289
RETRIEVE request for multi-value "rt" Resource with an "rt" query, (i.e. GET 1290
/ResExample?rt=oic.r.foo), the Server should respond only when the query value is an item of the 1291
"rt" Property Value of the target Resource and should send back only the Properties associated 1292
with the query value. For example, upon receiving GET /ResExample?rt=oic.r. switch.binary 1293
targeting a Resource with "rt": ["oic.r.switch.binary", "oic.r.light.brightness"], the Server responds 1294
with only the Properties of oic.r.switch.binary. 1295
1296
7.5 Device Type 1297
A Device Type is a class of Device. Each Device Type defined will include a list of minimum 1298
Resource Types that a device shall implement for that Device Type. A device may expose 1299
additional standard and vendor defined Resource Types beyond the minimum list . The Device 1300
Type is used in Resource discovery as specified in section 11.3.4. 1301
Like a Resource Type, a Device Type can be used in the Resource Type Common Property or in 1302
a Link using the Resource Type Parameter. 1303
A Device Type may either be pre-defined (in vertical domain specifications) or in custom definitions 1304
by manufacturers, end users, or developers of Devices (vendor-defined Device Types). Device 1305
Types and their definition details may be communicated out of band (like in documentation). 1306
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 39
Every Device Type shall be identified with a Resource Type ID using the same syntax constraints 1307
as a Resource Type. 1308
7.6 Interface 1309
Introduction 1310
An Interface provides first a view into the Resource and then defines the requests and responses 1311
permissible on that view of the Resource. So this view provided by an Interface defines the context 1312
for requests and responses on a Resource. Therefore, the same request to a Resource when 1313
targeted to different Interfaces may result in different responses. 1314
An Interface may be defined by either this specification (a Core Interface), the OCF vertical domain 1315
specifications (a “vertical Interface) or manufacturers, end users or developers of Devices (a 1316
“vendor-defined Interface”). 1317
The Interface Property lists all the Interfaces the Resource support. All resources shall have at 1318
least one Interface. The Default Interface shall be defined by an OCF specification and inherited 1319
from the Resource Type definition. The Default Interface associated with all Resource Types 1320
defined in this specification shall be the supported Interface listed first within the applicable 1321
enumeration in the definition of the Resource Type (see Annex D). All Default Interfaces specified 1322
in an OCF specification shall be mandatory. 1323
In addition to any OCF specification defined interface, all Resources shall support the Baseline 1324
Interface (“oic.if.baseline”) as defined in section 7.6.3.2. 1325
When an Interface is to be selected for a Request, it shall be specified as query parameter in the 1326
URI of the Resource in the Request message. If no query parameter is specified, then the Default 1327
Interface shall be used. If the selected Interface is not one of the permitted Interfaces on the 1328
Resource then selecting that Interface is an error. 1329
An Interface may accept more than one media type. An Interface may respond with more than one 1330
media type. The accepted media types may be different from the response media types. The media 1331
types are specified with the appropriate header parameters in the transfer protocol. (NOTE: This 1332
feature has to be used judiciously and is allowed to optimize representations on the wire) Each 1333
Interface shall have at least one media type. 1334
1335
Interface Property 1336
Table 7. Resource Interface Property definition 1337
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Interface if array Array of strings, conveying interfaces
R yes Property to declare the Interfaces supported by a Resource.
The Interfaces supported by a Resource shall be declared using the Interface Common Property 1338
(Table 7) as "if=<array of Interfaces>". The Property Value of an Interface Property shall be a 1339
lower case string with segments separated by a "." (dot). The string "oic", when used as the first 1340
segment in the Interface Property Value, is reserved for OCF-defined Interfaces. The Interface 1341
Property Value may also be a reference to an authority similar to IANA that may be used to find 1342
the definition of an Interface. A Resource Type shall support one or more of the Interfaces defined 1343
in section 7.6.3. 1344
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 40
Interface methods 1345
7.6.3.1 Overview 1346
The OCF -defined Interfaces are listed in the table below: 1347
Table 8. OCF standard Interfaces 1348
Interface Name Applicable Methods
Description
baseline “oic.if.baseline” RETRIEVE, UPDATE
The baseline Interface defines a view into all Properties of a Resource including the Meta Properties. This Interface is used to operate on the full Representation of a Resource.
links list “oic.if.ll” RETRIEVE
The ‘links list’ Interface provides a view into Links in a Collection (Resource).
Since Links represent relationships to other Resources, the links list interfaces may be used to discover Resources with respect to a context. The discovery is done by retrieving Links to these Resources. For example: the Core Resource “/oic/res” uses this Interface to allow discovery of Resource “hosted” on a Device.
batch “oic.if.b” RETRIEVE, UPDATE
The batch Interface is used to interact with a collection of Resources at the same time. This also removes the need for the Client to first discover the Resources it is manipulating – the Server forwards the requests and aggregates the responses
read-only “oic.if.r” RETRIEVE The read-only Interface exposes the Properties of a Resource that may be ‘read’. This Interface does not provide methods to update Properties or a Resource and so can only be used to ‘read’ Property Values.
read-write “oic.if.rw” RETRIEVE, UPDATE
The read-write Interface exposes only those Properties that may be both ‘read’ and “written” and provides methods to read and write the Properties of a Resource.
actuator “oic.if.a” CREATE, RETRIEVE, UPDATE
The actuator Interface is used to read or write the Properties of an actuator Resource.
sensor “oic.if.s” RETRIEVE The sensor Interface is used to read the Properties of a sensor Resource.
1349
1350
7.6.3.2 Baseline Interface 1351
7.6.3.2.1 Overview 1352
The Representation that is visible using the “baseline” Interface includes all the Properties of the 1353
Resource including the Common Properties. The “baseline” Interface shall be defined for all 1354
Resource Types. All Resources shall support the “baseline” Interface. 1355
The “baseline” Interface is selected by adding “if=oic.if.baseline” to the list of query parameters in 1356
the URI of the target Resource. For example: “GET /oic/res?if=oic.if.baseline”. 1357
7.6.3.2.2 Use of RETRIEVE 1358
The “baseline” Interface is used when a Client wants to retrieve all Properties of a Resource. The 1359
Client includes the URI query parameter definition "?if=oic.if.baseline" in a RETRIEVE request. 1360
When this query parameter definition is included the Server shall respond with a Resource 1361
representation that includes all of the implemented Properties of the Resource. When the Server 1362
is unable to send back the whole Resource representation, it shall reply with an error message. 1363
The Server shall not return a partial Resource representation. 1364
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 41
An example response to a RETRIEVE request using the baseline Interface is shown below : 1365
{
"rt": ["oic.r.temperature"],
"if": ["oic.if.a","oic.if.baseline"],
"temperature": 20,
"units": "C",
"range": [0,100]
}
1366
7.6.3.2.3 Use of UPDATE 1367
Using the baseline Interface, all Properties of a Resource with the exception of Common Properties 1368
may be modified using an UPDATE request with a list of Properties and their desired values if a 1369
Resource Type has an associated schema for UPDATE using baseline . 1370
7.6.3.3 Link List Interface 1371
7.6.3.3.1 Overview 1372
The links list Interface provides a view into the list of Links in a Collection (Resource). The 1373
Representation visible through this Interface has only the Links defined in the Property Value of 1374
the “links” Property – so this Interface is used to manipulate or interact with the list of Links in a 1375
Collection. The Links list may be RETRIEVEd using this Interface. 1376
The Interface definition and semantics are given as follows: 1377
The links list Interface name shall be “oic.if.ll” . 1378
If specified in a request (usually in the request header), the serialization in the response shall 1379
be in the format expected in the request. 1380
In response to a RETRIEVE request on the “links list” Interface, the URIs of the referenced 1381
Resources shall be returned as a URI reference. 1382
If there are no links present in a Resource, then an empty list shall be returned. 1383
The Representation determined by this Interface view only includes the Propert y Value of the 1384
“links” Property. Hence Collection or /oic/res response with oic.if.ll is an array of OCF Links. 1385
7.6.3.3.2 Example: “links list” Interface 1386
Example: Request to a Collection 1387
Request to RETRIEVE the Links in room
(the Links could be referencing lights, fans, electric sockets etc)
GET ocf://<devID>/a/room/1?if=oic.if.ll
The response would be the array of OCF Links
[
{
"href": "/the/light/1",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 42
"eps":[
{"ep": "coaps://[2001:db8:a::b1d4]:55555"}]
},
{
"href": "/the/light/2",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"eps": [{"ep":
"coaps://[2001:db8:a::b1d4]:55555"}]
},
{
"href": "/my/fan/1",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"eps":[
{"ep": "coaps://[2001:db8:a::b1d4]:55555"}]
{
"href": "/his/fan/2",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"eps":[
{"ep": "coaps://[2001:db8:a::b1d4]:55555"}]
}
]
1388
7.6.3.4 Batch Interface 1389
7.6.3.4.1 Overview 1390
The batch Interface is used to interact with a collection of Resources using a single/same Request. 1391
The batch Interface supports methods of Resources in the Links of the Collection, and can be used 1392
to RETRIEVE or UPDATE the Properties of the “linked” Resources with a single Resource 1393
representation. 1394
The batch Interface selects a view into the Links in a Collection – the Request is sent to all the 1395
Links in this view with potential modifications defined in the Parameters of the Link 1396
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 43
The batch Interface is defined as fol lows: 1397
The batch Interface name shall be “oic.if.b” 1398
A Collection Resource with a batch Interface has Links that have Resource references that 1399
may be URIs (fully qualified for remote Resources) or relative references (for local Resources) . 1400
The original request is modified to create new requests targeting each of the targets in the 1401
Resource Links by substituting the URI in the original request with the URI of the target 1402
Resource in the Link. The payload in the original request is replicated in the payload of the 1403
new Requests. 1404
The Requests shall be forwarded assuming use of the Default Interface of the referenced 1405
Resources. 1406
Requests shall only be forwarded to link targets that are identified as items in the collection by 1407
relation types "item" or "hosts" ("hosts" is the default relation type). Requests shall not be 1408
forwarded to targets of links that do not contain the "item" or "hosts" relation type values. The 1409
default relation type "hosts" shall be allowed for relative and absolute links. 1410
Resources of the collection itself may be included in the batch by using the link relation "self" 1411
along with "item" and insuring that the default interface of the collection does not expose the 1412
links property, i.e. not “oic.if.baseline” or “oic.if.ll”. 1413
All the Responses from the linked item Resources shall be aggregated into single Response 1414
to the Client. The Server may timeout the Response to a time window (if a time window has 1415
been negotiated with the Client then the Server shall not timeout within that window; in the 1416
absence of negotiated window, the Server may choose any appropriate window based on 1417
conditions). If the target Resources cannot process the new request, an empty response or 1418
error response shall be returned. These empty/error Responses shall be inc luded in 1419
aggregated Response to the original Client Request. 1420
The batch representation is an array of objects representing the responses from the linked 1421
resources. Each object in the batch response shall include at least two items: (1) the URI of 1422
the linked resource (fully qualified for remote resources, or a relative reference for local 1423
resources) as “href”: <URI> and (2) the individual response object as “rep” as the key i.e. “rep”: 1424
{ < representation of individual response> }. 1425
Resources referenced by links in the collection may be observed using the batch interface of 1426
the collection. The observe mechanism shall work as defined in 11.4.2. Specifically, the 1427
representations and status codes shall be the same as for RETRIEVE operations using the 1428
Batch interface. 1429
Properties of the collection resource itself may be observed by using the appropriate interface. 1430
For example, a collection may be observed on its l inked list or baseline interface to receive 1431
notifications of changes to its links. 1432
The Client may choose to restrict the list of Links to which the Request is forwarded by including 1433
query parameters in the URI of the Collection to which this original ‘batch’ Interface Request 1434
is made. The Server should process query parameters in a request that includes “oic.if.b”, as 1435
selectors for links in the Collection that are to be processed in the batch. 1436
Batch UPDATE operations are performed by creating a payload according to the same schema 1437
of the Batch RETRIEVE payload. A set of link-specific UPDATE requests is created according 1438
to the "href" tags in the included items, and the payload contained in the value of the "rep" 1439
property is applied to the corresponding "href" referenced item. 1440
If requested property for UPDATE does not exist in linked resource, it shall silently ignore the 1441
request. 1442
If the "href" value is the empty URI, denoted by a zero length string or "" in JSON, the payload 1443
in the value of the "rep" property is applied to all batch items in the Collection. 1444
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 44
Items with the empty "href" and link-specific "href" shall not be mixed in the same UPDATE 1445
payload. 1446
The Representation in the Link-specific Request may not match the Representation exposed 1447
by the Default Interface on the target Resource. In such cases, the ‘subset’ semantics apply 1448
where Properties in the Request which match Properties in the Resource view exposed shall 1449
be modified in the target Resource if the Property is writeable. 1450
The response to POST shall contain the updated values using the same payload schema as 1451
RETRIEVE operations, along with the appropriate status code. The response payload shall 1452
reflect the known state of the updated resource properties after the batch update was 1453
completed. 1454
7.6.3.4.2 Use of Query Parameters with Batch 1455
Additional query parameters may be used with the batch interface in order to select particular items 1456
in the batch for retrieval or update. When additional parameters are included which are not 1457
interpreted in other ways, these parameters are used to select items in the batch by matching link 1458
attribute values. 1459
A particular item in a batch is selected by additional query parameters in a request if, and only if, 1460
all of the link selection query parameters contained values which match corresponding values in 1461
the link attributes of that item. 1462
When link selection query parameters are used with RETRIEVE operations, only the items with 1463
matching link attributes are returned. 1464
When link selection query parameters are used with UPDATE operations, only the items having 1465
matching link attributes are updated. 1466
See 7.6.3.4.3 for examples of RETRIEVE and UPDATE operations that use link selection query 1467
parameters. 1468
7.6.3.4.3 Examples: Batch Interface 1469
Example 1 1470
Resources /a/room/1
{
"rt": ["oic.wk.col","x.org.example.rt.room"],
"if": ["oic.if.baseline","oic.if.b","oic.if.ll", "oic.if.r"],
"x.org.example.color": "blue",
"x.org.example.dimension": "15bx15wx10h",
"links": [
{"href": "/a/room/1", "rel": ["self", "item"], "rt":
["x.org.example.rt.room"], "if": ["oic.if.r",
"oic.if.baseline","oic.if.b","oic.if.ll"] },
{"href": "/the/light/1", "rel": ["item"], "rt":
["oic.r.switch.binary"], "if": ["oic.if.a","oic.if.baseline"]},
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 45
{"href": "/the/light/2", "rel": ["item"], "rt":
["oic.r.switch.binary"], if=["oic.if.a" ,"oic.if.baseline"]},
{"href": "/my/fan/1", "rel": ["item"], "rt":
["oic.r.switch.binary"], if=[","oic.if.a", "oic.if.baseline"]},
{"href": "/his/fan/2", "rel": ["item"], "rt":
["oic.r.switch.binary"], if=["oic.if.a", "oic.if.baseline"]}
]
}
/the/light/1
{
"rt": ["oic.r.switch.binary"],
"ins": "light-1",
"if": ["oic.if.a", "oic.if.baseline"],
"value": false
}
/the/light/2
{
"rt": ["oic.r.switch.binary"],
"ins": :"light-2",
"if": ["oic.if.a", "oic.if.baseline"],
"value": true
}
/the/fan/1
{
"rt": ["oic.r.switch.binary"],
"ins": "fan-1",
"if": ["oic.if.a", "oic.if.baseline"],
"value": true
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 46
}
/the/fan/2
{
"rt": ["oic.r.switch.binary"],
"ins": "fan-2",
"if": ["oic.if.a", "oic.if.baseline"],
"value": false
}
Use of batch
Request: GET /a/room/1?if=oic.if.b
Becomes the following individual request messages issued by the
Device in the Client role
GET /a/room/1 (NOTE: Uses the default Interface as specified for
this resource)
GET /the/light/1 (NOTE: Uses the default Interface as specified
for this resource)
GET /the/light/2 (NOTE: Uses the default Interface as specified for
this resource)
GET /the/fan/1 (NOTE: Uses the default Interface as specified for
this resource)
GET /the/fan/2 (NOTE: Uses the default Interface as specified for
this resource)
Response:
[
{
"href": "/a/room/1",
"rep": {"x.org.example.color":
"blue","x.org.example.dimension": "15bx15wx10h"}
},
{
"href": "/the/light/1",
"rep": {"value": false}
},
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 47
{
"href": "/the/light/2",
"rep": {"value": true}
},
{
"href": "/my/fan/1",
"rep": {"value": true}
},
{
"href": "/his/fan/2",
"rep": {"value": false}
}
]
Use of batch
(UPDATE has POST semantics)
UPDATE /a/room/1?if=oic.if.b
[
{
"href": "",
"rep": {
"value": false
}
}
]
Since the "href" value in the batch update payload item is the empty URI, the request is forwarded to all items in the batch and becomes:
UPDATE /a/room/1 { "value": false }
UPDATE /the/light/1 { "value": false }
UPDATE /the/light/2 { "value": false }
UPDATE /my/fan/1 { "value": false }
UPDATE /his/fan/2 { "value": false }
The response will be same as response for GET /a/room/1?if=oic.if.b.
Since /a/room/1 does not have a "value" property exposed by its default interface, the update request will be silently ignored.
Use of batch
UPDATE /a/room/1?if=oic.if.b
[
{
"href": "/the/light/1",
"rep": {
"value": false
}
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 48
(UPDATE has POST semantics)
},
{
"href": "/the/light/2",
"rep": {
"value": true
}
},
{
"href": "/a/room/1",
"rep": {
"x.org.example.color": "red"
}
}
]
This turns /the/light/1 off, turns /the/light/2 on, and sets the color of the room to "red". The response will be same as response for GET /a/room/1?if=oic.if.b. Example use of additional query parameters to select items by matching link attributes. Turn on light 1 based on the "ins" link attribute value of "light -1" UPDATE /a/room/1?if=oic.if.b&ins=light-1
[
{
"href": "",
"rep": {
"value": false
}
}
]
Similar to the earlier example, "href": "" applies the payload to all selected links. Since the additional query parameter ins=light-1 selects only links that have a matching "ins" value, only one link is selected. The payload is applied to the target resource of that link, /the/light/1. Retrieving the item using the same query parameter: RETRIEVE /a/room/1?if=oic.if.b&ins=light-1
Response payload: [
{
"href": "",
"rep": {
"value": false
}
}
]
1471
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 49
Example that further shows the “links list” and “batch” interface 1472
Example /myexample
{
"rt": ["oic.r.foo"],
"if": [ "oic.if.baseline", "oic.if.ll" ],
"links": [
{"href": "/acme/switch", "di": "<deviceID1>", "rt":
["oic.r.switch.binary"], "if": ["oic.if.a"]},
{"href": "ocf://<deviceID1>/acme/fan", "rt":
["oic.r.fan"], "if": ["oic.if.a"] }
]
}
Use of Baseline
GET /myexample?if=oic.if.baseline will return
{
"rt": ["oic.r.foo"],
"if": [ "oic.if.baseline", "oic.if.ll" ],
"links": [
{"href": "/acme/switch", "di": "<deviceID1>", "rt":
["oic.r.switch.binary"], "if": ["oic.if.a"]},
{"href": "ocf://<deviceID1>/acme/fan", "rt":
"oic.r.fan", "if”: "oic.if.a"}
]
}
Use of Links List
GET /myexample?if=oic.if.ll. will return
[
{"href": "/acme/switch", "di": "<deviceID1>", "rt":
["oic.r.switch.binary"], "if": ["oic.if.a"]},
{"href": "ocf://<deviceID1>/acme/fan", “rt”:
["oic.r.fan"], "if": ["oic.if.a"]}
]
1473
7.6.3.5 Actuator Interface 1474
The actuator Interface is the Interface for viewing Resources that may be actuated i.e. changes 1475
some value within or the state of the entity abstracted by the Resource : 1476
The actuator Interface name shall be “oic.if.a” 1477
The actuator Interface shall expose in the Resource Representation all mandatory Properties 1478
as defined by the applicable JSON; the actuator interface may also expose in the Resource 1479
Representation optional Properties as defined by the applicable JSON schema that are 1480
implemented by the target Device. 1481
For the following Resource
NOTE: “prm” is the Property name for ‘parameters’ Property
/a/act/heater
{
"rt": ["acme.gas"],
"if": ["oic.if.baseline", "oic.if.r", "oic.if.a", "oic.if.s"],
"prm": {"sensitivity": 5, "units": "C", "range": "0 .. 10"},
"settemp": 10,
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 50
"currenttemp" : 7
}
Figure 8: Example - "Heater" Resource (for illustration only) 1482
1483
NOTE: The example here is with respect to Figure 8 1. Retrieving values of an actuator Request: GET /a/act/heater?if="oic.if.a"
Response:
{
"prm": {"sensitivity": 5, "units": "C", "range": "0 .. 10"},
"settemp": 10,
"currenttemp" : 7
}
2. Correct use of actuator:
Request: POST /a/act/heater?if="oic.if.a"
{
"settemp": 20
}
Response:
{
Ok
}
3. Incorrect use of actuator
Request: POST /a/act/heater?if="oic.if.a"
{
"if": ["oic.if.s"] this is visible through baseline
Interface }
Response:
{
Error
}
Figure 9: Example - Actuator Interface 1484
A RETRIEVE request using this Interface shall return the Representation for this Resource 1485
subject to any query and filter parameters that may also exist 1486
An UPDATE request using this Interface shall provide a payload or body that contains the 1487
Properties that will be updated on the target Resource. 1488
7.6.3.6 Sensor Interface 1489
The sensor Interface is the Interface for retrieving measured, sensed or capability specific 1490
information from a Resource that senses: 1491
The sensor Interface name shall be “oic.if.s” 1492
The sensor Interface shall expose in the Resource Representation all mandatory Properties as 1493
defined by the applicable JSON; the sensor interface may also expose in the Resource 1494
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 51
Representation optional Properties as defined by the applicable JSON schema that are 1495
implemented by the target Device. 1496
A RETRIEVE request using this Interface shall return this Representation for the Resource 1497
subject to any query and filter parameters that may also exist 1498
1499
NOTE: The example here is with respect to Figure 8 1. Retrieving values of sensor Request: GET /a/act/heater?if="oic.if.s"
Response:
{
"currenttemp": 7
}
2. Incorrect use of sensor
Request: PUT /a/act/heater?if="oic.if.s" PUT is not allowed {
"settemp": 20 this is possible through actuator Interface }
Response:
{
Error
}
3. Incorrect use of sensor
Request: POST /a/act/heater?if="oic.if.s" POST is not allowed {
"currenttemp": 15 this is possible through actuator
Interface }
Response:
{
Error
}
1500
7.6.3.7 Read-only Interface 1501
The read-only Interface exposes only the Properties that may be “read”. This includes Properties 1502
that may be “read-only”, “read-write” but not Properties that are “write-only” or “set-only”. The 1503
applicable methods that can be applied to a Resource is RETRIEVE only. An attempt by a Client 1504
to apply a method other than RETRIEVE to a Resource shall be rejected with a n error response 1505
code. 1506
7.6.3.8 Read-write Interface 1507
The read-write Interface exposes only the Properties that may be “read” and “written”. The “read-1508
only” Properties shall not be included in Representation for the “read -write” Interface. This is a 1509
generic Interface to support “reading” and “setting” Properties in a Resource. The applicable 1510
methods that can be applied to a Resource are RETRIEVE and UPDATE only. An attempt by a 1511
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 52
Client to apply a method other than RETRIEVE or UPDATE to a Resource shall be rejected with 1512
an error response code. 1513
7.7 Resource representation 1514
Resource representation captures the state of a Resource at a particular time. The resource 1515
representation is exchanged in the request and response interactions with a Resource. A Resource 1516
representation may be used to retrieve or update the s tate of a resource. 1517
The resource representation shall not be manipulated by the data connectivity protocols and 1518
technologies (e.g., CoAP, UDP/IP or BLE). 1519
7.8 Structure 1520
Introduction 1521
In many scenarios and contexts, the Resources may have either an implicit or explicit structure 1522
between them. A structure can, for example, be a tree, a mesh, a fan-out or a fan-in. The 1523
Framework provides the means to model and map these structures and the relationships among 1524
Resources. The primary building block for resource structures in Framework is the collection. A 1525
collection represents a container, which is extensible to model complex structures. 1526
Resource Relationships 1527
Resource relationships are expressed as Links. A Link embraces and extends typed web links 1528
concept as a means of expressing relationships between Resources. A Link consists of a set of 1529
Parameters that define: 1530
a context URI, 1531
a target URI, 1532
a relation from the context URI to the target URI 1533
elements that provide metadata about the target URI, the relationship or the context of the Link. 1534
The target URI is mandatory and the other items in a Link are optional. Additional items in the Link 1535
may be made mandatory based on the use of the links in different contexts (e.g. in collections, in 1536
discovery, in bridging etc.). Schema for the Link payload is provided in Annex D. 1537
An example of a Link is shown in 1538
{"href": "/switch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", /room2"oic.if.baseline"], "p":
{"bm": 3}, "rel": "item"}
Figure 10: Example of a Link 1539
Two Links are distinct from each other when at least one parameter is different. For example the 1540
two Links shown in Figure 11 are distinct and can appear in the same list of Links. 1541
{"href": "/switch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm":
2}, "rel": "item"}
{"href": "/switch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm":
2}}
Figure 11: Example of distinct Links 1542
The specification may mandate Parameters and Parameter values as required for certain 1543
capabilities. For all Links returned in a response to a RETRIEVE on “/oic/res”, if a Link does not 1544
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 53
explicitly include the “rel” Parameter, a value of “rel”=”hosts” shall be assumed . The relation value 1545
of “hosts” is defined by IETF RFC 6690, the value of "item" by IETF RFC 6573, and the value of 1546
"self" by IETF RFC 4287 and all are registered in the IANA Registry for Link Relations at 1547
[http://www.iana.org/assignments/link-relations/link-relations.xhtml] 1548
As shown in D.2.8 the relation between the context URI and target URI in a Link is specified using 1549
the “rel” JSON element and the value of this element specifies the particular relation. 1550
The context URI of the Link shall implicitly be the URI of the Resource (or specifically a Collection) 1551
that contains the Link unless the Link specifies the anchor parameter. The anchor parameter is 1552
used to change the context URI of a Link – the relationship with the target URI is based off the 1553
anchor URI when the anchor is specified. Anchor parameter uses transfer protocol URI for OIC 1.1 1554
Link (e.g. "anchor": "coaps://[fe80::b1d6]:44444") and OCF URI defined in Sec 6 for OCF 1.0 Links 1555
(e.g. "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989"). 1556
An example of using anchors in the context of Collections – a floor has rooms and rooms have 1557
lights – the lights may be defined in floor as Links but the Links will have the anchor set to the URI 1558
of the rooms that contain the lights (the relation is contains). This allows all lights in a floor to be 1559
turned on or off together while still having the lights defined with respect to the rooms that contain 1560
them (lights may also be turned on by using the room URI too). 1561
/a/floor {
"links": [
{
"href": "/x/light1",
"anchor": "/a/room1", ** Note: /a/room1 has the “item” relationship with /x/light1; not /a/floor ** "rel": "item"
}
]
}
/a/room1 {
"links": [
{
** Note: /a/room1 “contains” the /x/light since /a/room1 is the implicit context URI ** "href": "/x/light1",
"rel": "item"
}
]
}
Figure 12: Example of use of anchor in Link 1562
7.8.2.1 Parameters 1563
7.8.2.1.1 “ins” or Link Instance Parameter 1564
The “ins” parameter identifies a particular Link instance in a list of Links. The "ins" parameter may 1565
be used to modify or delete a specific Link in a list of Links. The value of the “ins” parameter is set 1566
at instantiation of the Link by the OCF Device (Server) that is hosting the list of Links – once it has 1567
been set, the “ins” parameter shall not be modified for as long as the Link is a member of that list. 1568
7.8.2.1.2 “p” or Policy Parameter 1569
The Policy Parameter defines various rules for correctly accessing a Resource referenced by a 1570
target URI. The Policy rules are configured by a set of key-value pairs as defined below. 1571
The policy Parameter "p" is defined by: 1572
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 54
“bm” key: The “bm” key corresponds to an integer value that is interpreted as an 8 -bit bitmask. 1573
Each bit in the bitmask corresponds to a specific Policy rule. The following rules are specified 1574
for “bm”: 1575
1576
Bit Position Policy rule Comment
Bit 0 (the LSB) discoverable The discoverable rule defines whether the Link is to be included in the Resource discovery message via “/oic/res”.
If the Link is to be included in the Resource discovery message, then “p” shall include the “bm” key and set the discoverable bit to value 1.
If the Link is NOT to be included in the Resource discovery message, then “p” shall either include the “bm” key and set the discoverable bit to value 0 or omit the “bm” key entirely.
Bit 1 (2nd LSB) observable The observable rule defines whether the Resource referenced by the target URI supports the NOTIFY operation. With the self-link, i.e. the Link with "rel" value of "self", “/oic/res” can have a Link with the target URI of “/oic/res” and indicate itself observable. The "self" is defined by IETF RFC 4287 and registered in the IANA Registry for "rel" value at [http://www.iana.org/assignments/link-relations/link-relations.xhtml].
If the Resource supports the NOTIFY operation, then ”p” shall include the “bm” key and set the observable bit to value 1.
If the Resource does NOT support the NOTIFY operation, then “p” shall either include the “bm” key and set the observable bit to value 0 or omit the “bm” key entirely.
Bits 2-7 -- Reserved for future use. All reserved bits in “bm” shall be set to value 0.
1577
Note that if all the bits in “bm” are defined to value 0, then the “bm” key may be omitted entirely 1578
from “p” as an efficiency measure. However, if any bit is set to value 1, then “bm” shall be 1579
included in “p” and all the bits shall be defined appropriately. 1580
"sec" and "port" in the remaining bullets shall be used only in an OIC 1.1 payload. In OCF 1.0 1581
payload, "sec" and "port" shall not be used and instead the "eps" Parameter shall provide the 1582
information for an encrypted connection. 1583
"sec" key: The “sec” key corresponds to a Boolean value that indicates whether the Resource 1584
referenced by the target URI is accessed via an encrypted connection. If “sec” is true, the 1585
resource is accessed via an encrypted connection, using the “port” spec ified (see below). If 1586
“sec” is false, the resource is accessed via an unencrypted connection, or via an encrypted 1587
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 55
connection (if such a connection is made using the “port” settings for another Resource, for 1588
which “sec” is true). 1589
"port" key: The “port” key corresponds to an integer value that is used to indicate the port 1590
number where the Resource referenced by the target URI may be accessed via an encrypted 1591
connection. 1592
If the Resource is only available via an encrypted connection (i.e. DTLS over IP), then 1593
o "p" shall include the "sec" key and its value shall be true. 1594
o "p" shall include the "port" key and its value shall be the port number where the 1595
encrypted connection may be established. 1596
If the Resource is not available via an encrypted connection, then 1597
o "p" shall include the "sec" key and its value shall be false or "p" shall omit the "sec" 1598
key; the default value of "sec" is false. 1599
o "p" shall omit the "port" key. 1600
o A Resource that is available via either an encrypted or unencrypted connection 1601
follows the population scheme defined in this clause. 1602
Access to the Resource on the port specified by the “port” key shall be made by an encrypted 1603
connection (e.g. coaps://). (Note that unencrypted connection to the Resource may be possible 1604
on a separate port discovered thru multicast discovery). 1605
Note that access to the Resource is controlled by the ACL for the Resource. A successful 1606
encrypted connection does not ensure that the requested action will succeed. See 1607
OCF Security – Access Control section for more information. 1608
Example 1: below shows the Policy Parameter for a Resource that is discoverable but not 1609
observable, and for which authenticated accesses shall be done via CoAPS port 33275: 1610
1611
1612
Example 2: below shows a self-link, i.e. the “/oic/res” Link in itself that is discoverable and 1613
observable. 1614
1615
1616
1617
1618
1619
1620
1621
7.8.2.1.3 “type” or Media Type Parameter 1622
The “type” Parameter may be used to specify the various media types that are supported by a 1623
specific target Resource. The default type of "application/cbor" shall be used when the “type” 1624
element is omitted. Once a Client discovers this information for each Resource, it may use one of 1625
the available representations in the appropriate header field of the Request or Response. 1626
7.8.2.1.4 “bp” or the Batch Interface Parameter 1627
The “batch” Parameter "bp" is used to specify the modifications to the target URI as the "batch" 1628
Request is forwarded through this Link. The "q" element in the value defines the query string that 1629
"p": { "bm": 1}
{
"href": "/oic/res",
"rel": "self",
"rt": ["oic.wk.res"],
"if": ["oic.if.ll", "oic.if.baseline"],
"p": {"bm": 3}
}
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 56
shall be appended to the "href" to make the target URI. The "q" query string may contain Pro perty 1630
strings that are valid in that context. For example: Given a Collection as follows 1631
/room2 {
"if": ["oic.if.b"],
"colour": "blue",
"links": [
{"href": "/switch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline" ], "p":
{"bm": 2}, "rel": "contains", "bp": { "q": "if=oic.if.baseline"} }
]
}
The following is the sequence for batch request to /room2 1632
1. GET /room2?if=oic.if.b
2. This request is transformed to: GET /switch?if=oic.if.baseline when the batch
request is propagated through the Link to the target /switch
See the Interfaces section 7.5 for more details on the "batch" Interface. 1633
7.8.2.1.5 “di” or Device ID parameter 1634
The “di” Parameter specifies the device ID of the Device that hosts the target Resource defined in 1635
the in the “href” Parameter. 1636
The device ID may be used to qualify a relative reference used in the “href” or to lookup endpoint 1637
information for the relative reference. 1638
7.8.2.1.6 “eps” Parmeter 1639
The "eps" Parameter indicates the Endpoint information of the target Resource. 1640
"eps" shall have as its value an array of items and each item represents Endpoint information with 1641
"ep" and "pri" as specified in 10.2. "ep" is mandatory but "pri" is optional. 1642
Figure 13 is illustrated for "eps" with multiple Endpoints. 1643
"eps": [
{"ep": "coap://[fe80::b1d6]:1111", "pri": 2},
{"ep": "coaps://[fe80::b1d6]:1122"},
{"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3}
]
Figure 13: Example of “eps Parameter 1644
When "eps" is present in a link, the Endpoint information in "eps" can be used to access the target 1645
Resource referred by the "href" Parameter. 1646
When present, max-age information (e.g. Max-Age option for CoAP defined in IETF RFC 7252) 1647
determines the maximum time "eps" values may be cached before they are considered stale. 1648
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 57
7.8.2.2 Formatting 1649
When formatting in JSON, the list of Links shall be an array. 1650
7.8.2.3 List of Links in a Collection 1651
A list of Links in a Resource shall be included in that Resource as the value of the “links” Property 1652
of that Resource. A Resource that contains Links is a Collection. 1653
A Resource with a list of Links 1654
/Room1
{
"rt": ["my.room"],
"if": ["oic.if.ll", "oic.if.baseline" ],
"color": "blue",
"links": [
{
"href": "/oic/d",
"rt": ["oic.d.light", "oic.wk.d"],
"if": [ "oic.if.r", "oic.if.baseline" ], "p": {"bm": 1}
},
{
"href": "/oic/p",
"rt": ["oic.wk.p"],
"if": [ "oic.if.r", "oic.if.baseline" ], "p": {"bm": 1}
},
{
"href": "/switch",
"rt": ["oic.r.switch.binary"],
"if": [ "oic.if.a", "oic.if.baseline" ], "p": {"bm": 3},
"mt": [ "application/cbor", "application/exi+xml" ] },
{
"href": "/brightness",
"rt": ["oic.r.light.brightness"],
"if": [ "oic.if.a", "oic.if.baseline" ], "p": {"bm": 3}
}
]
}
Figure 14: List of Links in a Resource 1655
Collections 1656
7.8.3.1 Overview 1657
A Resource that contains one or more references (specified as Links) to other resources is an 1658
Collection. These reference may be related to each other or just be a list; the Collection provides 1659
a means to refer to this set of references with a single handle (i.e. the URI). A simple resource is 1660
kept distinct from a collection. Any Resource may be turned into an Collection by binding resource 1661
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 58
references as Links. Collections may be used for creating, defining or specifying hierarchies, 1662
indexes, groups, and so on. 1663
A Collection shall have at least one Resource Type and at least one Interface bound at all times 1664
during its lifetime. During creation time of a collection the Resource Type and interfaces are 1665
specified. The initial defined Resource Types and interfaces may be updated during its life time. 1666
These initial values may be overridden using mechanism used for overriding in the case of a 1667
Resource. Additional Resource Types and Interfaces may be bound to the Collection at creation 1668
or later during the lifecycle of the Collection. 1669
A Collection shall define the “links” Property. The value of the “links” Property is an array with zero 1670
or more Links. The target URIs in the Links may reference another Collection or another Resource. 1671
The referenced Collection or Resource may reside on the same Device as the Collection that 1672
includes that Link (called a local reference) or may reside on another Device (called a remote 1673
reference). The context URI of the Links in the “links” array shall (implicitly) be the Collection that 1674
contains that “links” property. The (implicit) context URI may be overridden with explicit 1675
specification of the “anchor” parameter in the Link where the value of “anchor” is th e new base of 1676
the Link. 1677
A Resource may be referenced in more than one Collection, therefore, a unique parent -child 1678
relationship is not guaranteed. There is no pre-defined relationship between a Collection and the 1679
Resource referenced in the Collection, i.e., the application may use Collections to represent a 1680
relationship but none is automatically implied or defined. The lifecycles of the Collection and the 1681
referenced Resource are also independent of one another. 1682
If the “drel” property is defined for the Collection then all Links that don’t explicitly specify a 1683
relationship shall inherit this default relationship in the context of that Collection. The default 1684
relationship defines the implicit relationship between the Collection and the target URI in the Link. 1685
A Property "links" represents the list of Links in a Collection. "links" Property has, as its value, an 1686
array of items and each item is an OCF Link as shown in Figure 15. 1687
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 59
1688
Figure 15: Example showing Collection and Links 1689
1690
A Collection may be: 1691
A pre-defined Collection where the Collection has been defined a priori and the Collection is 1692
static over its lifetime. Such Collections may be used to model, for example, an appliance that 1693
is composed of other devices or fixed set of resource representing fixed functions. 1694
A Device local Collection where the Collection is used only on the Device that hosts the 1695
Collection. Such collections may be used as a short-hand on a client for referring to many 1696
Servers as one. 1697
A centralized Collection where the Collection is hosted on an Device but other Devices may 1698
access or update the Collection 1699
A hosted Collection where the collection is centralized but is managed by an authorized agent 1700
or party. 1701
7.8.3.2 Collection Properties 1702
An Collection shall define the “links” Property. In addition, other Properties may be defined for the 1703
Collection by the Resource Type. The mandatory and recommended Common Properties for 1704
Collection are shown in Table 9. This list of Common Properties are in addition to those defined 1705
for Resources in section 7.3.2. When a property is repeated in Table 9 , the conditions in this 1706
definition shall override those in the general list for Resources. 1707
/my/house
{
"rt": ["my.r.house"],
"color": "blue",
"n": "myhouse",
"links": [
{
"href": "/door",
"rt": ["oic.r.door"],
"if": ["oic.if.b", "oic.if.ll", "oic.if.baseline"]
},
{
"href": "/door/lock",
"rt": ["oic.r.lock"],
"if": ["oic.if.b", "oic.if.baseline"],
"type": ["application/cbor", "application/exi+xml"]
},
{
"href": "/light",
"rt": ["oic.r.light"],
"if": ["oic.if.s", "oic.if.baseline"]
},
{
"href": "/binarySwitch",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"type": ["application/cbor"]
}
]
}
IRI/URI (resource)
Properties (resource)
Parameters (link)
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 60
Table 9. Common Properties for Collections (in addition to Common Properties defined in 1708
section 7.3.2) 1709
Property Description Property name Value Type Mandatory
Links The set of links in the collection “links” json
Array of Links
Yes
Name Human friendly name for the collection
“n” string No
Identity The id of the collection “id” UUID No
Resource Types
The list of allowed Resource Types for links in the collection. Requests for addition of links using link list or link batch interfaces will be validated against this list.
If this property is not defined or is null string then any Resource Type is permitted
“rts” json
Array of Resource Type names
No
Default relationship
Specifies the default relationship to use for Links in the collection where the “rel” parameter has not been explicitly defined.
It is permissible to have no “drel” property defined for the collection and the Links to also not have “rel” defined either. In such case, the use of the collection is, for example, as a random bag of links
“drel” string No
1710
The Properties of a Collection may not be modified. 1711
7.8.3.3 Default Resource Type 1712
A default Resource Type, “oic.wk.col”, shall be available for Collections. This Resource Type shall 1713
be used only when another type has not been defined on the Collection or when no Resource Type 1714
has been specified at the creation of the Collection. 1715
The default Resource Type provides support for the Common Properties including the “links” 1716
Property. For the default Resource Type, the value of “links” shall be a simple array of Links . 1717
The default Resource Type shall support the ‘baseline’ and ‘links list’ Interfaces. The default 1718
Interface shall be the ‘links list’ Interface. 1719
1720
7.9 Third (3rd) party specified extensions 1721
This section describes how a 3 rd party may add Device Types, Resource Types, 3 rd party defined 1722
Properties to an existing or 3 rd party defined Resource Type, 3 rd party defined enumeration values 1723
to an existing enumeration and 3 rd party defined parameters to an existing defined Property. 1724
A 3rd party may specify additional (non-OCF) Resources within an OCF Device. A 3 rd party may 1725
also specify additional Properties within an existing OCF defined Resource Type. Further a 3 rd 1726
party may extend an OCF defined enumeration with 3 rd party defined values. 1727
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 61
A 3rd party defined Device Type may expose both 3rd party and OCF defined Resource Types. A 1728
3rd party defined Device Type must expose the mandatory Resources for all OCF Devices defined 1729
within this specification. 1730
A 3rd party defined Resource Type shall include any mandatory Properties defined in this 1731
specification and also any vertical specified mandatory Properties. All Properties defined within a 1732
3rd party defined Resource Type that are part of the OCF namespace that are not Common 1733
Properties as defined in this specification shall follow the 3 rd party defined Property rules in Table 1734
10. 1735
The following table defines the syntax rules for 3 rd party defined Resource Type elements. Within 1736
the table the term “Domain_Name” refers to a domain name that is owned by the 3 rd party that is 1737
defining the new element. 1738
Table 10. 3rd party defined Resource elements 1739
Resource Element Vendor Definition Rules
New 3rd party defined Device Type “rt” Property Value of “/oic/d”
x.<Domain_Name>.<resource identification>
New 3rd party defined Resource Type “rt” Property Value x.<Domain_Name>.<resource identification>
New 3rd party defined Property within the OCF namespace
Resource Property Name
x.<Domain_Name>.<property>
Additional 3 rd party defined values in an OCF specified enumeration
Enumeration Property Value
x.<Domain_Name>.<enum value>
Additional 3 rd party defined parameter in an OCF specified Property
Parameter key word x.<Domain_Name>.<parameter keyword>
1740
With respect to the use of the Domain_Name in this scheme the labels are reversed from how they 1741
appear in DNS or other resolution mechanisms. The 3 rd party defined Device Type and Resource 1742
Type otherwise follow the rules defined in Section 7.4.2 Resource Type Property. 3 rd party defined 1743
Resource Types should be registered in the IANA Constrained RESTful Environments (CoRE) 1744
Parameters registry. 1745
For example: 1746
x.com.samsung.galaxyphone.accelerator 1747
x.com.cisco.ciscorouterport 1748
x.com.hp.printerhead 1749
x.org.allseen.newinterface.newproperty 1750
1751
8 CRUDN 1752
8.1 Overview 1753
CREATE, RETRIEVE, UPDATE, DELETE, and NOTIFY (CRUDN) are operations defined for 1754
manipulating Resources. These operations are performed by a Client on the resources contained 1755
in n Server. 1756
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 62
On reception of a valid CRUDN operation n Server hosting the Resource that is the target of the 1757
request shall generate a response depending on the Interface included in the request; or based 1758
on the Default Interface for the Resource Type if no Interface is included. 1759
CRUDN operations utilize a set of parameters that are carried in the messages and are defined in 1760
Table 11. A Device shall use CBOR as the default payload (content) encoding scheme for resource 1761
representations included in CRUDN operations and operation responses; a Device may negotiate 1762
a different payload encoding scheme (e.g, see in section 12.2.4 for CoAP messaging). The 1763
following subsections specify the CRUDN operations and use of the parameters. The type 1764
definitions for these terms will be mapped in the messaging section for each protoco l. 1765
Table 11. Parameters of CRUDN messages 1766
Applicability Name Denotation Definition
All messages
fr From The URI of the message originator.
to To The URI of the recipient of the message.
ri Request Identifier The identifier that uniquely identifies the message in the originator and the recipient.
cn Content Information specific to the operation.
Requests
op Operation Specific operation requested to be performed by the Server.
obs Observe Indicator for an observe request.
Responses
rs Response Code
Indicator of the result of the request; whether it was accepted and what the conclusion of the operation was. The values of the response code for CRUDN operations shall conform to those as defined in section 5.9 and 12.1.2 in IETF RFC 7252.
obs Observe Indicator for an observe response.
8.2 CREATE 1767
The CREATE operation is used to request the creation of new Resources on the Server. The 1768
CREATE operation is initiated by the Client and consists of three steps, as depicted in Figure 16 1769
and described below. 1770
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 63
1771
Figure 16. CREATE operation 1772
CREATE request 1773
The CREATE request message is transmitted by the Client to the Server to create a new Resource 1774
by the Server. The CREATE request message will carry the following parameters: 1775
fr: Unique identifier of the Client 1776
to: URI of the target resource responsible for creation of the new resource. 1777
ri: Identifier of the CREATE request 1778
cn: Information of the resource to be created by the Server 1779
i) cn will include the URI and Resource Type property of the resource to be created. 1780
ii) cn may include additional properties of the resource to be created. 1781
op: CREATE 1782
Processing by the Server 1783
Following the receipt of a CREATE request, the Server may validate if the Client has the 1784
appropriate rights for creating the requested resource. If the validation is successful, the Server 1785
creates the requested resource. The Server caches the value of ri parameter in the CREATE 1786
request for inclusion in the CREATE response message. 1787
CREATE response 1788
The Server shall transmit a CREATE response message in response to a CREATE request 1789
message from a Client. The CREATE response message will include the following parameters. 1790
fr: Unique identifier of the Server 1791
to: Unique identifier of the Client 1792
ri: Identifier included in the CREATE request 1793
cn: Information of the resource as created by the Server. 1794
i) cn will include the URI of the created resource. 1795
ii) cn will include the resource representation of the created resource. 1796
rs: The result of the CREATE operation 1797
8.3 RETRIEVE 1798
The RETRIEVE operation is used to request the current state or representation of a Resource. 1799
The RETRIEVE operation is initiated by the Client and consists of three steps, as depicted in 1800
Figure 17 and described below. 1801
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 64
1802
Figure 17. RETRIEVE operation 1803
RETRIEVE request 1804
RETRIEVE request message is transmitted by the Client to the Server to request the 1805
representation of a Resource from a Server. The RETRIEVE request message will carry the 1806
following parameters. 1807
fr: Unique identifier of the Client 1808
to: URI of the resource the Client is targeting 1809
ri: Identifier of the RETRIEVE request 1810
op: RETRIEVE 1811
Processing by the Server 1812
Following the receipt of a RETRIEVE request, the Server may validate if the Client has the 1813
appropriate rights for retrieving the requested data and the properties are readable. The Server 1814
caches the value of ri parameter in the RETRIEVE request for use in the response. 1815
RETRIEVE response 1816
The Server shall transmit a RETRIEVE response message in response to a RETRIEVE request 1817
message from a Client. The RETRIEVE response message will include the following parameters. 1818
fr: Unique identifier of the Server 1819
to: Unique identifier of the Client 1820
ri: Identifier included in the RETRIEVE request 1821
cn: Information of the resource as requested by the Client 1822
i) cn should include the URI of the resource targeted in the RETRIEVE request 1823
1824
rs: The result of the RETRIEVE operation 1825
8.4 UPDATE 1826
The UPDATE operation is either a Partial UPDATE or a complete replacement of the information 1827
in a Resource in conjunction with the interface that is also applied to the operation. The UPDATE 1828
operation is initiated by the Client and consists of three steps, as depicted in Figure 18 and 1829
described below. 1830
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 65
1831
Figure 18. UPDATE operation 1832
UPDATE request 1833
The UPDATE request message is transmitted by the Client to the Server to request the update of 1834
information of a Resource on the Server. The UPDATE request message will carry the following 1835
parameters. 1836
fr: Unique identifier of the Client 1837
to: URI of the resource targeted for the information update 1838
ri: Identifier of the UPDATE request 1839
op: UPDATE 1840
cn: Information, including properties, of the resource to be updated at the target resource 1841
Processing by the Server 1842
Following the receipt of an UPDATE request, the Server may validate if the Client has the 1843
appropriate rights for updating the requested data. If the validation is successful the Server 1844
updates the target Resource information according to the information carried in cn parameter of 1845
the UPDATE request message. The Server caches the value of ri parameter in the UPDATE 1846
request for use in the response. 1847
An UPDATE request that includes Properties that are read-only shall be rejected by the Server 1848
with an rs indicating a bad request. 1849
An UPDATE request shall be applied only to the Properties in the target resource visible via the 1850
applied interface that support the operation. An UPDATE of non-existent Properties is ignored. 1851
UPDATE response 1852
The UPDATE response message will include the following parameters: 1853
fr: Unique identifier of the Server 1854
to: Unique identifier of the Client 1855
ri: Identifier included in the UPDATE request 1856
rs: The result of the UPDATE request 1857
The UPDATE response message may also include the following parameters: 1858
cn: The Resource representation following processing of the UPDATE request 1859
8.5 DELETE 1860
The DELETE operation is used to request the removal of a Resource. The DELETE operation is 1861
initiated by the Client and consists of three steps, as depicted in Figure 19 and described below. 1862
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 66
1863
Figure 19. DELETE operation 1864
DELETE request 1865
DELETE request message is transmitted by the Client to the Server to delete a Resource on the 1866
Server. The DELETE request message will carry the following parameters: 1867
fr: Unique identifier of the Client 1868
to: URI of the target resource which is the target of deletion 1869
ri: Identifier of the DELETE request 1870
op: DELETE 1871
Processing by the Server 1872
Following the receipt of a DELETE request, the Server may validate if the Client has the 1873
appropriate rights for deleting the identified resource, and whether the identified resource exists. 1874
If the validation is successful, the Server removes the requested resource and deletes all the 1875
associated information. The Server caches the value of ri parameter in the DELETE request for 1876
use in the response. 1877
DELETE response 1878
The Server shall transmit a DELETE response message in response to a DELETE request 1879
message from a Client. The DELETE response message will include the following parameters. 1880
fr: Unique identifier of the Server 1881
to: Unique identifier of the Client 1882
ri: Identifier included in the DELETE request 1883
rs: The result of the DELETE operation 1884
8.6 NOTIFY 1885
The NOTIFY operation is used to request asynchronous notification of state changes . Complete 1886
description of the NOTIFY operation is provided in section 11.4. The NOTIFY operation uses the 1887
NOTIFICATION response message which is defined here. 1888
8.6.1.1 NOTIFICATION response 1889
The NOTIFICATION response message is sent by a Server to notify the URLs identified by the 1890
Client of a state change. The NOTIFICATION response message carries the following parameters. 1891
fr: Unique identifier of the Server 1892
to: URI of the Resource target of the NOTIFICATION message 1893
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 67
ri: Identifier included in the CREATE request 1894
op: NOTIFY 1895
cn: The updated state of the resource 1896
9 Network and connectivity 1897
9.1 Introduction 1898
The Internet of Things is comprised of a wide range of applications which sense and actuate the 1899
physical world with a broad spectrum of device and network capabilities: from battery powered 1900
nodes transmitting 100 bytes per day and able to last 10 years on a coin cell battery, to mains 1901
powered nodes able to maintain MBit video streams. It is estimated that many 10s of billions of 1902
IoT devices will be deployed over the coming years. 1903
It is desirable that the connectivity options be adapted to the IP layer. To that end, IETF has 1904
completed considerable work to adapt Bluetooth®, Wi-Fi, 802.15.4, LPWAN, etc. to IPv6. These 1905
adaptations, plus the larger address space and improved address management capabilities, make 1906
IPv6 the clear choice for the OCF network layer technology. 1907
9.2 Architecture 1908
While the aging IPv4 centric network has evolved to support complex topologies, its deployment 1909
was primarily provisioned by a single Internet Service Provider (ISP) as a single network. More 1910
complex network topologies, often seen in residential home, are mostly introduced through the 1911
acquisition of additional home network devices, which rely on technologies like private Network 1912
Address Translation (NAT). These technologies require expert assistance to set up correctly and 1913
should be avoided in a home network as they most often result in breakage of constructs like 1914
routing, naming and discovery services. 1915
The multi-segment ecosystem OCF addresses will not only cause a proliferation of new devices 1916
and associated routers, but also new services introducing additional edge routers. All these new 1917
requirements require advance architectural constructs to address complex network topologies like 1918
the one shown in Figure 20. 1919
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 68
1920
Figure 20. High Level Network & Connectivity Architecture 1921
In terms of IETF RFC 6434, IPv6 nodes assume either a router or host role. Nodes may further 1922
implement various specializations of those roles: 1923
A Router may implement Customer Edge Router capabilities as defined in IETF RFC 7084. 1924
Nodes limited in processing power, memory, non-volatile storage or transmission capacity 1925
requires special IP adaptation layers (6LoWPAN) and/or dedicated routing protocols (RPL). 1926
Examples include devices transmitting over low power physical layer like IEEE 802.14.5, ITU 1927
G9959, Bluetooth Low Energy, DECT Ultra Low Energy, Near Field Communication (NFC ). 1928
A node may translate and route messaging between IPv6 and non-IPv6 networks. 1929
9.3 IPv6 network layer requirements 1930
Introduction 1931
Projections indicate that many 10s of billions of new IoT endpoints and related services will be 1932
brought online in the next few years. These endpoint’s capabilities will span from battery powered 1933
nodes with limited compute, storage, and bandwidth to more richly resourced devices operating 1934
over Ethernet and WiFi links. 1935
Internet Protocol version 4 (IPv4), deployed some 30 years ago, has matured to support a wide 1936
variety of applications such as Web browsing, email, voice, video, and critical system monitoring 1937
and control. However, the capabilities of IPv4 are at the point of exhaustion, not the least of which 1938
is that available address space has been consumed. 1939
Sensor Network (6LowPan)
/ Subnets
IPv6 Local Network
IPv4-only or Legacy (Zigbee, …)
Border Router
Gateway (iotivity+ plugins)
IPv6 + IPv4
Internet Core
IPv6 Sensor Network
Non-IPv6 Network
IPv6 Local Network
User Interface
Monitoring
Intrusion detection
Private VPN Service
Internet Services
SP CE Router
Private Proxy
Smart Grid)
SP CE Router
Smart Grid (Energy segment)
Power Grid
Legend: OCF OCF aware OCF plugged-in Infrastructure
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 69
The IETF long ago saw the need for a successor to IPv4, thus the development of IPv6. OCF 1940
recommends IPv6 at the network layer. Amongst the reasons for IPv6 recommendations are: 1941
Larger address space. Side-effect: greatly reduce the need for NATs. 1942
More flexible addressing architecture. Multiple addresses and types per interface: Link-local, 1943
ULA, GUA, variously scoped Multicast addresses, etc. Better ability to support multi -homed 1944
networks, better re-numbering capability, etc. 1945
More capable auto configuration capabilities: DHCPv6, SLAAC, Router Discovery, etc. 1946
Technologies enabling IP connectivity on constrained nodes are based upon IPv6. 1947
All major consumer operating systems (IoS, Android, Windows, Linux) are already IPv6 enabled. 1948
Major Service Providers around the globe are deploying IPv6. 1949
IPv6 node requirements 1950
9.3.2.1 Introduction 1951
In order to ensure network layer services interoperability from node to node, mandating a common 1952
network layer across all nodes is vital. The protocol should enable the network to be: secure, 1953
manageable, scalable and to include constrained and self -organizing meshed nodes. OCF 1954
mandates IPv6 as the common network layer protocol to ensure interoperability across all Devices. 1955
More capable devices may also include additional protocols creating multiple -stack devices. The 1956
remainder of this section will focus on interoperability requirements for IPv6 hosts, IPv6 1957
constrained hosts and IPv6 routers. The various protocol translation permutations included in 1958
multi-stack gateway devices may be addresses in subsequent addendums of this specification. 1959
9.3.2.2 IP Layer 1960
An IPv6 node shall support IPv6 and it shall conform to the requirements as specified in 1961
IETF RFC 6434: 1962
1963
10 Endpoint 1964
10.1 Endpoint definition 1965
The specific definition of an Endpoint depends on the Transport Protocol Suite being used. For the 1966
example of CoAP over UDP over IPv6, the endpoint is identified by an IPv6 address and UDP port 1967
number. 1968
Each OCF Device shall associate with at least one Endpoint with which it can exchange request 1969
and response messages. When a message is sent to an Endpoint, it shall be delivered to the OCF 1970
Device which is associated with the Endpoint. When a request message is delivered to an Endpoint, 1971
path component is enough to locate the target Resource. 1972
OCF Device can be associated with multiple Endpoints. For example, an OCF Device can have 1973
several IP addresses or port numbers or support both CoAP and HTTP transfer protocol. 1974
On the other hand, an Endpoint can be shared among multiple OCF Devices, only when the re is a 1975
way to clearly designate the target Resource with request URI. For example, when multiple CoAP 1976
servers use uniquely different URI paths for all their hosted Resources, and the CoAP 1977
implementation demuxes by path, they can share the same CoAP Endpoint. However, this is not 1978
possible for OIC 1.1 and OCF 1.0 because pre-determined URI (e.g. “/oic/d”) is mandatory for 1979
some mandatory Resources (e.g. "oic.wk.d"). 1980
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 70
10.2 Endpoint information 1981
Introduction 1982
Endpoint is represented by Endpoint information which consis ts of two items of key-value pair, 1983
"ep" and "pri". 1984
“ep” 1985
"ep" represents Transport Protocol Suite and Endpoint Locator specified as follows: 1986
Transport Protocol Suite - a combination of protocols (e.g. CoAP + UDP + IPv6) with which 1987
request and response messages can be exchanged for RESTful transaction (i.e. CRUDN). 1988
Transport Protocol Suites shall be indicated by IANA registered schemes (e.g. "coap" or 1989
"coaps" in Table 12). Vendor or OCF defined schemes are also allowed (e.g. "org.ocf.foo" or 1990
"com.samsung.bar"). 1991
Endpoint Locator – an address (e.g. IPv6 address + Port number) through which a message 1992
can be sent to the Endpoint and in turn associated OCF Device. The Endpoint Locator for 1993
"coap", "coaps", "coap+tcp", "coaps+tcp", "http", and "https" shall be specified as "IP address: 1994
port number". Temporary addresses should not be used because Endpoint Locators are for the 1995
purpose of accepting incoming sessions, whereas temporary addresses are for initiating 1996
outgoing sessions (IETF RFC 4941). Moreover its inclusion in “/oic/res” can cause a privacy 1997
concern (IETF RFC 7721). 1998
"ep" shall have as its value a URI (as specified in IETF RFC 3986) with the scheme component 1999
indicating Transport Protocol Suite and the authority component indicating the Endpoint Locator. 2000
Figure 21 illustrate an exmaple. 2001
2002
"ep": "coap://[fe80::b1d6]:1111"
Figure 21: Example of "ep" 2003
The current list of "ep" with corresponding Transport Protocol Suite is shown in Table 12: 2004
Table 12. “ep” value for Transport Protocol Suite 2005
Transport Protocol Suite
scheme Endpoint Locator "ep" Value example
coap + udp + ip coap IP address + port number coap://[fe80::b1d6]:1111
coaps + udp + ip coaps IP address + port number coaps://[fe80::b1d6]:1122
coap + tcp + ip coap+tcp IP address + port number coap+tcp://[2001:db8:a::123]:2222
coaps + tcp + ip coaps+tcp IP address + port number coaps+tcp://[2001:db8:a::123]:2233
http + tcp + ip http IP address + port number http://[2001:db8:a::123]:1111
https + tcp + ip https IP address + port number https://[2001:db8:a::123]:1122
“pri” 2006
When there are multiple Endpoints, "pri" indicates the priority among them. 2007
"pri" shall be represented as a positive integer (e.g. "pri": 1) and the lower the value, the higher 2008
the priority. 2009
The default "pri" value is 1, i.e. when "pri" is not present, it shall be equivalent to "pri": 1. 2010
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 71
Endpoint information in "eps" Parameter 2011
To carry Endpoint information, a new Link Parameter "eps" is defined in 7.8.2.1.6. "eps" has an 2012
array of items as its value and each item represents Endpoint information with two key-value pairs, 2013
"ep" and "pri", of which "ep" is mandatory and "pri" is optional. Figure 22 illustrates a link with 2014
"eps". 2015
2016
{
"anchor": "ocf://light_device_id",
"href": "/myLightSwitch",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, {"ep":
"coaps://[fe80::b1d6]:1122"}]
}
Figure 22: Example of Link with "eps" Parameter 2017
In Figure 22, "anchor" represents the hosting OCF Device, "href", target Resource and "eps" the 2018
two Endpoints for the target Resource. 2019
If the target Resource of a Link requires a secure connection (e.g. CoAPS), "eps" Parameter shall 2020
be used to indicate the necessary information (e.g. port number) in OCF 1.0 payload, because 2021
"sec" and "port" shall be used only in OIC 1.1 payload. 2022
10.3 Endpoint discovery 2023
Introduction 2024
"Endpoint discovery" is defined as the process for a Client to acquire the Endpoint information for 2025
OCF Device or Resource. 2026
Implicit discovery 2027
If a Device is the source of a CoAP message (e.g. “/oic/res” response), the source IP address and 2028
port number can be combined to form the Endpoint Locator for the Device. Along with a "coap" 2029
scheme and default “pri” value, Endpoint information for the Device can be constructed. 2030
In other words, an “/oic/res” response message with CoAP can implicitly carry the Endpoint 2031
information of the responding Device and in turn all the hosted Resources, which can be accessed 2032
with the same transfer protocol of CoAP. 2033
Explicit discovery with “/oic/res” response 2034
Endpoint information can be explicitly indicated with the "eps" Parameter of the Links in “/oic/res”. 2035
As in 10.3.2, an “/oic/res” response can implicitly indicate the Endpoint information for the target 2036
Resources hosted by the responding Device. However “/oic/res” may expose a target Resource 2037
which belongs to another Device. When the Endpoint for a target Resource of a Link cannot be 2038
implicitly inferred, the "eps" Parameter shall be included to provide explicit Endpoint information 2039
with which a Client can access the target Resource. 2040
This applies to the case of “/oic/res” for a Resource Directory or Bridge Device which usually 2041
carries the Links for Resources which another Device hosts. 2042
Figure 23 is a “/oic/res” response with the "eps" Parameter in Links. 2043
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 72
2044
[
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/oic/res",
"rel": "self",
"rt": ["oic.wk.res"],
"if": ["oic.if.ll", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:55555"},
{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/oic/d",
"rt": ["oic.wk.d", "oic.d.bridge"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:55555"},
{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/oic/p",
"rt": ["oic.wk.p"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/mySecureMode",
"rt": ["oic.r.securemode"],
"if": ["oic.if.rw", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/oic/sec/doxm",
"rt": ["oic.r.doxm"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:55555"},
{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/oic/sec/pstat",
"rt": ["oic.r.pstat"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/oic/sec/cred",
"rt": ["oic.r.cred"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 73
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/oic/sec/acl2",
"rt": ["oic.r.acl2"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/myIntrospection",
"rt": ["oic.wk.introspection"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/oic/res",
"rt": ["oic.wk.res"],
"if": ["oic.if.ll", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"},
{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/oic/d",
"rt": ["oic.wk.d", "oic.d.light", "oic.d.virtual"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"},
{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/oic/p",
"rt": ["oic.wk.p"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/myLight",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/oic/sec/doxm",
"rt": ["oic.r.doxm"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"},
{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 74
"href": "/oic/sec/pstat",
"rt": ["oic.r.pstat"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
}, {
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/oic/sec/cred",
"rt": ["oic.r.cred"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/oic/sec/acl2",
"rt": ["oic.r.acl2"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",
"href": "/myLightIntrospection",
"rt": ["oic.wk.introspection"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/oic/res",
"rt": ["oic.wk.res"],
"if": ["oic.if.ll", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"},
{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/oic/d",
"rt": ["oic.wk.d", "oic.d.fan", "oic.d.virtual"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"},
{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/oic/p",
"rt": ["oic.wk.p"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/myFan",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 75
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/oic/sec/doxm",
"rt": ["oic.r.doxm"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"},
{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/oic/sec/pstat",
"rt": ["oic.r.pstat"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/oic/sec/cred",
"rt": ["oic.r.cred"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/oic/sec/acl2",
"rt": ["oic.r.acl2"],
"if": ["oic.if.baseline"],
"p": {"bm": 1},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
},
{
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",
"href": "/myFanIntrospection",
"rt": ["oic.wk.introspection"],
"if": ["oic.if.r", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]
}
]
Figure 23: Example of “/oic/res” with Endpoint information 2045
The exact format of the “/oic/res” response and a way for a Client to acquire a “/oic/res” response 2046
message is specified in D.10 and 11.3.5 respectively. 2047
10.4 CoAP based Endpoint discovery 2048
The following describes CoAP based Endpoint discovery: 2049
a) Advertising or publishing Devices shall join the ‘All OCF Nodes’ multicast groups (as defined 2050
in [IANA IPv6 Multicast Address Space Registry]) with scopes 2, 3, and 5 (i.e., ff02::158, 2051
ff03::158 and ff05::158) and shall listen on the port 5683. For compliance to IETF RFC 7252 a 2052
Device may additionally join the ‘All CoAP Nodes’ multicast groups. 2053
b) Clients intending to discover resources shall join the multicast groups as defined in a). 2054
c) Clients shall send discovery requests (GET request) to the 'All OCF Nodes’ multicast group 2055
address with scope 2 (ff02::158) at port 5683. The requested URI shall be “/oic/res”. For 2056
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 76
compliance to IETF RFC 7252 a Client may additionally send to the ‘All CoAP Nodes’ multicast 2057
groups. 2058
d) If the discovery request is intended for a specific Resource Type, the Query parameter "rt" shall 2059
be included in the request (section 6.2.1) with its value set to the desired Resource Type. Only 2060
Devices hosting the Resource Type shall respond to the discovery request. 2061
e) When the “rt” Query parameter is omitted, all Devices shall respond to the discovery request. 2062
f) Handling of multicast requests shall be as described in section 8 of IETF RFC 7252 and section 2063
4.1 in IETF RFC 6690. 2064
g) Devices which receive the request shall respond using CBOR payload encoding. A Device shall 2065
indicate support for CBOR payload encoding for multicast discovery as described in section 2066
12.4. Later versions of the specification may support alternate payload encodings (JSON, 2067
XML/EXI, etc.). 2068
11 Functional interactions 2069
11.1 Introduction 2070
The functional interactions between a Client and n Server are described in section 11.2 through 2071
section 11.6 respectively. The functional interactions use CRUDN messages (section 8) and 2072
include Discovery, Notification, and Device management. These functions require support of core 2073
defined resources as defined in Table 13. More details about these resources are provided later 2074
in this section. 2075
Table 13. List of Core Resources 2076
Pre-defined URI
Resource Name Resource Type Related Functional Interaction
Mandatory
“/oic/res” Default “oic.wk.res” Discovery Yes
“/oic/p” Platform oic.wk.p Discovery Yes
/oic/d Device “oic.wk.d” Discovery Yes
(none) Configuration oic.wk.con Device Management
No
“/oic/mnt” Maintenance “oic.wk.mnt” Device Management
No
2077
11.2 Onboarding, Provisioning and Configuration 2078
Onboarding and Provisioning are fully defined by the OCF Security Specification. 2079
2080
Should a Device support Client update of configurable information it shall do so via exposing the 2081
Core Resource “/example/oic/con” (Table 14) in “/oic/res”; 2082
2083
Table 14. Configuration Resource 2084
Example URI
Resource Type Title
Resource Type ID (“rt” value)
Interfaces Description Related Functional Interaction
“/example/oic/con”
Device Configuration
“oic.wk.con”
“oic.if.rw” The Resource Type through which configurable information specific to the Device is exposed.
Configuration
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 77
The resource properties exposed in “oic.wk.con” are listed in Table 15.
“/example/oic/con”
Platform Configuration
“oic.wk.con.p”
“oic.if.rw” The optional Resource Type through which configurable information specific to the Platform is exposed. The resource properties exposed in “oic.wk.con.p” are listed in Table 16.
Configuration
2085
Table 15 defines the “oic.wk.con” resource type. 2086
2087
Table 15. “oic.wk.con” Resource Type definition 2088
Property title Property name Value type
Value rule
Unit Access mode
Mandatory Description
(Device) Name
n (Common Property of “/example/oic/con”)
string R, W yes Human friendly name configurable by the end user (e.g. Bob's thermostat). "n" Common Property of"/example/oic/con” and "n" Common Property “/oic/d” shall have the same Value. When the "n" Common Property Value of “/example/oic/con” is modified, it shall be reflected to the "n" Common Property of “/oic/d”.
Location loc array of float (has two elements, the first is latitude, the second is longitude)
Degrees R, W no Provides location information where available.
Location Name
locn string R, W no Human friendly name for location For example, “Living Room”.
Currency c string R,W no Indicates the currency that is used for any monetary transactions
Region r string R,W no Free form text Indicating the current region in which the device is located geographically. The free form text shall not start with a quote (").
Localized Names
ln array R,W no Human-friendly name of the Device, in one or more languages. This property is an array of objects where each object has a ‘language’ field (containing an IETF RFC 5646 language tag) and a ‘value’ field
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 78
containing the device name in the indicated language. If this property and the Device Name (n) property are both supported, the Device Name (n) value shall be included in this array.
Default Language
dl language-tag
R,W no The default language supported by the Device, specified as an IETF RFC 5646 language tag. By default, clients can treat any string property as being in this language unless the property specifies otherwise.
2089
Table 16 defines the “oic.wk.con.p” resource type. 2090
Table 16. “oic.wk.con.p” Resource Type definition 2091
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Platform Names mnpn array R,W no Friendly name of the Platform. This property is an array of objects where each object has a ‘language’ field (containing an IETF RFC 5646 language tag) and a ‘value’ field containing the platform friendly name in the indicated language.
For example,
[{“language”:”en”, “value”:”Dave’s Laptop”}]
2092
2093
11.3 Resource discovery 2094
Introduction 2095
Discovery is a function which enables endpoint discovery as well as resource based discovery. 2096
Endpoint discovery is described in detail in section 10. This section mainly describes the resource 2097
based discovery. 2098
Resource based discovery: mechanisms 2099
11.3.2.1 Overview 2100
As part of discovery, a Client may find appropriate information about other OCF peers. This 2101
information could be instances of Resources, Resource Types or any other information 2102
represented in the resource model that an OCF peer would want another OCF peer to discover. 2103
At the minimum, Resource based discovery uses the following: 2104
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 79
1) A resource to enable discovery shall be defined. The representation of that resource shall 2105
contain the information that can be discovered. 2106
2) The resource to enable discovery shall be specified and commonly known a -priori.A Device for 2107
hosting the resource to enable discovery shall be identified. 2108
3) A mechanism and process to publish the information that needs to be discovered with the 2109
resource to enable discovery. 2110
4) A mechanism and process to access and obtain the information from the resource to enable 2111
discovery. A query may be used in the request to limit the returned information. 2112
5) A scope for the publication 2113
6) A scope for the access. 2114
7) A policy for visibility of the information. 2115
2116
Depending on the choice of the base aspects defined above, the Framework defines three resource 2117
based discovery mechanisms: 2118
Direct discovery, where the Resources are published locally at the Device hosting the 2119
resources and are discovered through peer inquiry. 2120
Indirect discovery, where Resources are published at a third party assisting with the 2121
discovery and peers publish and perform discovery against the resource to enable 2122
discovery on the assisting 3rd party. 2123
Advertisement discovery, where the resource to enable discovery is hosted local to the 2124
initiator of the discovery inquiry but remote to the Devices that are publishing discovery 2125
information. 2126
A Device shall support direct discovery. 2127
11.3.2.2 Direct discovery 2128
In direct discovery, 2129
1) The Device that is providing the information shall host the resource to enable discovery. 2130
2) The Device publishes the information available for discovery with the local resource to 2131
enable discovery (i.e. local scope). 2132
3) Clients interested in discovering information about this Device shall issue RETRIEVE 2133
requests directly to the resource. The request may be made as a unicast or multicast. 2134
The request may be generic or may be qualified or limited by using appropriate queries in 2135
the request. 2136
4) The “server” Device that receives the request shall send a response with the discovered 2137
information directly back to the requesting “client” Device. 2138
5) The information that is included in the request is determined by the policies set for the 2139
resource to be discovered locally on the responding Device. 2140
2141
11.3.2.3 Indirect discovery of Resources (resource directory based discovery) 2142
In indirect discovery the information about the resource to be discovered is hosted on a Server 2143
that is not hosting the resource. See section 11.3.6 for details on resource directory based 2144
discovery. 2145
In indirect discovery: 2146
a) The resource to be discovered is hosted on a Device that is neither the client initiating 2147
the discovery nor the Device that is providing or publishing the information to be 2148
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 80
discovered. This Device may use the same resource to provide discovery for multiple 2149
agents looking to discover and for multiple agents with information to be discovered. 2150
b) The Device to be discovered or with information to discover, publishes that information 2151
with resource to be discovered on a different Device. The policies on the information 2152
shared including the lifetime/validity are specified by the publishing Device. The 2153
publishing Device may modify these policies as required. 2154
c) The client doing the discovery may send a unicast discovery request to the Device 2155
hosting the discovery information or send a multicast request that shall be monitored and 2156
responded to by the Device. In both cases, the Device hosting the discovery information 2157
is acting on behalf of the publishing Device. 2158
d) The discovery policies may be set by the Device hosting the discovery information or by 2159
the party that is publishing the information to be discovered. The discovery information 2160
that is returned in the discovery response shall adhere to the policies that are in effect at 2161
the time of the request. 2162
2163
11.3.2.4 Advertisement Discovery 2164
In advertisement discovery: 2165
a) The resource to enable discovery is hosted local to the Device that is initiating the discovery 2166
request (client). The resource to enable discovery may be an Core Resource or discovered 2167
as part of a bootstrap. 2168
b) The request could be an implementation dependent lookup or be a local RETRIEVE request 2169
against the resource that enables discovery. 2170
c) The Device with information to be discovered shall publish the appropriate information to 2171
the resource that enables discovery. 2172
d) The publishing Device is responsible for the published information. The pub lishing Device 2173
may UPDATE the information at the resource to enable discovery based on its needs by 2174
sending additional publication requests. The policies on the information that is discovered 2175
including lifetime is determined by the publishing Device. 2176
2177
Resource based discovery: Information publication process 2178
The mechanism to publish information with the resource to enable discovery can be done either 2179
locally or remotely. The publication process is depicted in Figure 24. The Device which has 2180
discovery information to publish shall a) either update the resource that enables discovery if 2181
hosted locally or b) issue an UPDATE request with the information to the Device which hosts the 2182
resource that enables discovery. The Device hosting the resource to enable discovery 2183
adds/updates the resource to enable discovery with the provided information and then responds 2184
to the Device which has requested the publication of the resource with an UPDATE response. 2185
2186
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 81
OIC Client(Registering resources)
OIC Server(Hosting the designated
OIC Resource)
1. UPDATE Request
3. UPDATE Response
2. Entry updated in /oic/res
2187
Figure 24. Resource based discovery: Information publication process 2188
Resource based discovery: Finding information 2189
The discovery process (Figure 25) is initiated as a RETRIEVE request to the resource to enable 2190
discovery. The request may be sent to a single Device (as in a Unicast) or to multiple Devices (as 2191
in Multicast). The specific mechanisms used to do Unicast or Multicast are determined by the 2192
support in the data connectivity layer. The response to the request has the information to be 2193
discovered based on the policies for that information. The policies can determine which information 2194
is shared, when and to which requesting agent. The information that can be discovered can be 2195
resources, types, configuration and many other standards or custom aspects depending on the 2196
request to appropriate resource and the form of request. Optionally the requester may narrow the 2197
information to be returned in the request using query parameters in the URI query. 2198
OIC Client OIC Server(s)
1. RETRIEVE Request
3. RETRIEVE Response
2. Discovery inquiry processed
2199
Figure 25. Resource based discovery: Finding information 2200
2201
Discovery Resources 2202
Some of the Core Resources shall be implemented on all Devices to support discovery. The Core 2203
Resources that shall be implemented to support discovery are: 2204
“/oic/res” for discovery of resources 2205
“/oic/p” for discovery of platform 2206
“/oic/d” for discovery of device information 2207
Details for these mandatory Core Resources are described in Table 17 2208
Platform resource – 2209
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 82
The OCF recognizes that more than one instance of Device may be hosted on a single platform. 2210
Clients need a way to discover and access the information on the platform. The core resource, 2211
“/oic/p” exposes platform specific properties. All instances of Device on the same Platform shall 2212
have the same values of any propert ies exposed (i.e. a Device may choose to expose optional 2213
properties within “/oic/p” but when exposed the value of that property should be the same as the 2214
value of that property on all other Devices on that Platform) 2215
2216
Device resource 2217
The device resource shall have the pre-defined URI “/oic/d”. The resource “/oic/d” exposes the 2218
properties pertaining to a Device as defined in Table 17. The properties exposed are determined 2219
by the specific instance of Device and defined by the Resource Type(s) of “/oic/d” on that Device. 2220
Since all the Resource Types of “/oic/d” are not known a priori, the Resource Type(s) of “/oic/d” 2221
shall be determined by discovery through the core resource “/oic/res”. The device resource “/oic/d” 2222
shall have a default Resource Type that helps in bootstrapping the interactions with this device 2223
(the default type is described in Table 17.) 2224
2225
Protocol indication 2226
A Device may need to support different messaging protocols depending on requirements for 2227
different application profiles. For example, the Smart Home profile may use CoAP and the 2228
Industrial profile may use DDS. To enable interoperability, a Device uses the protocol indication 2229
to indicate the transport protocols they support and can communicate over . 2230
2231
Table 17. Mandatory discovery Core Resources 2232
Pre-defined URI
Resource Type Title
Resource Type ID (“rt” value)
Interfaces Description Related Functional Interaction
“/oic/res”
Default “oic.wk.res”
“oic.if.ll” The resource through which the corresponding Server is discovered and introspected for available resources.
“/oic/res” shall expose the resources that are discoverable on a Device. When a Server receives a RETRIEVE request targeting “/oic/res” (e.g., “GET /oic/res”), it shall respond with the link list of all the discoverable resources of itself. The “/oic/d” and “/oic/p” are discoverable resources, hence their links are included in “/oic/res” response. The resource properties exposed by “/oic/res” are listed in Table 18.
Discovery
“/oic/p”
Platform “oic.wk.p” “oic.if.r” The discoverable resource through which platform specific information is discovered.
The resource properties exposed by “/oic/p” are listed in Table 21
Discovery
“/oic/d”
Device “oic.wk.d” and/or one Device Specific Resource Type ID
“oic.if.r” The discoverable via “/oic/res” resource which exposes properties specific to the Device instance.
The resource properties exposed by “/oic/d” are listed in Table 20
“/oic/d” may have one Resource Type that is specific to the Device in addition to the default Resource Type or if present overriding the default Resource Type.
The base type “oic.wk.d” defines the properties that shall be exposed by all Devices.
The device specific Resource Type exposed is dependent on the class of device (e.g. air conditioner, smoke alarm); applicable values are defined by the vertical specifications.
Discovery
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 83
2233
Table 18 defines “oic.wk.res” Resource Type. 2234
Table 18. “oic.wk.res” Resource Type definition 2235
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Name n string R no Human-friendly name defined by the vendor
Links links array See 7.8.2
R yes The array of Links describes the URI, supported Resource Types and interfaces, and access policy.
Messaging Protocol
mpro SSV R No String with Space Separated Values (SSV) of messaging protocols supported as a SI Number from Table 19
For example, “1 and 3” indicates that the Device supports coap and http as messaging protocols.
A Device which wants to indicate its messaging protocol capabilities may add the property ‘mpr o’ 2236
in response to a request on “/oic/res”. A Device shall support CoAP based discovery as the 2237
baseline discovery mechanism (see section 10.4). A Client which sees this property in a discovery 2238
response can choose any of the supported messaging protocols for communicating with the Server 2239
for further messages. For example, if a Device supporting multiple protocols indicates it supports 2240
a value of “1 3” for the ‘mpro’ property in the discovery response, then it cannot be assumed that 2241
there is an implied ordering or priority. But a vertical service specification may choose to specify 2242
an implied ordering or priority. If the ‘mpro’ property is not present in the response, A Client shall 2243
use the default messaging protocol as specified in the vertical specification for further 2244
communication. 2245
The “/oic/res” shall list all Resources that are indicated as discoverable (see section 11.3). Also 2246
the following architecture Resource Types shall be listed: 2247
Introspection resource indicated with an “rt” value of “oic.wk.introspection” 2248
“/oic/p” indicated with an “rt” value of “oic.wk.p” 2249
“/oic/d” indicated with an “rt” value of “oic.wk.d” 2250
“/oic/sec/doxm” indicated with an “rt” value of “oic.r.doxm” 2251
“/oic/sec/pstat” indicated with an “rt” value of “oic.r.pstat” 2252
Conditionally required: 2253
“/oic/res” with an "rt" value of "oic.wk.res" as self-reference, on the condition that “oic/res” has 2254
to signal that it is observable by a Client. 2255
The Introspection Resource is only applicable for Devices that host Vertical Resource Types (e.g. 2256
“oic.r.switch.binary”) or vendor-defined Resource Types. Devices that only host Resources 2257
required to onboard the Device as a Client do not have to implement the Introspection Resource. 2258
Table 19 provides an OCF registry for protocol schemes. 2259
Table 19. Protocol scheme registry 2260
SI Number Protocol
1 coap
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 84
2 coaps
3 http
4 https
5 coap+tcp
6 coaps+tcp
Note: The discovery of an endpoint used by a specific protocol is out of scope. The mechanism used by a Client to form 2261 requests in a different messaging protocol other than discovery is out of scope. 2262
2263
The following applies to the use of “/oic/d” as defined above: 2264
A vertical may choose to expose its Device Type (e.g., refrigerator or A/C) by adding the Device 2265
Type to the list of Resource Types associated with “/oic/d”. 2266
o For example; “rt” of “/oic/d” becomes ["oic.wk.d", "oic.d.<thing>"]; where 2267
“oic.d.<thing>” is defined in another spec such as the Smart Home vertical. 2268
o This implies that the properties exposed by “/oic/d” are by default the mandatory 2269
properties in Table 20. 2270
A vertical may choose to extend the list of properties defined by the Resource Type 'oic.wk.d'. 2271
In that case, the vertical shall assign a new Device Type specific Resource Type ID. The 2272
mandatory properties defined in Table 20 shall always be present. 2273
Table 20 “oic.wk.d” Resource Type definition defines the base Resource Type for the “/oic/d” 2274
resource. 2275
2276
Table 20. “oic.wk.d” Resource Type definition 2277
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
(Device) Name n string R no Human friendly name defined by the vendor.” In the presence of "n" Property of “/oic/con”, both have the same Property Value. When "n" Property Value of “/oic/con” is modified, it shall be reflected to "n" Property Value of “/oic/d”.
Spec Version icv string R yes Spec version of the core specification this device is implemented to, The syntax is "ocf.<major>.<minor>.<sub-version>” where <major>, <minor, and <sub-version> are the major, minor and sub-version numbers of the specification respectively. This version of the specification the string value shall be “ocf.1.0.0”.
Device ID di uuid R yes Unique identifier for Device. This value shall be the same value (i.e. mirror) as the doxm.deviceuuid Property as defined in OCF Security. Handling privacy-sensitivity for the “di” Property, refer to section 13.8 in OCF Security.
Data Model Version
dmv csv R yes Spec version of the Resource Specification to which this device data model is implemented; if
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 85
implemented against a Vertical specific device specification(s), then the Spec version of the vertical specification this device model is implemented to. The syntax is a comma separated list of ” <res>.<major>.<minor>.<sub-version> or <vertical>.<major>.<minor>.<sub-version>. <res> is the string “ocf.res” and <vertical> is the name of the vertical defined in the Vertical specific resource specification. The <major>, <minor>, and <sub-version> are the major, minor and sub-version numbers of the specification respectively. This version of the specification one entry in the csv string shall be“ocf.res.1.0.0”. Another entry in the csv shall be the vertical(s) being (e.g. “ocf.sh.1.0.0”).. This value may be extended by the vendor. The syntax for extending this value, as a comma separated entry, by the vendor shall be by adding x.<Domain_Name>.<vendor_string>. For example “ocf.res.1.0.0, ocf.sh.1.0.0, x.com.example.string”, The order of the values in the comma separated string can be in any order (i.e. no prescribed order). This property shall not exceed 256 octets.
Protocol Independent ID
piid UUID R yes A unique and immutable Device identifier. A Client can detect that a single Device supports multiple communication protocols if it discovers that the Device uses a single Protocol Independent ID value for all the protocols it supports. Handling privacy-sensitivity for the “piid” Property, refer to section 13.8 in OCF Security.
Localized Descriptions
ld array R no Detailed description of the Device, in one or more languages. This property is an array of objects where each object has a ‘language’ field (containing an IETF RFC 5646 language tag) and a ‘value’ field containing the device description in the indicated language.
Software Version
sv string R no Version of the device software.
Manufacturer Name
dmn array R no Name of manufacturer of the Device, in one or more languages. This property is an array of objects where each object has a ‘language’ field (containing an IETF RFC 5646 language tag) and a ‘value’ field containing the manufacturer name in the indicated language.
Model Number dmno string R no Model number as designated by manufacturer.
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 86
2278
The additional Resource Type(s) of the “/oic/d” resource are defined by the vertical specification. 2279
2280
Table 21 defines “oic.wk.p” Resource Type. 2281
2282
Table 21. “oic.wk.p” Resource Type definition 2283
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Platform ID pi string R yes Unique identifier for the physical platform (UIUID); this shall be a UUID in accordance with IETF RFC 4122. It is recommended that the UUID be created using the random generation scheme (version 4 UUID) specific in the RFC. Handling privacy-sensitivity for the “pi” Property, refer to section 13.8 in OCF Security.
Manufacturer Name
mnmn string R yes Name of manufacturer
Manufacturer Details Link
mnml uri R no Reference to manufacturer, represented as a URI
Model Number mnmo string R no Model number as designated by manufacturer
Date of Manufacture
mndt date Time (show RFC)
R no Manufacturing date of Platform.
Platform Version mnpv string R no Version of platform – string (defined by manufacturer)
OS Version mnos string R no Version of platform resident OS – string (defined by manufacturer)
Hardware Version
mnhw string R no Version of platform hardware
Firmware version
mnfv string R no Version of Platorm firmware
Support link mnsl uri R no URI that points to support information from manufacturer
SystemTime st date-time R no Reference time for the Platform.
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 87
Vendor ID vid string R no Vendor defined string for the platform. The string is freeform and up to the vendor on what text to populate it.
2284
Composite Device 2285
A physical device may be modelled as a single device or as a composition of other devices. For 2286
example a refrigerator may be modelled as a composition, as such part of its definition of may 2287
include a sub-tending thermostat device which itself may be composed of a sub-tending 2288
thermometer device. 2289
There may be more than one way to model a server as a composition. One example method would 2290
be to have Platform which represents the composite device to have more than one instance of a 2291
Device on the Platform. Each Device instance represents one of the distinct devices in the 2292
composition. Each instance of Device may itself have or host multiple instances of other resources. 2293
An implementation irrespective of how it is composed shall only expose a single instance of “/oic/d” 2294
with an ‘rt’ of choice for each logical Server. 2295
Thus, for the above refrigerator example if modeled as a single Server; “/oic/res” would expose 2296
“/oic/d” with a Resource Type name appropriate to a refrigerator. The sub-tending thermostat and 2297
thermometer devices would be exposed simply as instances of a resource with a device 2298
appropriate Resource Type with an associated URI assigned by the implementation; e.g., 2299
/MyHost/MyRefrigerator/Thermostat and /MyHost/MyRefrigerator/Thermostat/Thermometer. 2300
2301
Resource discovery using “/oic/res” 2302
Discovery using “/oic/res” is the default discovery mechanism that shall be supported by all Devices 2303
as follows: 2304
a) Every Device updates its local “/oic/res” with the resources that are discoverable (see section 2305
7.3.2.2). Every time a new resource is instantiated on the Device and if that resource is 2306
discoverable by a remote Device then that resource is published with the “/oic/res” resource 2307
that is local to the Device (as the instantiated resource). 2308
b) A Device wanting to discover resources or Resource Types on one or more remote Devices 2309
makes a RETRIEVE request to the “/oic/res” on the remote Devices. This request may be sent 2310
multicast (default) or unicast if only a specific host is to be probed. The RETRIEVE request 2311
may optionally be restricted using appropriate clauses in the query portion of the request. 2312
Queries may select based on Resource Types, interfaces, or properties. 2313
c) The query applies to the representation of the resources. “/oic/res” is the only resource whose 2314
representation has “rt”. So “/oic/res” is the only resource that can be used for Multicast 2315
discovery at the transport protocol layer. 2316
d) The Device receiving the RETRIEVE request responds with a list of resources, the Resource 2317
Type of each of the resources and the interfaces that each resource supports. Additionally, 2318
information on the policies active on the resource can also be sent. The policy supported 2319
includes observability and discoverability. (More details below) 2320
e) The receiving Device may do a deeper discovery based on the resources returned in the 2321
request to “/oic/res”. 2322
2323
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 88
The information that is returned on discovery against “/oic/res” is at the minimum: 2324
The URI (relative or fully qualified URL) of the resource 2325
The Resource Type(s) of each resource. More than one Resource Type may be returned if the 2326
resource enables more than one type. To access resources of multiple types, the specific 2327
Resource Type that is targeted shall be specified in the request. 2328
The Interfaces supported by that Resource. Multiple interfaces may be returned. To access a 2329
specific interface that interface shall be specified in the request. If the interface is not specified, 2330
then the Default Interface is assumed. 2331
Different “/oic/res” responses are returned according to requesting Clients, which indicate their 2332
preference with Content Format in Accept Option. OCF 1.0 Clients request with the Content Format 2333
of “application/vnd.ocf+cbor”, whereas the absence of that Content Format 2334
(i.e.”application/vnd.ocf+cbor”) indicates OIC 1.1 Clients. 2335
For OIC 1.1 Clients, “/oic/res” response shall use "sec" and "port" to provide the information for an 2336
encrypted connection. 2337
For OCF 1.0 Clients, “/oic/res” response only includes the “array of Links to conform to 2338
IETF RFC 6690. Each Link shall use "eps" Parameter to provide the information f or an encrypted 2339
connection and carry "anchor" of the value OCF URI where the authority component of <deviceID> 2340
indicates the Device hosting the target Resource. 2341
The JSON schemas for discovery using “/oic/res” are described in D.10. Also refer to Section 10 2342
(Endpoint Discovery) for details of Multicast discovery using “/oic/res” on a CoAP transport. 2343
For example, a Light device might return the following to OIC 1.1 clients: 2344
[ 2345
{ 2346
"di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 2347
"links": [ 2348
{ 2349
"href": "coaps://[fe80::b1d6]:44444/oic/res", 2350
"rel": "self", 2351
"rt": ["oic.wk.res"], 2352
"if": ["oic.if.ll", "oic.if.baseline"], 2353
"p": {"bm": 3} 2354
}, 2355
{ 2356
"href": "/oic/p", 2357
"rt": ["oic.wk.p"], 2358
"if": ["oic.if.r", "oic.if.baseline"], 2359
"p": {"bm": 3, "sec": true, "port": 11111} 2360
}, 2361
{ 2362
"href": "/oic/d", 2363
"rt": ["oic.wk.d", "oic.d.light"], 2364
"if": ["oic.if.r", "oic.if.baseline"], 2365
"p": {"bm": 3, "sec": true, "port": 11111} 2366
}, 2367
{ 2368
"href": "/myLight", 2369
"rt": ["oic.r.switch.binary"], 2370
"if": ["oic.if.a", "oic.if.baseline"], 2371
"p": {"bm": 3, "sec": true, "port": 11111} 2372
} 2373
] 2374
} 2375
] 2376
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 89
The light device might return the following to clients that request with the Content Format of 2377
“application/vnd.ocf+cbor” in Accept Option: 2378
[ 2379
{ 2380
"href": "/oic/res", 2381
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989/oic/res", 2382
"rel": "self", 2383
"rt": ["oic.wk.res"], 2384
"if": ["oic.if.ll", "oic.if.baseline"], 2385
"p": {"bm": 3}, 2386
"eps": [{"ep": "coap://[fe80::b1d6]:44444"}] 2387
}, 2388
{ 2389
"href": "/oic/p", 2390
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989, 2391
"rt": ["oic.wk.p"], 2392
"if": ["oic.if.r", "oic.if.baseline"], 2393
"p": {"bm": 3}, 2394
"eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2395
{"ep": "coaps://[fe80::b1d6]:11111"} 2396
] 2397
}, 2398
{ 2399
"href": "/oic/d", 2400
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989, 2401
"rt": ["oic.wk.d", "oic.d.light"], 2402
"if": ["oic.if.r", "oic.if.baseline"], 2403
"p": {"bm": 3}, 2404
"eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2405
{"ep": "coaps://[fe80::b1d6]:11111"} 2406
] 2407
}, 2408
{ 2409
"href": "/myLight", 2410
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989, 2411
"rt": ["oic.r.switch.binary"], 2412
"if": ["oic.if.a", "oic.if.baseline"], 2413
"p": {"bm": 3}, 2414
"eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2415
{"ep": "coaps://[fe80::b1d6]:11111"} 2416
] 2417
} 2418
] 2419
After performing discovery using “/oic/res”, Clients may discover additional details about Server 2420
by performing discovery using “/oic/p”, /oic/rts etc. If a Client already knows about Server it may 2421
discover using other resources without going through the discovery of “/oic/res”. 2422
Resource directory (RD) based discovery 2423
11.3.6.1 Introduction 2424
11.3.6.1.1 Indirect discovery for lookup of the resources 2425
Direct discovery is the mechanism used currently to find resources in the network. When needed, 2426
resources are queried at a particular node directly or a multicast packet is sent to all nodes . Each 2427
queried node responds directly with its discoverable resources to the discovering device. 2428
Resources available locally are registered on the same device. 2429
In some situations, one of the other mechanisms described in section 11.3.2.3, called indirect 2430
discovery, may be required. Indirect discovery is when a 3rd party device, other than the 2431
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 90
discovering device and the discovered device, assists with the discovery process. The 3rd party 2432
only provides information on resources on behalf of another device but does not host resources 2433
on part of that device. 2434
2435
Figure 26. Indirect discovery of resource by resource directory 2436
Indirect discovery is useful for a resource constrained device that needs to sleep to manage power 2437
and cannot process every discovery request, or when devices may not be on the same network 2438
and requires optimization for discovery. Once resources are discovered using indirect discovery 2439
then the access to the resource is done by a request directly to the Device that hosts that resource. 2440
11.3.6.1.2 Resource directory 2441
A resource directory (RD) is a Device that assists with indirect discovery. A Device which acts as 2442
an RD will be involved in the following operations. 2443
RD discovery – the procedure with which OCF Devices discover an RD and acquire the criteria 2444
to select one among multiple RDs. 2445
Resource publish – the procedures with which OCF Devices publish their Resource 2446
information, i.e. Links, subsequently update the published Links or deletes the ones. 2447
Resource exposure – the feature with which RDs expose the Links hosted by the 3 rd party 2448
Devices via their “/oic/res”. 2449
For the above, RDs make use of a core Resource Type “/oic/rd” i.e., “oic.wk.rd” defined in Table 2450
22 and Table 23. A Device exposes “oic.wk.rd” in its “/oic/res” to announce that it serves as an RD 2451
along with selection criteria. A publishing Device can send POST request to “/oic/rd” with its Links 2452
in the payload to publish or update the Links in “/oic/res” of the RD. Also the publishing Device can 2453
send DELETE request to “/oic/rd” to delete the existing Links from “/oic/res” of the RD. 2454
Table 22. “oic.wk.rd” Resource Type definition 2455
Pre-defined URI
Resource Type Title
Resource Type ID (“rt” value)
Interfaces Description Related Functional Interaction
OCF Device A
OCF Device B
OCF Device C
/oic/res
/oic/res
OCF Device D
/oic/res Multicast Group
Multicast Discovery Request by
Unicast Response with resources for Devices A, B and D
Publish (to /oic res)
Device B acts as Resource Directory for Device A and Device D; Device A and D do not respond to multicast query
Publish (to /oic res)
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 91
“/oic/rd”
Resource directory
“oic.wk.rd” “oic.if.baseline”
The discoverable Resource Type through with which an RD 1) facilitates its discovery and provides the criteria to select an RD and 2) allows OCF Devices to publish, update and delete their Links in “/oic/res” of the RD.
A Device can find the presence of “oic.wk.rd” to discover an RD, then sends GET request to “/oic/rd” to acquire the selection criteria. An OCF Device can send POST request with Links in its payload to expose those Links in “/oic/res” of the RD. Also OCF Device can send DELTE request with suitable query (e.g. “di” or “ins”) to remove its Links from “/oic/res” of the RD.
Discovery
2456
Table 23. “oic.wk.rd” Properties 2457
Property title Property name Value type
Value rule
Unit Access mode
Mandatory Description
Selector sel Integer or JSON Object
R yes Provides the criteria for RD selection. Either JSON Object describing the selection criteria (e.g. Power) specified in 11.3.6.2.2.1 or an integer representing a bias factor calculated by RD. The value is in the range of 0 to 100 - 0 implies that RD is not to be selected. Client chooses RD with highest bias factor or randomly between RDs that have same bias factor.
2458
A RD can be queried at its “/oic/res” resource to find resources hosted on other Devices. These 2459
Devices can be sleepy nodes or any other device that cannot or may not respond to disc overy 2460
requests. Device can publish all or partial list of resources they host to a RD. The RD then responds 2461
to queries for Resource discovery on behalf of the publishing Device (for example: when a Device 2462
may go to sleep). For general Resource discovery, the RD behaves like any other Server in 2463
responding to requests to “/oic/res”. 2464
Any Device that serves or acts as a RD shall expose a well -known resource “/oic/rd”. The Devices 2465
that want to discover RDs shall use this resource and one of the Resource discovery mechanisms 2466
to discover the RD and get the parameters of the RD. The information discovered through this 2467
resource shall be used to select the appropriate RD to use for resource public ation. The bias 2468
information includes the following criteria: power source (AC, battery powered or safe/reliable), 2469
connectivity (wireless, wired), CPU, memory, load statistics (processing publishing to 100. 2470
Optionally, the RD may also return a context - the value which shall be a string and semantics of 2471
the context are not discussed in this document but it is expected that the context will be used to 2472
establish a domain, region or some such scope that is meaningful to the application, deployment 2473
or usage. 2474
Using these criteria or the bias factor, the Device should select one RD (per context) to publish its 2475
resources. A context describes the state of an OCF Device with respect to Resource discovery. A 2476
context is usually determined at deployment and from applica tion requirements. An example of a 2477
context could be a multicast group- a Device that is a member of more than one multicast group 2478
may have to find and select a RD in each of the multicast groups (i.e. per context) to publish its 2479
information. 2480
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 92
This remainder of this section is divided into three parts. The first part covers “RD Discovery” 2481
(section 11.3.6.2.2), i.e., discovering and selecting of the RD. The second part “Resource publish” 2482
(section ), i.e., publishing, updating and deleting of resources for the constrained/sleepy device. 2483
The third part “Resource exposure” (section)where RD replies to queries from devices looking to 2484
discover resources. 2485
11.3.6.2 RD discovery 2486
11.3.6.2.1 Discovering a resource directory 2487
An RD in the OCF network shall support RD discovery, shall provide the facility to allow devices 2488
to publish their resource information to a RD, to update resource information in an RD and to delete 2489
resource information from an RD. 2490
2491
Figure 27. RD discovery and RD supported query of resources support 2492
As shown in Figure 27, the Device that wishes to advertise its resources: first discovers a resource 2493
directory and then publishes the desired resource information. Once a set of resources have been 2494
published to an RD then the publishing device should not respond to multicast Resource discovery 2495
queries for those published resources when the RD is on the same multicast domain. In that case, 2496
only the RD should respond to multicast Resource discovery requests on the resource published 2497
to it. 2498
An OCF network allows for more than one device acting as an RD. The reason to have multiple 2499
RD support is to make network scalable, handle network failures and centralized device failure 2500
bottleneck. This does not preclude a scenario where a use case or deployment environment may 2501
require single device in the environment to be deployed as the only resource directory (e.g. 2502
gateway model). There may be more than one Device acting as RD on a Platform. 2503
Discovering of an RD may result in responses from more than one RD. The discovering device 2504
shall select an RD. The selection may be based on the weightage parameter(s) provided in the 2505
response from the RD. 2506
An RD will be application agnostic i.e., application should not be aware whether resource directory 2507
was queried to get the resource information. All the handling of the retrieval is kept opaque to the 2508
Query Resources
Discovery of RD and Publish
Device A Device B (acting RD)
Device C (discovering node)
Discover RD
Publish to RD
ep
Multicast Resource discovery Requests
Does not respond Unicast Response with Device A and Device B resources
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 93
application. A Client that performs Resource discovery uses an RD just like it may use any other 2509
Server for discovery. It may send a unicast request to the RD when it needs only the resource 2510
advertised on the RD or do a multicast query when it does not require or have explicit knowledge 2511
of an RD. 2512
2513
Figure 28. Resource Direction Deployment Scenarios 2514
RD can also be discovered in the following manners: 2515
Pre-configuration: Devices wishing to publish resource information may be configured a priori 2516
with the information (e.g. IP address, port, transport etc.) of a specific resource directory. This 2517
pre-configuration may be done at onboarding or may be updated on the device using an out-2518
of-band method. This pre-configuration may be done by the manufacturer or by the user/device 2519
manager. 2520
Query-oriented: A Client wanting to discover resource directories using query-oriented 2521
discovery (i.e. pull) can issue a multicast Resource discovery request for “/oic/res?rt=oic.wk.rd”. 2522
Only and all Devices that can be an RD will respond to this query. The “/oic/rd” response shall 2523
include information about the RD i.e., the presence of “oic.wk.rd” Link (as defined by the 2524
Resource Type) and subsequent query to “/oic/rd” would produce weightage parameters to 2525
allow the discovering device to select between RDs (see details in RD selection section). The 2526
“oic.wk.rd” resource shall be instantiated on the OCF Devices acting as a resource directory . 2527
The “oic.wk.rd” schema is as defined in D.14. 2528
Advertisement: An RD may advertise about itself to devices. It is an advertisement packet. The 2529
devices that are already publishing to a RD may use this as a heartbeat message of the RD. If 2530
the RD advertisement does not arrive at a stipulated interval, publishing device starts searching 2531
for other RDs in the network, as this is a signal that RD is not online. Other usage of this 2532
message is it serves as an advertisement for a device seeking a RD to publish their resources. 2533
The details from the advertisement can then be used to query directly t o a RD to get weightage 2534
details instead of sending a multicast packet in a network. As it is intended this is sent at a 2535
regular interval and does not include weightage information to keep packet sizes small. Further 2536
details may be presented in the later version of this specification. 2537
One of the important benefits of an RD is to make services discoverable in networks that don't 2538
support site wide multicast but do support site wide routing. An example of such a network is 2539
Homenet..To enable an RD function across such a network a site discovery mechanism is 2540
needed to discover the RD service (IP address & port number). In order to make itself 2541
Platform
OCF Device
/oic/res
/oic/rd
Platform
OCF Device A
/oic/res
OCF Device B
/oic/res
/oic/rd
OCF Device serving as
Resource Directory
Platform with dedicated Resource
Directory
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 94
discoverable beyond the link local scope, an RD with a routable ip address should implement 2542
the mDNS responder requirements defined in IETF RFC 6762. Further details for such an 2543
operation may be specified in a later version of this specification, when the n eeds arise. 2544
11.3.6.2.2 RD selection process 2545
11.3.6.2.2.1 Selection criteria 2546
When a device discovers more than one RD then it should decide to use one of these RDs based 2547
on the selection criteria described here. A device should use or publish information to only one RD 2548
within a multicast domain at a given time. This is to minimize the burden of processing duplicate 2549
information in the Resource discovery phase. 2550
There two ways to select an RD. One is based on a bias factor (RD generated) and the other is 2551
based on clients determination based on granular parameters provided by the server (client/device 2552
generated). Devices may use one or both methods to select an RD. 2553
Bias factor: The bias factor is a server generated positive number in the range of 0 to 100, where 2554
0 is the lowest to 100 being the highest. If two RDs have the same bias factor then the selecting 2555
device may choose either based auxiliary criteria or at random. Either way only one RD should be 2556
selected and used at a time. No specific method is defined in this specification to determine the 2557
bias factor for an RD. The number may be a pre-configured value at the time of onboarding or 2558
subsequent configuration of the RD or may be based on a formula determined by the 2559
implementation of the RD. (OCF may provide a standard formula for this calculation in a future 2560
version or release of this specification, if the needs arise). 2561
The bias factor can be calculated by the RD by adding the contribution values determined for each 2562
of the parameters in Table 24 and divided by the number of parameters. An RD may advertise a 2563
bias factor larger than the calculated value when there is reason to believe that the RD is highly 2564
capable for example an installed service provider gateway. 2565
Parameters: Optionally, parameters defined in Table 24 (like direct power supply, network 2566
connectivity, load conditions, CPU power, memory, etc.) may be returned in the “/oic/rd” discovery 2567
response. Discovering device may use the details to make granular selection decisions based on 2568
client defined policies and criteria that use the RD parameters . For example, a device in an 2569
industrial deployment may not weight power connectivity high but another in home environments 2570
may give more weightage for power. 2571
Table 24: Selection parameters 2572
Parameter Values (Contribution)
Description
Power Safe (100)
AC (70)
Batt (40)
Safe implies that the power supply is reliable and is backed up with battery for power outages etc.
Implementation may lower the number for Batt based on the type of battery the RD device runs on. If battery conservation is important then this number should be lowered.
Mobility Fixed (100)
Mobile (50)
Implementation may further grade the mobility number based on how mobile the RD device is; lower number for highly mobile and larger numbers for limited mobility
The mobility number shall not be larger than 80
Network Product
Type:
Wired (10)
Wireless (4)
Bandwidth:
High (10)
Low (5)
Network product = [sum of (type * bandwidth per network interface)]/[number of interfaces]
Normalized to 100
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 95
Lossy (3)
Interfaces
Memory Factor Available
Total
Memory is the volatile or non-volatile storage used to store the resource information
Memory Factor = [Available]/[Total]
Normalized to 100 (i.e. expressed as percentage)
Request Load Factor
1-minute
5-minute
15-minutes
Current request loading of the RD
Similar to UNIX load factor (using observable, pending and processing requests instead of runnable processes)
Expressed as a load factor 3-tuple (up to two decimal points each). Factor is based on request processed in a 1-minute (L1), 5-minute (L5) and 15-minute (L15) windows
See http://www.teamquest.com/import/pdfs/whitepaper/ldavg1.pdf
Factor = 100 – ([L1*3 + L5*7 + L15*10]/3)
2573
11.3.6.2.2.2 Selection scenarios 2574
The device that wants to use an RD will find zero or more RDs on the network. After discovering 2575
the RDs, the device needs to select an RD of all found RDs on the network. The selection based 2576
on the bias factor will ensure that a Device can judge if the found RD is suitable for its needs. 2577
The following situation can occur during the selection of an RD: 2578
1) A single or multiple RDs are present in the network 2579
2) No RD is present in the network 2580
3) an additional RD arrives on the network 2581
In the first scenario the RDs are already present. If a single RD is detected then that RD can be 2582
used . When multiple RDs are detected the Device uses the bias information to select the RD. 2583
In the second scenario, device will listen to the advertisement of the devices that hosts the RDs. 2584
Once an RD advertisement packet is received it judges if the bias criteria are met and starts using 2585
the RDs. 2586
In the third scenario the Device has already published its resources to an existing RD. In this 2587
scenario it discovers a new RD on the network. 2588
After judging the bias factor the Device may choose to move to the new RD. If the decision is made 2589
to select the new RD, the then Device should delete its resource information from the current used 2590
RD and then after removal publish the information to the new RD. During the transition period the 2591
Device itself should respond to Resource discovery requests. 2592
11.3.6.3 Resource publish 2593
11.3.6.3.1 Publish resources 2594
11.3.6.3.1.1 Overview 2595
After the selection process of an RD, a device may choose one of the following mechanisms: 2596
Push its resources information to the selected RD or 2597
Request the RD to pull the resource information by doing a unicast discovery request against 2598
its “/oic/res” 2599
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 96
The publishing device may decide to publish all resources or few resources on the resource 2600
directory. The publishing device shall only publish resources that are otherwise published to its 2601
own “/oic/res”. A publishing device may respond to discovery requests (on its “/oic/res” resource) 2602
for the resources it does not publish to a RD. Nonetheless, it is highly recommended that when an 2603
RD is used, all discoverable resources on the publisher be published to the RD. 2604
11.3.6.3.1.2 Publish: Push resource information 2605
Resource information is published using an UPDATE operation to “/oic/rd” with “rt” query of 2606
“?rt=oic.wk.rdpub” and the “oic.if.baseline” interface. 2607
A Device, which hosts a Resource, can publish the Resource information, i.e. the Link targeting 2608
the Resource, to an RD by sending a POST request with the Link in the payload. The published 2609
Link will be exposed through the “/oic/res” of the RD. 2610
When a Device first publishes a Link or Links, it sends a POST request to “/oic/rd” Resource 2611
including the following key-value pairs in the payload 2612
di – as its value, a unique identifier for the publishing Device, i.e. its device ID . 2613
links – as its value, the array of Links to be published. Links may not include “ins” Parameter. 2614
ttl – as its value, the time to indicate the RD how long to keep this published item. After this 2615
time (in seconds) elapses, the RD invalidates the links. To keep link alive the publishing device 2616
updates the ttl using the update schema. 2617
Take notice that the payload shall carries the appropriate Con tent-Format of 2618
“application/vnd.ocf+cbor”. 2619
{
"di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"links": [
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/myLightSwitch",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [
{"ep": "coaps://[fe80::b1d6]:1111", "pri": 2},
{"ep": "coaps://[fe80::b1d6]:1122"},
{"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3}
]
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/myLightBrightness",
"rt": ["oic.r.brightness"],
"if": ["oic.if.a", "oic.if.baseline"],
"p": {"bm": 3},
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 97
"eps": [
{"ep": "coaps://[[2001:db8:a::123]:2222"}
]
}
],
"ttl": 600
}
Figure 29. Example of POST request payload 2620
When an RD receives the POST request, it determines whether to grant the request or not. Upon 2621
granting the request, for each Link to be published, the RD assigns a unique instance value 2622
identifying the Link among all the Links it advertises and includes the identifying value in “ins” 2623
Parameter of the Link. The RD may use the "ins" value which the publishing Device includes in the 2624
POST request payload as long as the "ins" value doesn't match with any existing "ins" value in the 2625
published Link. The RD adds the new Links to its “/oic/res” and exposes them to a valid discovery 2626
query, i.e. GET request. 2627
The RD sends back the POST response to the Publishing Device with the same payload as in the 2628
matching POST request with possible differences of 1) “ins” inclusion in each Link and 2) different 2629
“ttl” value. Take notice that each published Link in RD response payload shall carry “ins” Parameter 2630
to provide the publishing Device of the identifier with which it can further UPDATE or DELETE the 2631
Link. 2632
2633
{
"di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"links": [
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/myLightSwitch",
"rt": ["oic.r.switch.binary"],
"if": ["oic.if.a", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [
{"ep": "coaps://[fe80::b1d6]:1111", "pri": 2},
{"ep": "coaps://[fe80::b1d6]:1122"},
{"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3}
],
"ins": "11235"
},
{
"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href": "/myLightBrightness",
"rt": ["oic.r.brightness"],
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 98
"if": ["oic.if.a", "oic.if.baseline"],
"p": {"bm": 3},
"eps": [
{"ep": "coaps://[[2001:db8:a::123]:2222"}
],
"ins": "112358"
}
],
"ttl": 600
}
Figure 30. Example of POST response payload 2634
2635
Once a publishing device has published resources to an RD, it may not respond to the multicast 2636
discovery queries for the same resources against its own “/oic/res”, especially when on the same 2637
multicast domain as the RD. After publishing resources, primarily it is an RD responsibility to reply 2638
to the queries for the published resources. 2639
If the publishing device is in sleep mode and an RD has replied on behalf of the publishing device, 2640
then a discovering device will try to access resource on the provided URI. 2641
There is another possibility that the resource directory and the publishing device both respond to 2642
the multicast query from the discovering device. This will create a duplication of the information 2643
but is an alternate that may be used for non-robust network. It is not a recommended option but 2644
for industrial scenarios, this is one of the possibilities. Either way, discovering clients shall always 2645
be prepared to process duplicate information in responses to multicast discovery request . The 2646
“/oic/rd” schema is as defined in D.14 to specify publishing to the “/oic/rd” Resrouce. 2647
11.3.6.3.2 Update resource information 2648
An RD will hold the published Link till the time specified in the ttl field. A publishing Device can 2649
send update if it seeks the RD to keep holding the Link or modify the published Link (e.g. changing 2650
Endpoint information). UPDATE can be used for updating about all resources that are published 2651
on an RD or per resource published. 2652
UPDATEs in CoAP are done using the same POST request to “oic/rd”. POST request message will 2653
be of the same payload format but the each Link to be modified shall include the “ins” Parameter 2654
which the RD previously provided in POST response message. 2655
Upon granting the request, the RD reflects the change to the Link in its “/oic/res” and sends back 2656
the POST response of the same format as the initial publishing. 2657
11.3.6.3.3 Delete resource information 2658
A resource information hold at the resource directory can be removed anytime by the publishing 2659
device. It can be either for the whole device information or for a particular resource. This request 2660
should be only allowed when device meets a certain requirement, as it can create potential security 2661
issue. 2662
A publishing Device can delete published Link or Links from an RD by sending a DELETE request 2663
with the query “di” or “ins” indicating the Links to be deleted. 2664
di – This is used to determine which set of links to delete. (Need authentication to ensure that 2665
there is no spoofing). It's the form of di=value, where value is a device ID indicating the Device 2666
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 99
to operate on. When present, the entire set of links corresponding to the device ID is deleted, 2667
i.e. the Links published by the publishing Device with the same device ID are deleted. 2668
ins – Instance of the Link to delete. Value of parameter is a string indicating the instance to be 2669
deleted. When present, the Link with the same instance value is deleted. 2670
DELETE /oic/rd?di=0685B960-736F-46F7-BEC0-9E6CBD671ADC1
DELETE /oic/rd?ins=20
Figure 31. Example of DELETE request with "di" or "ins" query 2671
When a publishing Device wants to remove published Link or Links from an RD, it sends DELETE 2672
request with “di” or “ins” indicating the Links to be removed. Upon granting the request, the RD 2673
removes the identified Links and sends back the DELETE response. 2674
Selective deletion of information for individual resources is not possible the case where the RD 2675
pull the resource information due to the absence of :ins” value . The publishing device can request 2676
a delete but only for all the resource information that the RD has pulled from that device. In this 2677
case, the DELETE request has the device ID ”di” in the query. 2678
11.3.6.3.4 Transfer resource information from one RD to another 2679
When a publishing device identifies an RD that is better suited, it may decide to publish to that RD. 2680
Since the device should publish to only one RD at a time, the client should ensure that previously 2681
published information is deleted from the currently used RD before publishing to the newly selected 2682
RD. The deletion of the resource may be done either by al lowing the TTL to expire or explicitly 2683
deleting the resource information. 2684
RDs shall not transfer Resource information between themselves. It is the Client’s responsibility 2685
to choose the RD and to manage the published Resources. 2686
11.3.6.4 Resource exposure 2687
11.3.6.4.1 “/oic/res” and retrieving of the resources 2688
The “/oic/res” based discovery process remains the same as that in the absence of an RD. 2689
Resources may be discovered by retrieving the “/oic/res” resource by sending a multicast or 2690
unicast request. In the case of a multicast discovery request, an RD will respond for the device 2691
that hosts the resources. Clients shall be prepared to process duplicate resource i nformation from 2692
more than one RD responding with the same information or from an RD and the hosting device 2693
(publishing the resource information) both responding to the request. Interaction with resources 2694
discovered using the RD is done using the same mechanism and methods as with resources 2695
discovered by retrieving the “/oic/res” resource of the device hosting the resources (e.g., connect 2696
to the resource and perform CRUDN operations on the resource). 2697
Resource Directory provides different “/oic/res” response according to requesting Clients, which 2698
indicate their preference with content format. OCF 1.0 Clients request with the “Content Format of 2699
“application/vnd.ocf+cbor”, whereas the absence of the Content-Format indicates OIC 1.1 Clients. 2700
For OIC 1.1 Clients, “/oic/res” response includes to OIC 1.1 Link and anchor parameter has transfer 2701
protocol URI (e.g. coap URI), if present. The Resources hosted by the same Device are grouped 2702
together within a single JSON Object with "di" indicating the hosting Device. The Resources 2703
belonging to the responding RD may omit "anchor" parameter. However , the Resources of other 2704
Devices shall include "anchor" parameter when "rel" value is "hosts" and its “href” value should be 2705
(fully qualified) transfer protocol URI with IP address and port number as its authority component 2706
(e.g., coaps://[2001:db8:b::c2e5]:22222/myLightSwitch) . 2707
For example, a Resource Directory might return the following to OIC 1.1 clients: 2708
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 100
[ 2709
{ 2710
"di": "88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2711
"links": [ 2712
{ 2713
"href": "/oic/res", 2714
"rel": "self", 2715
"rt": ["oic.wk.res"], 2716
"if": ["oic.if.ll", "oic.if.baseline"], 2717
"p": {"bm": 3, "sec": false, "port": 33333} 2718
}, 2719
{ 2720
"href": "/oic/d", 2721
"rt": ["oic.wk.d", "oic.d.fan"], 2722
"if": ["oic.if.r", "oic.if.baseline"], 2723
"p": {"bm": 3, "sec": false, "port": 33333} 2724
}, 2725
{ 2726
"href": "/oic/p", 2727
"rt": ["oic.wk.p"], 2728
"if": ["oic.if.r", "oic.if.baseline"], 2729
"p": {"bm": 3, "sec": true, "port": 33333} 2730
}, 2731
{ 2732
"href": "/myFanIntrospection", 2733
"rt": ["oic.wk.introspection"], 2734
"if": ["oic.if.r", "oic.if.baseline"], 2735
"p": {"bm": 3, "sec": true, "port": 33333} 2736
}, 2737
{ 2738
"href": "/oic/rd", 2739
"rt": ["oic.wk.rd"], 2740
"if": ["oic.if.baseline"], 2741
"p": {"bm": 3, "sec": true, "port": 33333} 2742
}, 2743
{ 2744
"href": "/myFanSwitch", 2745
"rt": ["oic.r.switch.binary"], 2746
"if": ["oic.if.a", "oic.if.baseline"], 2747
"p": {"bm": 3, "sec": true, "port": 33333} 2748
}, 2749
{ 2750
"href": "/oic/sec/doxm", 2751
"rt": ["oic.r.doxm"], 2752
"if": ["oic.if.baseline"], 2753
"p": {"bm": 1, "sec": false, "port": 33333} 2754
}, 2755
{ 2756
"href": "/oic/sec/pstat", 2757
"rt": ["oic.r.pstat"], 2758
"if": ["oic.if.baseline"], 2759
"p": {"bm": 1, "sec": true, "port": 33333} 2760
}, 2761
{ 2762
"href": "/oic/sec/cred", 2763
"rt": ["oic.r.cred"], 2764
"if": ["oic.if.baseline"], 2765
"p": {"bm": 1, "sec": true, "port": 33333} 2766
}, 2767
{ 2768
"href": "/oic/sec/acl2", 2769
"rt": ["oic.r.acl2"], 2770
"if": ["oic.if.baseline"], 2771
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 101
"p": {"bm": 1, "sec": true, "port": 33333} 2772
} 2773
] 2774
}, 2775
{ 2776
"di": "dc70373c-1e8d-4fb3-962e-017eaa863989", 2777
"links": [ 2778
{ 2779
"anchor": "coap://[2001:db8:b::c2e5]:66666", 2780
"href": "coap://[2001:db8:b::c2e5]:66666/oic/d", 2781
"rt": ["oic.wk.d", "oic.d.light", "oic.d.virtual"], 2782
"if": ["oic.if.r", "oic.if.baseline"], 2783
"p": {"bm": 3, "sec": false, "port": 22222} 2784
}, 2785
{ 2786
"anchor": "coaps://[2001:db8:b::c2e5]:22222", 2787
"href": "coaps://[2001:db8:b::c2e5]:22222/oic/p", 2788
"rt": ["oic.wk.p"], 2789
"if": ["oic.if.r", "oic.if.baseline"], 2790
"p": {"bm": 3, "sec": true, "port": 22222} 2791
}, 2792
{ 2793
"anchor": "coaps://[2001:db8:b::c2e5]:22222", 2794
"href": "coaps://[2001:db8:b::c2e5]:22222/myLightSwitch", 2795
"rt": ["oic.r.switch.binary"], 2796
"if": ["oic.if.a", "oic.if.baseline"], 2797
"p": {"bm": 3, "sec": true, "port": 22222} 2798
}, 2799
{ 2800
"anchor": "coaps://[2001:db8:b::c2e5]:22222", 2801
"href": "coaps://[2001:db8:b::c2e5]:22222/myLightBrightness", 2802
"rt": ["oic.r.brightness"], 2803
"if": ["oic.if.a", "oic.if.baseline"], 2804
"p": {"bm": 3, "sec": true, "port": 22222} 2805
} 2806
] 2807
} 2808
] 2809
2810
For OCF 1.0 Clients, “/oic/res” response includes adds to the OCF 1.0 Link and the anchor 2811
parameter has OCF URI. “/oic/res” response has the single array of OCF 1.0 Links to conform to 2812
IETF RFC 6690. Each Link shall carry "anchor" of the value OCF URI where the authority 2813
component of <deviceID> indicates the Device hosting the target Resource. 2814
The Resource Directory might return the following to clients that request with the Content Format 2815
of “application/vnd.ocf+cbor”: 2816
[ 2817
{ 2818
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2819
"href": "/oic/res", 2820
"rel": "self", 2821
"rt": ["oic.wk.res"], 2822
"if": ["oic.if.ll", "oic.if.baseline"], 2823
"p": {"bm": 3}, 2824
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2825
{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2826
}, 2827
{ 2828
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2829
"href": "/oic/d", 2830
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 102
"rt": ["oic.wk.d", "oic.d.fan"], 2831
"if": ["oic.if.r", "oic.if.baseline"], 2832
"p": {"bm": 3}, 2833
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2834
{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2835
}, 2836
{ 2837
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2838
"href": "/oic/p", 2839
"rt": ["oic.wk.p"], 2840
"if": ["oic.if.r", "oic.if.baseline"], 2841
"p": {"bm": 3}, 2842
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2843
}, 2844
{ 2845
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2846
"href": "/myFanIntrospection", 2847
"rt": ["oic.wk.introspection"], 2848
"if": ["oic.if.r", "oic.if.baseline"], 2849
"p": {"bm": 3}, 2850
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2851
}, 2852
{ 2853
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2854
"href": "/oic/rd", 2855
"rt": ["oic.wk.rd"], 2856
"if": ["oic.if.baseline"], 2857
"p": {"bm": 3}, 2858
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2859
}, 2860
{ 2861
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2862
"href": "/myFanSwitch", 2863
"rt": ["oic.r.switch.binary"], 2864
"if": ["oic.if.a", "oic.if.baseline"], 2865
"p": {"bm": 3}, 2866
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2867
}, 2868
{ 2869
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2870
"href": "/oic/sec/doxm", 2871
"rt": ["oic.r.doxm"], 2872
"if": ["oic.if.baseline"], 2873
"p": {"bm": 1}, 2874
"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2875
{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2876
}, 2877
{ 2878
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2879
"href": "/oic/sec/pstat", 2880
"rt": ["oic.r.pstat"], 2881
"if": ["oic.if.baseline"], 2882
"p": {"bm": 1}, 2883
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2884
}, 2885
{ 2886
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2887
"href": "/oic/sec/cred", 2888
"rt": ["oic.r.cred"], 2889
"if": ["oic.if.baseline"], 2890
"p": {"bm": 1}, 2891
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2892
}, 2893
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 103
{ 2894
"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2895
"href": "/oic/sec/acl2", 2896
"rt": ["oic.r.acl2"], 2897
"if": ["oic.if.baseline"], 2898
"p": {"bm": 1}, 2899
"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2900
}, 2901
2902
{ 2903
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2904
"href": "/oic/d", 2905
"rt": ["oic.wk.d", "oic.d.light"], 2906
"if": ["oic.if.r", "oic.if.baseline"], 2907
"p": {"bm": 3}, 2908
"eps": [{"ep": "coap://[2001:db8:b::c2e5]:66666"}, 2909
{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2910
}, 2911
{ 2912
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2913
"href": "/oic/p", 2914
"rt": ["oic.wk.p"], 2915
"if": ["oic.if.r", "oic.if.baseline"], 2916
"p": {"bm": 3}, 2917
"eps": [{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2918
}, 2919
{ 2920
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2921
"href": "/myLightSwitch", 2922
"rt": ["oic.r.switch.binary"], 2923
"if": ["oic.if.a", "oic.if.baseline"], 2924
"p": {"bm": 3}, 2925
"eps": [{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2926
}, 2927
{ 2928
"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2929
"href": "/myLightBrightness", 2930
"rt": ["oic.r.brightness"], 2931
"if": ["oic.if.a", "oic.if.baseline"], 2932
"p": {"bm": 3}, 2933
"eps": [{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2934
} 2935
] 2936
2937
11.4 Notification 2938
Overview 2939
A Server shall support NOTIFY operation to enable a Client to request and be notified of desired 2940
states of one or more Resources in an asynchronous manner. Section 11.4.2 specifies the observe 2941
mechanism in which updates are delivered to the requester. 2942
Observe 2943
In observe mechanism the Client utilizes the RETRIEVE operation to require the Server for updates 2944
in case of Resource state changes. The Observe mechanism consists of five steps which are 2945
depicted in Figure 32 and described below. 2946
Note: the observe mechanism can only be used for a resource with a property of observable 2947
(section 7.3.2.2). 2948
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 104
OIC Client OIC Server
1. RETRIEVE Request (Observe)
3. RETRIEVE Response (Observe)
5. RETRIEVE Response (Observe)
2. Observe request cached
4. Observe condition satisfied
2949
Figure 32. Observe Mechanism 2950
11.4.2.1 RETRIEVE request with observe indication 2951
The Client transmits a RETRIEVE request message to the Server to request updates for the 2952
Resource on the Server if there is a state change. The RETRIEVE request message carries the 2953
following parameters: 2954
fr: Unique identifier of the Client 2955
to: Resource that the Client is requesting to observe 2956
ri: Identifier of the RETRIEVE request 2957
op: RETRIEVE 2958
obs: Indication for observe request 2959
11.4.2.2 Processing by the Server 2960
Following the receipt of the RETRIEVE request, the Server may validate if the Client has the 2961
appropriate rights for the requested operation and the properties are readable and observable. If 2962
the validation is successful, the Server caches the information related to the observe request. The 2963
Server caches the value of the ri parameter from the RETRIEVE request for use in the initial 2964
response and future responses in case of a change of state. 2965
11.4.2.3 RETRIEVE response with observe indication 2966
The Server shall transmit a RETRIEVE response message in response to a RETRIEVE request 2967
message from a Client. The RETRIEVE response message shall include the following parameters. 2968
If validation succeeded, the response includes an observe indication. If not, the observe indication 2969
is omitted from the response which signals to the requesting client that registration for notification 2970
was not allowed. 2971
The RETRIEVE response message shall include the following parameters: 2972
fr: Unique identifier of the Server 2973
to: Unique identifier of the Client 2974
ri: Identifier included in the RETRIEVE request 2975
cn: Information resource representation as requested by the Client 2976
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 105
rs: The result of the RETRIEVE operation 2977
obs: Indication that the response is made to an observe request 2978
11.4.2.4 Resource monitoring by the Server 2979
The Server shall monitor the state the Resource identified in the observe request from the Client. 2980
Anytime there is a change in the state of the observed resource, the Server sends another 2981
RETRIEVE response with the observe indication. The mechanism does not allow the client to 2982
specify any bounds or limits which trigger a notification, the decision is left entirely to the server. 2983
11.4.2.5 Additional RETRIEVE responses with observe indication 2984
The Server shall transmit updated RETRIEVE response messages following observed changes in 2985
the state of the Resources indicated by the Client. The RETRIEVE response message shall include 2986
the parameters listed in section 11.4.2.3. 2987
11.4.2.6 Cancelling Observe 2988
The Client can explicitly cancel observe by sending a RETRIEVE request without the observe 2989
indication field to the same resource on Server which it was observing. For certain protocol 2990
mappings, the client may also be also be able to cancel an observe by ceasing to respond to the 2991
RETRIEVE responses. 2992
11.5 Device management 2993
Overview 2994
The Device Management includes the following functions: 2995
Diagnostics and maintenance 2996
The device management functionalities specified in this version of specification are in tended to 2997
address the basic device management features. Addition of new device management features in 2998
the future versions of the specification is expected. 2999
Diagnostics and maintenance 3000
The Diagnostics and Maintenance function is intended for use by administrators to resolve issues 3001
encountered with the Devices while operating in the field. If diagnostics and maintenance is 3002
supported by a Device, the Core Resource “/oic/mnt” shall be supported as described in Table 25. 3003
Table 25. Optional diagnostics and maintenance device management Core Resources 3004
Pre-defined URI
Resource Type Title
Resource Type ID (“rt” value)
Interfaces Description Related Functional Interaction
“/oic/mnt”
Maintenance “oic.wk.mnt”
“oic.if.rw” The resource through which the device is maintained and can be used for diagnostic purposes.
The resource properties exposed by “/oic/mnt” are listed in Table 26.
Device Management
3005
Table 26 defines the “oic.wk.mnt” Resource Type. At least one of the Factory_Reset, and Reboot 3006
properties shall be implemented. 3007
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 106
Table 26. “oic.wk.mnt” Resource Type definition 3008
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Factory_Reset fr boolean R, W no When writing to this Property:
0 – No action (Default*)
1 – Start Factory Reset
After factory reset, this value shall be changed back to the default value (i.e., 0).
After factory reset all configuration and state data will be lost.
When reading this Property, a value of “1” indicates a pending factory reset, otherwise the value shall be “0” after the factory reset.
Reboot rb boolean R, W no When writing to this Property:
0 – No action (Default)
1 – Start Reboot
After Reboot, this value shall be changed back to the default value (i.e., 0)
3009
Note: * - Default indicates the value of this property as soon as the device is rebooted or factory reset 3010
3011
11.6 Scenes 3012
Introduction 3013
Scenes are a mechanism for automating certain operations. 3014
A scene is a static entity that stores a set of defined resource property values for a collection of 3015
resources. Scenes provide a mechanism to store a setting over multiple Resources that may be 3016
hosted by multiple separate Servers. Scenes, once set up, can be used by multiple Clients to recall 3017
a setup. 3018
Scenes can be grouped and reused, a group of scenes is also a scene. 3019
In short, scenes are bundled user settings. 3020
Scenes 3021
11.6.2.1 Introduction 3022
Scenes are described by means of resources. The scene resources are hosted by a Server and 3023
the top level resource is listed in “/oic/res”. This means that a Client can determine if the scene 3024
functionality is hosted on a Server via a RETRIEVE on “/oic/res” or via Resource discovery. The 3025
setup of scenes is driven by Client interactions. This includes creating new scenes, and mappings 3026
of Server resource properties that are part of a scene. 3027
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 107
The scene functionality is created by multiple resources and has the structure depicted in Figure 3028
33. The sceneList and sceneCollection resources are overloaded collection resources. The 3029
sceneCollection contains a list of scenes. This list contains zero or more scenes. The 3030
sceneMember resource contains the mapping between a scene and what needs to happen 3031
according to that scene on an indicated resource. 3032
3033
Figure 33 Generic scene resource structure 3034
11.6.2.2 Scene creation 3035
A Client desiring to interact with scenes needs to first determine if the server supports the scene 3036
feature; the sceneMembers of a scene do not have to be co-located on the server supporting the 3037
scene feature. This can be done by checking if “/oic/res” contains the rt of the sceneList resource. 3038
This is depicted in first steps of Figure 34. The sceneCollection is created by the Server using 3039
some out of bound mechanism, Client creation of scenes is not supported at this time. This will 3040
entail defining the scene with an applicable list of scene values and the mappings for each 3041
Resource being part of the scene. The mapping for each resource being part of the sceneCollection 3042
is described by a resource called sceneMember. The sceneMember resource contains the link to 3043
a resource and the mapping between the scene listed in the sceneValues property and the actual 3044
resource property value of the Resource indicated by the link. 3045
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 108
3046
Figure 34 Interactions to check Scene support and setup of specific scenes 3047
11.6.2.3 Interacting with Scenes 3048
All capable Clients can interact with scenes. The allowed scene values and the last applied scene 3049
value can be retrieved from the server hosting the scene. The scene value shall be changed by 3050
issuing an UPDATE operation with a payload that sets the lastScene property to one of the listed 3051
allowed scene values. These steps are depicted in Figure 35. Note that the lastScene value does 3052
not imply that the current state of all resources that are part of the scene will be at the mapped 3053
value. This is due to that the setting the scene values are not modelled as actual states of the 3054
system. This means that another Client can change just one resource being part of the scene 3055
without having feedback that the state of the scene is changed. 3056
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 109
3057
Figure 35 Client interactions on a specific scene 3058
As described previously, a scene can reference one or more resources that are present on one or 3059
more Servers. The scene members are re-evaluated each time a scene change takes place. This 3060
evaluation is triggered by a Client that is either embedded as part of the Server hosting the scene, 3061
or separate to the server having knowledge of the scene via a RETRIEVE operation, observing the 3062
referenced resources using the mechanism described in section 11.4.2. During the evaluation the 3063
mappings for the new scene value will be applied to the Server. This behaviour is depicted in 3064
Figure 36. 3065
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 110
3066
Figure 36 Interaction overview due to a Scene change 3067
11.6.2.4 Summary of Resource Types defined for Scene functionality 3068
Table 27 summarizes the list of Resource Types that are part of Scenes. 3069
Table 27 list of Resource Types for Scenes 3070
Friendly Name (informative) Resource Type (rt) Short Description Section
sceneList oic.wk.scenelist Top Level collection containing sceneCollections
sceneCollection oic.wk.scenecollection Description of zero or more scenes
sceneMember oic.wk.scenemember Description of mappings for each specific resource part of the sceneCollection
Security considerations 3071
Creation of Scenes on a Server that is capable of this functionality is dependent on the ACLs 3072
applied to the resources and the Client having the appropriate permissions. Interaction between 3073
a Client (embedded or separate) and a Server that hosts the resource that is referenced as a scene 3074
member is contingent on the Client having appropriate permissions to access the resource on the 3075
host Server. 3076
See OCF Security for details on the use of ACLs and also the mechanisms around Device 3077
Authentication that are necessary to ensure that the correct permissions exist for the Client to 3078
access the scene member resource(s) on the Server. 3079
11.7 Icons 3080
Overview 3081
Icons are a primitive that are needed by various OCF subsystems, such as bridging. An optional 3082
Resource Type of “oic.r.icon” has been defined to provide a common representation of an icon 3083
Resource that can be used by Devices. 3084
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 111
Resource 3085
The icon Resource is as defined in Table 28. 3086
Table 28. Optional Icon Core Resource 3087
URI Resource Type Title
Resource Type ID (“rt” value)
Interfaces Description Related Functional Interaction
“/example/oic/icon”
Icon “oic.r.icon” “oic.if.r” The Resource through which the Device can obtain icon images.
The Resource properties exposed by “/example/oic/mnt” are listed in Table 29.
Icon
3088
Table 29 defines the details for the “oic.r.icon” Resource Type. 3089
Table 29. “oic.r.icon” Resource Type definition 3090
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Mime Type mimetype string R yes Specifies the format (media type) of the icon. It should be a template string as specified in IANA Media Types Assignment
Width width integer >= 1 R yes Width of the icon in pixels greater than or equal to 1.
Height height integer >= 1 R yes Height of the icon in pixels greater than or equal to 1.
Icon media uri R yes URI to the location of the icon image.
3091
11.8 Introspection 3092
Overview 3093
Introspection is a mechanism to announce the capabilities of Resources hosted on the Device. 3094
The intended usage of the Introspection Device Data is to enable dynamic clients. E.g. clients that 3095
can use the Introspection Device Data to generate dynamically an UI or dynamically create 3096
translations of the hosted Resources to another eco-system. Other usages of the Introspection is 3097
that the information can be used to generate client code. The Introspection Device Data is designed 3098
to augment the existing data already on the wire. This means that existing mechanism needs to 3099
be used to get a full overview of what is implemented in the Device. For example the Introspection 3100
Device Data does not convey information about observe, since that is already conveyed with the 3101
“p” property on the links in “/oic/res” (see section 7.8.2.1.2). 3102
The Introspection Device Data is recommended to be conveyed as "static" data. Meaning that the 3103
data does not change during the uptime of a Device. However when the data is not static the 3104
Introspection Resource shall indicate to be observable and the url property value of 3105
“oic.wk.introspection” Resource shall change to indicate that the Introspection Device Data is 3106
changed. 3107
The Introspection Device Data describes the Resources that make up the Device. For the complete 3108
list of included Resources Table 13. The Introspection Device Data is described as a swagger2.0 3109
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 112
in JSON format file. The swagger2.0 file wi ll contain the description of the Resources as defined 3110
below: All Resources with the next remarks: 3111
The URLs of the Resources in the Introspection Device Data shall be without the endpoint 3112
description, e.g. it shall not be a full URL but only the relative path from the endpoint. The 3113
relative path shall be the same as being conveyed by “/oic/res”. 3114
“/oic/res” Resource shall not be listed in the Introspection Device Data. 3115
The Resources “/oic/d”, “/oic/p” and the security Resources are allowed to be present in the 3116
Introspection Device Data, but are not required. The “/oic/d”, “/oic/p”, “/oic/res” and the security 3117
Resources shall be included when vendor defined or optional properties are implemented. 3118
All other Resources are required to be listed in the Introspection Device Data. 3119
Per Resource it will include: 3120
o All Implemented Methods 3121
o Per Supported Method: 3122
Implemented queryParameters per Method. 3123
This includes the supported interfaces ("if") as enum value. 3124
Schemas of the payload for the request and response bodies of the Method 3125
The schema data shall be conveyed by the swagger schema object as 3126
defined in the parameters section. 3127
The swagger2.0 schema object shall comply with: 3128
The schemas shall be fully resolved, e.g. no references shall exist 3129
outside the swagger file. 3130
The schemas shall list which interfaces are supported on the method. 3131
The schemas shall list if a property is optional or required. 3132
The schemas shall indicate if an property is read only or read-write 3133
o By means of the readOnly schema tag belonging to the 3134
property 3135
The default value of the “rt” property shall be used to indicate the 3136
supported Resource Types. 3137
oneOf and anyOf constructs are allowed to be used as part of an 3138
swagger2.0 schema object. 3139
Dynamic Resources (e.g. Resources that can be created up on a request by a Client) shall have 3140
an URL definition which contains a URL identifier (e.g. using the {} syntax). An URL with {} identifies 3141
that the Resource definition applies to the whole group of Resources that can be created. The 3142
actual path can contain the collection node that links to the Resource. 3143
Example of an URL with identifiers: 3144
/SceneListResURI/{SceneCollectionResURI}/{SceneMemberResURI}: 3145
When different Resource Types are allowed to be created in a collection, then the different 3146
schemas for the create method shall define all possible Resource Types that can be created. The 3147
schema construct oneOf allows the definition of a schema with selectable Resources. The oneOf 3148
construct allows the integration of all schemas and that only one existing sub schemas shall be 3149
used to indicate the definition of the Resource that can be created. 3150
Example usage of oneOf JSON schema construct: 3151
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 113
{ 3152
"oneOf": [ 3153
{ <<subschema 1 definition>> }, 3154
{ << sub schema 2 definition >> } 3155
… 3156
] 3157
} 3158
3159
A Client using the Introspection Device Data of a Device should check the version of the supported 3160
Introspection Device Data of the Device. The swagger version is indicated in each file with the tag 3161
"swagger". Example of the 2.0 supported version of the tag is: "swagger": "2.0". Later versions of 3162
the spec may reference newer versions of the swagger specification, for example 3.0. 3163
A Server shall support one Resource with a Resource Type of “oic.wk.introspection” as defined in 3164
Table 30. The Resource with a Resource Type of “oic.wk.introspection” shall be included in the 3165
Resource “/oic/res”. 3166
Table 30. Introspection Resource 3167
Pre-defined
URI
Resource Type Title
Resource Type ID
(“rt” value)
Interfaces Description Related Functional Interaction
none Introspection
oic.wk.introspection
“oic.if.r” The Resource that announces the URL of the Introspection file.
Introspection
3168
Table 31defines “oic.wk.introspection” Resource Type. 3169
Table 31. “oic.wk.introspection” Resource Type definition 3170
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
urlInfo urlInfo array R yes array of objects
url url string uri R yes URL to the hosted payload
protocol protocol string enum R yes Protocol definition to retrieve the Introspection Device Data from the url.
content-type content-type
string enum R no content type of the url.
version version integer enum R no Version of the Introspection protocol, indicates which rules are applied on the Introspection Device Data regarding the content of the RAML file.
Current value is 1.
Usage of introspection 3171
The Introspection Device Data is retrieved in the following steps: 3172
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 114
1) Check if the Introspection Resource is supported and retrieve the URL of the Resource. 3173
2) Retrieve the contents of the Introspection Resource 3174
3) Download the Introspection Device Data from the URL specified the Introspection Resource. 3175
4) Usage of the Introspection Device Data by the Client 3176
3177
Figure 37 Interactions to check Introspection support and download the Introspection 3178
Device Data. 3179
12 Messaging 3180
12.1 Introduction 3181
This section specifies the protocol messaging mapping to the CRUDN messaging operations 3182
(Section 8) for each messaging protocol specified (e.g. , CoAP.). Mapping to additional protocols 3183
is expected in later version of this specification. All the property information from the resource 3184
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 115
model shall be carried within the message payload. This payload shall be generated in the resource 3185
model layer and shall be encapsulated in the data connectivity layer. The message header shall 3186
only be used to describe the message payload (e.g. , verb, mime-type, message payload format), 3187
in addition to the mandatory header fields defined in messaging protocol (e.g ., CoAP) specification. 3188
If the message header does not support this, then this informat ion shall also be carried in the 3189
message payload. Resource model information shall not be included in the message header 3190
structure unless the message header field is mandatory in the messaging protocol specification. 3191
12.2 Mapping of CRUDN to CoAP 3192
Overview 3193
A Device implementing CoAP shall conform to IETF RFC 7252 for the methods specified in section 3194
12.2.3. A Device implementing CoAP shall conform to IETF RFC 7641 to implement the CoAP 3195
Observe option. Support for CoAP block transfer when the payload is larger than the MTU is 3196
defined in section 12.2.8. 3197
URIs 3198
An OCF: URI is mapped to a coap: URI by replacing the scheme name ‘oic’ with ‘coap’ if unsecure 3199
or ‘coaps’ if secure before sending over the network by the requestor. Similarly on the receiver 3200
side, the scheme name is replaced with ‘oic’. 3201
CoAP method with request and response 3202
12.2.3.1 Overview 3203
Every request has a CoAP method that realizes the request. The primary methods and their 3204
meanings are shown in Table 32, which provides the mapping of GET/PUT/POST/DELETE 3205
methods to CREATE, RETRIEVE, UPDATE, and DELETE operations. The associated text provides 3206
the generic behaviours when using these methods, however resource interfaces may modify these 3207
generic semantics. 3208
3209
Table 32. CoAP request and response 3210
Method for CRUDN
(mandatory) Request data (mandatory) Response data
GET for RETRIEVE
- Method code: GET (0.01)
- Request URI: an existing URI for the Resource to be retrieved
- Response code: success (2.xx) or error (4.xx or 5.xx)
- Payload: Resource representation of the target Resource (when successful)
POST for CREATE
- Method code: POST (0.02)
- Request URI: an existing URI for the Resource responsible for the creation
- Payload: Resource presentation of the Resource to be created
- Response code: success (2.xx) or error (4.xx or 5.xx)
- Payload: the URI of the newly created Resource (when successful).
PUT for CREATE
- Method code: PUT (0.03)
- Request URI: a new URI for the Resource to be created.
- Payload: Resource presentation of the Resource to be created.
- Response code: success (2.xx) or error (4.xx or 5.xx)
POST for UPDATE
- Method code: POST (0.02)
- Request URI: an existing URI for the Resource to be updated.
- Payload: representation of the Resource to be updated.
- Response Code: success (2.xx) or error (4.xx or 5.xx)
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 116
DELETE for DELETE
- Method code: DELETE (0.04)
- Request URI: an existing URI for the Resource to be deleted.
- Response code: success (2.xx) or error (4.xx or 5.xx)
3211
12.2.3.2 CREATE with POST or PUT 3212
12.2.3.2.1 With POST 3213
POST shall be used only in situations where the request URI is valid, that is it is the URI of an 3214
existing Resource on the Server that is processing the request. If no such Resource is present, 3215
the Server shall respond with an error response code of 4.xx. The use of POST for CREATE shall 3216
use an existing request URI which identifies the Resource on the Server responsible for creation. 3217
The URI of the created Resource is determined by the Server and provided to the Client in the 3218
response. 3219
A Client shall include the representation of the new Resource in the request payload. The new 3220
resource representation in the payload shall have all the necessary properties to create a valid 3221
Resource instance, i.e. the created Resource should be able to properly respond to the valid 3222
Request with mandatory Interface (e.g., “GET with ?if=oic.if.baseline”). 3223
Upon receiving the POST request, the Server shall either 3224
create the new Resource with a new URI, respond with the new URI for the newl y created 3225
Resource and a success response code (2.xx); or 3226
respond with an error response code (4.xx or 5.xx). 3227
POST is unsafe and is the supported method when idempotent behaviour cannot be expected or 3228
guaranteed. 3229
12.2.3.2.2 With PUT 3230
PUT shall be used to create a new Resource or completely replace the entire representation of an 3231
existing Resource. The resource representation in the payload of the PUT request shall be the 3232
complete representation. PUT for CREATE shall use a new request URI identifying the new 3233
Resource to be created. 3234
The new resource representation in the payload shall have all the necessary properties to create 3235
a valid Resource instance, i.e. the created Resource should be able to properly respond to the 3236
valid Request with mandatory Interface (e.g. “GET with ?if=oic.if.baseline”). 3237
Upon receiving the PUT request, the Server shall either 3238
create the new Resource with the request URI provided in the PUT request and send back a 3239
response with a success response code (2.xx); or 3240
respond with an error response code (4.xx or 5.xx). 3241
PUT is an unsafe method but it is idempotent, thus when a PUT request is repeated the outcome 3242
is the same each time. 3243
12.2.3.3 RETRIEVE with GET 3244
GET shall be used for the RETRIEVE operation. The GET method retrieves the representation of 3245
the target Resource identified by the request URI. 3246
Upon receiving the GET request, the Server shall either 3247
send back the response with the representation of the target Resource with a success response 3248
code (2.xx); or 3249
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 117
respond with an error response code (4.xx or 5.xx) or ignore it (e.g. non-applicable multicast 3250
GET). 3251
GET is a safe method and is idempotent. 3252
12.2.3.4 UPDATE with POST 3253
POST shall be used only in situations where the request URI is valid, that is it is the URI of an 3254
existing Resource on the Server that is processing the request. If no such Resource is present, 3255
the Server shall respond with an error response code of 4.xx. A client shall use POST to UPDATE 3256
Property values of an existing Resource (see Sections 3.1.32 and 8.4.2). 3257
Upon receiving the request, the Server shall either 3258
apply the request to the Resource identified by the request URI in accordance with the applied 3259
interface (i.e. POST for non-existent Properties is ignored) and send back a response with a 3260
success response code (2.xx); or 3261
respond with an error response code (4.xx or 5.xx). Note that if the representation in the 3262
payload is incompatible with the target Resource for POST using the applied inter face (i.e. the 3263
"overwrite" semantic cannot be honored because of read-only property in the payload), then 3264
the error response code 4.xx shall be returned. 3265
POST is unsafe and is the supported method when idempotent behaviour cannot be expected or 3266
guaranteed. 3267
12.2.3.5 DELETE with DELETE 3268
DELETE shall be used for DELETE operation. The DELETE method requests that the resource 3269
identified by the request URI be deleted. 3270
Upon receiving the DELETE request, the Server shall either 3271
delete the target Resource and send back a response with a success response code (2.xx); or 3272
respond with an error response code (4.xx or 5.xx). 3273
DELETE is unsafe but idempotent (unless URIs are recycled for new instances). 3274
3275
3276
Content-Format negotiation 3277
The OCF Framework mandates support of CBOR, however it allows for negotiation of the payload 3278
body if more than one Content-Format (e.g. CBOR and JSON) is supported by an implementation. 3279
In this case the Accept Option defined in section 5.10.4 of IETF RFC 7252 shall be used to indicate 3280
which Content–Format (e.g. JSON) is requested by the Client. 3281
The Content-Formats supported are shown in Table 33. 3282
Table 33. OCF Content-Formats 3283
Media Type ID
“application/cbor” 60
“application/vnd.ocf+cbor”
10000
Clients shall include a Content-Format Option in every message that contains a payload. Servers 3284
shall include a Content-Format Option for all success (2.xx) responses with a payload body. Per 3285
IETF RFC 7252 section 5.5.1, Servers shall include a Content-Format Option for all error (4.xx or 3286
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 118
5.xx) responses with a payload body unless they include a Diagnostic Payload; error responses 3287
with a Diagnostic Payload do not include a Content-Format Option. The Content-Format Option 3288
shall use the ID column numeric value from Table 33. An OCF vertical may mandate a specific 3289
Content-Format Option. 3290
Clients shall also include an Accept Option in every request message. The Accept Option shall 3291
indicate the required Content-Format as defined in Table 33 for response messages. The Server 3292
shall return the required Content-Format if available. If the required Content-Format cannot be 3293
returned, then the Server shall respond with an appropriate error message. 3294
OCF-Content-Format-Version information 3295
Servers and Clients shall include the OCF-Content-Format-Version in both request and response 3296
messages with a payload. Clients shall include the OCF-Accept-Content-Format-Version in 3297
request messages. The OCF-Content-Format-Version and OCF-Accept-Content-Format-Version 3298
are specified as Option Numbers in the CoAP header as shown in Table 34. 3299
Table 34. OCF-Content-Format-Version and OCF-Accept-Content-Format-Version Option 3300
Numbers 3301
CoAP Option Number
Name Format Length (bytes)
2049 OCF-Accept-Content-Format-Version
uint 2
2053 OCF-Content-Format-Version
uint 2
The value of the OCF-Accept-Content-Format-Version and the OCF-Content-Format-Version is a 3302
two-byte unsigned integer that is used to define the major, minor and sub versions. The major and 3303
minor versions are represented by 5 bits and the sub version is represented by 6 bits as shown in 3304
Table 35. 3305
Table 35. OCF-Accept-Content-Format-Version and the OCF-Content-Format-Version 3306
Representation 3307
Major Version Minor Version Sub Version
Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Table 36 illustrates several examples: 3308
Table 36. Examples of OCF-Content-Format-Version and OCF-Accept-Content-Format-3309
Version Representation 3310
OCF version Binary representation Integer value
1.0.0 0000 1000 0000 0000 2048
1.1.0 0000 1000 0100 0000 2112
The OCF-Accept-Content-Format-Version and OCF-Content-Format-Version for this version of the 3311
specification shall be 1.0.0 (i.e. 0b0000 1000 0000 0000). 3312
Content-Format policy 3313
To maintain compatibility between devices implemented to different versions of this specification, 3314
Devices shall follow the policy as described in Figure 38. 3315
3316
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 119
3317
Figure 38 Content-Format Policy 3318
All Devices shall support the current and all previous Content-Format Option and Versions. Clients 3319
shall send discovery request messages with the current and all previous Content-Format and 3320
Versions until it discovers all Servers in the network. 3321
CRUDN to CoAP response codes 3322
The mapping of CRUDN operations response codes to CoAP response codes are identical to the 3323
response codes defined in IETF RFC 7252. 3324
CoAP block transfer 3325
Basic CoAP messages work well for the small payloads typical of light-weight, constrained IoT 3326
devices. However scenarios can be envisioned in which an application needs to transfer larger 3327
payloads. 3328
CoAP block-wise transfer as defined in https://tools.ietf.org/html/rfc7721 3329
IETF RFC 7959 shall be used by all Servers which generate a content payload that would exceed 3330
the size of a CoAP datagram as the result of handling any defined CRUDN operation. 3331
Similarly, CoAP block-wise transfer as defined in https://tools.ietf.org/html/rfc7721 3332
IETF RFC 7959 shall be supported by all Clients. The use of block-wise transfer is applied to 3333
both the reception of payloads as well as transmission of payloads that would exceed the size of 3334
a CoAP datagram. 3335
All blocks that are sent using this mechanism for a single instance of a transfer shall all have the 3336
same reliability setting (i.e. all confirmable or all non-confirmable). 3337
A Client may support both the block1 (as descriptive) and block2 (as control) opt ions as 3338
described by IETF RFC 7959 A Server may support both the block1 (as control) and block2 (as 3339
descriptive) options as described by https://tools.ietf.org/html/rfc7721 3340
IETF RFC 7959. 3341
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 120
12.3 CoAP serialization over TCP 3342
12.3.1.1 Introduction 3343
In environments where TCP is already available, CoAP can take advantage of it to provide 3344
reliability. Also in some environments UDP traffic is blocked, so deployments may use TCP. For 3345
example, consider a cloud application acting as a Client and the Server is located at the user’s 3346
home. The Server which already support CoAP as a messaging protocol (e.g., Smart Home vertical 3347
profile) could easily support CoAP serialization over TCP rather than adding another messaging 3348
protocol. A Device implementing CoAP Serialization over TCP should conform to IETF draft-ietf-3349
core-coap-tcp-tls-07. 3350
12.3.1.2 Indication of support 3351
If UDP is blocked, clients depend on the pre-configured details on the device to find support for 3352
CoAP over TCP. If UDP is not-blocked, a Device which supports CoAP serialization over TCP shall 3353
populate the Messaging Protocol (“mpro”) property in “/oic/res” with the value “coap+tcp” or 3354
“coaps+tcp” to indicate that the device supports messaging protocol as specified by section 11.3.4. 3355
12.3.1.3 Message type and header 3356
The message type transported between Client and Server shall be a non-confirmable message 3357
(NON). The protocol stack used in this scenario should be as described in section 3 in IETF draft-3358
ietf-core-coap-tcp-tls-07. 3359
The CoAP header as described in figure 6 in IETF draft-ietf-core-coap-tcp-tls-07 should be used 3360
for messages transmitted between a Client and a Server. A Device should use “Alternative L3” as 3361
defined in IETF draft-ietf-core-coap-tcp-tls-07. 3362
12.3.1.4 URI scheme 3363
The URI scheme used shall be as defined in section 6 in IETF draft-ietf-core-coap-tcp-tls-07. 3364
For the “coaps+tcp” URI scheme the “TLS Application Layer Protocol Negotiation Extension” 3365
IETF RFC 7301 shall be used. 3366
12.3.1.5 KeepAlive 3367
12.3.1.5.1 Overview 3368
In order to ensure that the connection between a Device is maintained, when using CoAP 3369
serialization over TCP, a Device that initiated the connection should send application layer 3370
KeepAlive messages. The reasons to support application layer KeepAlive are as follows: 3371
TCP KeepAlive only guarantees that a connection is alive at the network layer, but not at the 3372
application layer 3373
Interval of TCP KeepAlive is configurable only using kernel parameters, and is OS dependent 3374
(e.g., 2 hours by default in Linux) 3375
12.3.1.5.2 KeepAlive Mechanism 3376
Devices supporting CoAP over TCP shall use the following KeepAlive mechanism. A Server shall 3377
support the “oic.wk.ping” Resource Type as defined in Table 37. 3378
Table 37. Ping resource 3379
Pre-defined
URI
Resource Type Title
Resource Type ID
(“rt” value)
Interfaces Description Related Functional Interaction
/oic/ping
Ping oic.wk.ping
“oic.if.rw” The resource using which a Client keeps its Connection with a Server active.
KeepAlive
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 121
The resource properties exposed by “/oic/ping” are listed in Table 38.
3380
Table 38 defines “oic.wk.ping” Resource Type. 3381
Table 38. “oic.wk.ping” Resource Type definition 3382
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
Interval in integer minutes R,W yes The time interval for which connection shall be kept alive and not closed. Default value is 0.
The following steps detail the KeepAlive mechanisms for a Client and Server: 3383
1) A Client which wants to keep the connection with a Server alive shall send a POST request to 3384
“/oic/ping” resource on the Server updating its connection Interval. 3385
a. This time interval shall start from 2 minutes and increases in multiples of 2 3386
up to a maximum of 64 minutes. It stays at 64 minutes from that point. 3387
5) A Server receiving this ping request shall respond within 1 minute . 3388
6) If a Client does not receive the response within 1 minute, it shall terminate the connection. 3389
7) If a Server does not receive a POST request to ping resource within the specified "interval" 3390
time, the Server shall terminate the connection. 3391
An example of the KeepAlive mechanism is as follows: 3392
Client → Server: “POST/oic/ping {interval: 2}” 3393
Server → Client: 2.03 valid 3394
12.4 Payload Encoding in CBOR 3395
OCF implementations shall perform the conversion to CBOR from JSON defined schemas and to 3396
JSON from CBOR in accordance with IETF RFC 7049 section 4 unless otherwise specified in this 3397
section. 3398
Properties defined as a JSON integer shall be encoded in CBOR as an integer (CBOR major types 3399
0 and 1). Properties defined as a JSON number shall be encoded as an integer, single - or double-3400
precision floating point (CBOR major type 7, sub-types 26 and 27); the choice is implementation 3401
dependent. Half-precision floating point (CBOR major 7, sub-type 25) shall not be used. Integer 3402
numbers shall be within the closed interval [-2^53, 2^53]. Properties defined as a JSON number 3403
should be encoded as integers whenever possible; if this is not possible Properties defined as a 3404
JSON number should use single-precision if the loss of precision does not affect the quality of 3405
service, otherwise the Property shall use double-precision. 3406
3407
On receipt of a CBOR payload, an implementation shall be able to interpret CBOR integer values 3408
in any position. If a property defined as a JSON integer is received encoded other than as an 3409
integer, the implementation may reject this encoding using a final response as appr opriate for the 3410
underlying transport (e.g. 4.00 for CoAP) and thus optimise for the integer case. If a property is 3411
defined as a JSON number an implementation shall accept integers, single - and double-precision 3412
floating point. 3413
13 Security 3414
The details for handling security and privacy are specified in [OCF Security]. 3415
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 122
3416
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 123
Annex A 3417
(informative) 3418
3419
Operation Examples 3420
A.1 Introduction 3421
This section describes some example scenarios using sequence of operations between the entities 3422
involved. In all the examples below “Light” is a Server and “Smartphone” is a Client. In one of the 3423
scenario “Garage” additionally acts as a Server. All the examples are based on the following 3424
example resource definitions: 3425
rt=oic.example.light with Resource Type definition as illustration in Table 39. 3426
Table 39. oic.example.light Resource Type definition 3427
Property title Property name
Value type
Value rule Unit Access mode
Mandatory Description
Name n string R, W no
on-off of boolean R, W yes On/Off Control:
0 = Off
1 = On
dim dm integer 0-255 R, W yes Resource which can take a range of values minimum being 0 and maximum being 255
3428
rt=oic.example.garagedoor with Resource Type definition as illustration in Table 40. 3429
Table 40. oic.example.garagedoor Resource Type definition 3430
Property title Property name
Value type
Value rule Unit Access mode
Mandatory Description
Name n string R, W no
open-close oc boolean R, W yes Open/Close Control:
0 = Open
1 = Close
3431
“/oic/mnt” (“rt=oic.wk.mnt”) used in below examples is defined in section 11.5.2. 3432
A.2 When at home: From smartphone turn on a single light 3433
This sequence highlights (Figure 39) the discovery and control of an OCF light resource from an 3434
OCF smartphone. 3435
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 124
3436
Figure 39. When at home: from smartphone turn on a single light 3437
Discovery request can be sent to “All OCF Nodes” Multicast address FF0X::158 or can be sent 3438
directly to the IP address of device hosting the light resource. 3439
1) Smartphone sends a GET request to “/oic/res” resource to discover all resources hosted on 3440
targeted end point 3441
8) The end point (bulb) responds with the list of Resource URI, Resource Type and 3442
Interfaces supported on the end point (one of the resource is ‘/light’ whose 3443
rt=oic.example.light) 3444
9) Smartphone sends a GET request to ’/light’ resource to know its c urrent state 3445
10) The end point responds with representation of light resource ({n=bedlight;of=0}) 3446
11) Smartphone changes the ‘of’ property of the light resource by sending a POST 3447
request to ‘/light’ resource ({of=1}) 3448
12) On Successful execution of the request, the end point responds with the changed 3449
resource representation. Else, error code is returned. Details of the error codes are defined 3450
in section 12.2.7. 3451
A.3 GroupAction execution 3452
This example will be added when groups feature is added in later version of specification 3453
A.4 When garage door opens, turn on lights in hall; also notify smartphone 3454
This example will be added when scripts feature is added in later version of specification 3455
A.5 Device management 3456
This sequence highlights (Figure 40) the device management function of maintenance. 3457
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 125
3458
3459
Figure 40. Device management (maintenance) 3460
Pre-Condition: Admin device has different security permissions and hence can perform device 3461
management operations on the Device 3462
1) Admin device sends a GET request to “/oic/res” resource to discover all resources hosted on 3463
a targeted end point (in this case Bulb) 3464
13) The end point (bulb) responds with the list of Resource URI, Resource Type and Interfaces 3465
supported on the end point (one of the resources is “/oic/mnt” whose “rt=oic.wk.mnt”) 3466
14) Admin Device changes the ‘fr’ property of the maintenance resource by 3467
sending a POST request to “/oic/mnt” resource ({fr=1}). This triggers a factory reset of the 3468
end point (bulb) 3469
15) On successful execution of the request, the end point responds with the changed 3470
resource representation. Else, error code is returned. Details of the error codes are defined 3471
in section 12.2.7. 3472
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 126
Annex B 3473
(informative) 3474
3475
OCF interaction scenarios and deployment models 3476
B.1 OCF interaction scenarios 3477
A Client connects to one or multiple Servers in order to access the resources provided by those 3478
Servers. The following are scenarios representing possible interactions among Roles: 3479
Direct interaction between Client and Server (Figure 41). In this scenario the Client and the 3480
Server directly communicate without involvement of any other Device. A smartphone which 3481
controls an actuator directly uses this scenario. 3482
3483
Figure 41. Direct interaction between Server and Client 3484
Interaction between Client and Server using another server (Figure 42). In this scenario, 3485
another Server provides the support needed for the Client to directly access the desired 3486
resource on a specific Server. This scenario is used for example, when a smartphon e first 3487
accesses a discovery server to find the addressing information of a specific appliance, and 3488
then directly accesses the appliance to control it. 3489
3490
Figure 42. Interaction between Client and Server using another Server 3491
Interaction between Client and Server using Intermediary (Figure 43). In this scenario an 3492
Intermediary facilitates the interaction between the Client and the Server. A sma rtphone which 3493
controls appliances in a smart home via MQTT broker uses this scenario. 3494
3495
Figure 43. Interaction between Client and Server using Intermediary 3496
Interaction between Client and Server using support from multiple Servers and intermediary 3497
(Figure 44). In this scenario, both Server and Intermediary roles are present to facilitate the 3498
transaction between the Client and a specific Server. An example scenario is when a 3499
smartphone first accesses a Resource Directory (RD) server to find the address to a specific 3500
appliance, then utilizes MQTT broker to deliver a command message to the appliance. The 3501
smartphone can utilize the mechanisms defined in CoRE Resource Directory such as default 3502
location, anycast address or DHCP to discover the Resource Directory information. 3503
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 127
3504
Figure 44. Interaction between Client and Server using support from multiple Servers and 3505
Intermediary 3506
B.2 Deployment model 3507
In deployment, Devices are deployed and interact via either wired or wireless connections. Devices 3508
are the physical entities that may host resources and play one or more Roles. There is no constraint 3509
on the structure of a deployment or number of Devices in it. Architecture is flexible and scalable 3510
and capable of addressing large number of devices with different device capabilities, including 3511
constrained devices which have limited memory and capabilities. Constrained devices are defined 3512
and categorized in [TCNN]. 3513
3514
Figure 45. Example of Devices 3515
Figure 45 depicts a typical deployment and set of Devices, which may be divided in the following 3516
categories: 3517
Things: Networked devices which are able to interface with physical environments. Things are 3518
the devices which are primarily controlled and monitored. Examples include smart appliances, 3519
sensors, and actuators. Things mostly take the role of Sever but they may also take the role of 3520
Client, for example in machine-to-machine communications. 3521
User Devices: Devices employed by the users enabling the users to access resources and 3522
services. Examples include smart phones, tablets, and wearable devices. User Devices mainly 3523
take the role of Client, but may also take the role of Server or Intermediary. 3524
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 128
Service Gateways: Network equipment which take the role of Intermediary. Examples are 3525
home gateways. 3526
Infra Servers: Data centers residing in cloud infrastructure, which facilitate the interaction 3527
among Devices by providing network services such as AAA, NAT traversal or discovery. It can 3528
also play the role of Client or Intermediary 3529
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 129
Annex C 3530
(informative) 3531
3532
Other Resource Models and OCF Mapping 3533
C.1 Multiple resource models 3534
RESTful interactions are defined dependent on the resource model; hence, Devices require a 3535
common understanding of the resource model for interoperability. 3536
There are multiple resource models defined by different organizations including OCF, IPSO 3537
Alliance and oneM2M, and used in the industry, which may restrict interoperability among 3538
respective ecosystems. The main differences from Resource model are as follows: 3539
Resource structure: Resources may be defined to have properties (e.g., oneM2M defined 3540
resources), or may be defined as an atomic entity and not be decomposable into properties 3541
(e.g., IPSO alliance defined resources). For example, a smart light may be represented as a 3542
resource with an on-off property or a resource collection containing an on-off resource. In the 3543
former, on-off property doesn’t have a URI of its own and can only be accessed indirectly via 3544
the resource. In the latter, being a resource itself, on-off resource is assigned its own URI and 3545
can be directly manipulated. 3546
Resource name & type: Resources may be allowed to be named freely and have their 3547
characteristics indicated using a Resource Type property (e.g., as defined in oneM2M). 3548
Alternatively, the name of resources may be defined a priori in a way that the name by itself is 3549
indicative of its characteristic (e.g., as defined by IPSO alliance). For example, in oneM2M 3550
resource model, a smart light can be named with no restrictions, such as ‘LivingRoomLight_1” 3551
but in IPSO alliance resource model it is required to have the fixed Object name with numerical 3552
Object ID of “IPSO Light Control (3311)”. Consequently, it’s likely that in the former case the 3553
data path in URI is freely defined and in the latter case it is predetermined. 3554
Resource hierarchy: Resources may be allowed to be organized in hierarchy where a resource 3555
contains another resource with a parent-child relationship (e.g., in oneM2M definition of 3556
resource model). Resources may also be required to have a flat structure and associate with 3557
other resources only by referencing their links. 3558
In addition to the above, different organizations use different syntax and define different features 3559
(e.g., resource interface), which preclude interoperability. 3560
C.2 OCF approach for support of multiple resource models 3561
In order to expand the IoT ecosystem the Framework takes an inclusive approach for interworking 3562
with existing resource models. Specifically, the Framework defines a resource model while 3563
providing a mechanism to easily map to other models. By embracing existing resource models 3564
OCF is inclusive of existing ecosystems while allowing for the transition toward definition of a 3565
comprehensive resource model integrating all ecosystems. 3566
The following OCF characteristics enable support of other resource models: 3567
resource model is the superset of multiple models : the resource model is defined as the 3568
superset of existing resource models. In other words, any existing resource model can be 3569
mapped to a subset of resource model concepts. 3570
Framework may allow for resource model negotiation: the Client and Server exchange the 3571
information about what resource model(s) each supports. Based on the exchanged information, 3572
the Client and Server choose a resource model to perform RESTful interactions or to perform 3573
translation. This feature is out of scope of the current version of this specification, however, 3574
the following is a high level description for resource model negotiation. 3575
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 130
C.3 Resource model indication 3576
The Client and server exchange the information about what resource model(s) each supports. 3577
Based on the exchanged information, the Client and Server choose a resource model to perform 3578
RESTful interactions or to perform translation. The exchange could be part of discovery and 3579
negotiation. Based on the exchange, the Client and Server fol low a procedure to ensure 3580
interoperability among them. They may choose a common resource model or execute translation 3581
between resource models. 3582
Resource model schema exchange: The Client and Server may share the resource model 3583
information when they initiate a RESTful interaction. They may exchange the information about 3584
which resource model they support as part of session establishment procedures. Alternatively, 3585
each request or response message may carry the indication of which resource model it is using. 3586
For example, [COAP] defines “Content-Format option” to indicate the “representation format” 3587
such as “application/json”. It’s possible to extend the Content -Format Option to indicate the 3588
resource model used with the representation format such as “application/i pso-json”. 3589
Ensuing procedures: After the Client and Server exchange the resource model information, 3590
they perform a suitable procedure to ensure interoperability among them. The simplest way is 3591
to choose a resource model supported by both the Client and Server. In case there is no 3592
common resource model, the Client and Server may interact through a 3rd party. 3593
In addition to translation which can be resource intensive, a method based on profiles can be used 3594
in which an OCF implementation can accommodate multiple profiles and hence multiple 3595
ecosystems. 3596
Resource Model Profile: the Framework defines resource model profiles and implementers or 3597
users choose the active profile. The chosen profile constraints the Device to strict rules in how 3598
resources are defined, instantiated and interacted with. This would allow for interoperation with 3599
devices from the ecosystem identified by the profile (e.g. , IPSO, OneM2M etc.). Although this 3600
enables a Device to participate in and be part of any given ecosystem, this scheme does not 3601
allow for generic interoperability at runtime. While this approach may be suitable for resource 3602
constrained devices, more resource capable devices are expected to support more than one 3603
profile. 3604
C.4 An Example Profile (IPSO profile) 3605
IPSO defines smart objects that have specific resources and they take values determined by the 3606
data type of that resource. The smart object specification defines a category of such objects. Each 3607
resource represents a characteristic of the smart object being modelled. 3608
While the terms may be different, there are equivalent concepts in OCF to represent these terms. 3609
This section provides the equivalent OCF terms and then frames the IPSO smart object in OCF 3610
terms. 3611
The IPSO object Light Control defined in Section 16 of the IPSO Smart Objects 1.0 is used as the 3612
reference example. 3613
C.4.1 Conceptual equivalence 3614
The IPSO smart object definition is equivalent to an Resource Type definition which defines the 3615
relevant characteristics of an entity being modelled. The specific IPSO Resource is equivalent to 3616
a Property that like an IPSO Resource has a defined data type, enumeration of acceptable values, 3617
units, a general description and access modes (based on the Interface). 3618
The general method for developing the equivalent Resource Type from an IPSO Smart Object 3619
definition is to ignore the Object ID and replace the Object URN with and OCF ‘.’ (dot) separated 3620
name that incorporates the IPSO object. Alternatively the Object URN can be used as the Resource 3621
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 131
Type ID as is (as long as the URN does not contain any ‘.’ (dots)) – using the same Object URN 3622
as the Resource Type ID allows for compatibility when interacting with an IPSO compliant device. 3623
The object URN based naming does not have any bearing for OCF to OCF interoperability and so 3624
the OCF format is preferred – for OCF to OCF interoperability only the data model consistency is 3625
required. 3626
Two models are available to render IPSO objects into OCF. 3627
1) One is where the IPSO Smart Object represents a Resource. In this case, the IP Smart Object 3628
is regarded as a resource with the Resource Type matching the description of the Smart Object. 3629
Furthermore, each resource in the IPSO definition is represented as a Property in the Resource 3630
Type (the IPSO Resource ID is replaced with a string representing the Property). This is the 3631
preferred approach when the IPSO Data Model is expressed in the Resource Model. 3632
16) The other approach is to model an IPSO Smart Object as a Col lection. Each IPSO 3633
Resource is then modelled as a Resource with an Resource Type tha t matches the 3634
definition of the IPSO Resource. Each of these resource instances are then bound to the 3635
Collection that represents this IPSO Smart Object. 3636
3637
Below is an example showing how an IPSO LightControl Object is modelled as a Resource. 3638
Resource Type: Light Control 3639
Description: This Object is used to control a light source, such as a LED or other light. It allows a 3640
light to be turned on or off and its dimmer setting to be controlled as a percentage value between 3641
0 and 100. An optional colour setting enables a string to be used to indicate the desired colour. 3642
Table 41 and Table 42 define the Resource Type and its properties, respectively. 3643
Table 41. Light control Resource Type definition 3644
Resource Type Resource Type ID Multiple Instances Description
Light Control “oic.light.control” or “urn:oma:lwm2m:ext:3311”
Yes Light control object with on/off and optional dimming and energy monitor
3645
Table 42. Light control Resource Type definition 3646
Property title Property name
Value type
Value rule
Unit Access mode
Mandatory Description
On/Off “on-off” boolean R, W yes On/Of Control:
0 = Off
1 = On
Dimmer “dim” integer % R, W no Proportional Control, integer value between 0 and 100 as percentage
Color “color” string 0 – 100 Defined by “units” property
R, W no String representing some value in color space
Units “units” string R no Measurement Units Definition e.g., “Cel” for Temperature in Celsius.
On Time “ontime” integer s R, W no The time in seconds that the light has been on.
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 132
Writing a value of 0 resets the counter
Cumulative active power
“cumap” float Wh R no The cumulative active power since the last cumulative energy reset or device start
Power Factor “powfact” float R no The power factor of the load
3647
3648
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 133
Annex D 3649
(normative) 3650
3651
Resource Type definitions 3652
D.1 List of Resource Type definitions 3653
Table 43 contains the list of defined core resources in this specification. 3654
Table 43. Alphabetized list of core resources 3655
Friendly Name (informative)
Resource Type (rt) Section
Collections “oic.wk.col” D.2
Device Configuration “oic.wk.con” D.3
Platform Configuration “oic.wk.con.p” D.4
Device “oic.wk.d” D.5
Discoverable Resources, baseline interface
“oic.wk.res” D.9
Discoverable Resources, link list interface
“oic.wk.res” D.10
Icon “oic.r.icon” D.15
Introspection “oic.wk.introspection” D.16
Maintenance “oic.wk.mnt” D.6
Platform “oic.wk.p” D.7
Ping “oic.wk.ping” D.8
Resource Directory “oic.wk.rd” D.14
Scenes (Top Level) “oic.wk.scenelist” D.11
Scenes Collections “oic.wk.scenecollection” D.12
Scenes Member “oic.wk.scenemember” D.13
3656
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 134
D.2 OCF Collection 3657
D.2.1 Introduction 3658
OCF Collection Resource Type contains properties and links. The oic.if.baseline interface exposes 3659
a representation of the links and the properties of the collection resource itself 3660
D.2.2 Example URI 3661
/CollectionBaselineInterfaceURI 3662
D.2.3 Resource Type 3663
The resource type (rt) is defined as: oic.wk.col. 3664
D.2.4 RAML Definition 3665
#%RAML 0.8 3666
title: Collections 3667 version: 1.0 3668
traits: 3669 - interface-ll : 3670 queryParameters: 3671
if: 3672 enum: ["oic.if.ll"] 3673
- interface-b : 3674 queryParameters: 3675
if: 3676 enum: ["oic.if.b"] 3677
- interface-baseline : 3678 queryParameters: 3679
if: 3680 enum: ["oic.if.baseline"] 3681
- interface-all : 3682 queryParameters: 3683
if: 3684 enum: ["oic.if.ll", "oic.if.baseline", "oic.if.b"] 3685
3686
/CollectionBaselineInterfaceURI: 3687
description: | 3688 OCF Collection Resource Type contains properties and links. 3689 The oic.if.baseline interface exposes a representation of 3690 the links and the properties of the collection resource itself 3691 3692
is : ['interface-baseline'] 3693
get: 3694
description: | 3695 Retrieve on Baseline Interface 3696 3697
responses : 3698
200: 3699
body: 3700 application/json: 3701
schema: | 3702
{ 3703 "$schema": "http://json-schema.org/draft-04/schema#", 3704 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 3705 reserved.", 3706 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-3707 schema.json#", 3708
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 135
"title": "Collection", 3709 "definitions": { 3710 "oic.collection.setoflinks": { 3711 "description": "A set (array) of simple or individual OIC Links. In 3712 addition to properties required for an OIC Link, the identifier for that link in this set is also 3713 required", 3714 "type": "array", 3715 "items": { 3716 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 3717 } 3718 }, 3719 "oic.collection.alllinks": { 3720 "description": "All forms of links in a collection", 3721 "oneOf": [ 3722 { 3723 "$ref": "#/definitions/oic.collection.setoflinks" 3724 } 3725 ] 3726 }, 3727 "oic.collection": { 3728 "type": "object", 3729 "description": "A collection is a set (array) of tagged-link or set 3730 (array) of simple links along with additional properties to describe the collection itself", 3731 "properties": { 3732 "id": { 3733 "anyOf": [ 3734 { 3735 "type": "integer", 3736 "description": "A number that is unique to that 3737 collection; like an ordinal number that is not repeated" 3738 }, 3739 { 3740 "type": "string", 3741 "description": "A unique string that could be a hash or 3742 similarly unique" 3743 }, 3744 { 3745 "$ref": "oic.types-schema.json#/definitions/uuid", 3746 "description": "A unique string that could be a UUIDv4" 3747 } 3748 ], 3749 "description": "ID for the collection. Can be an value that is 3750 unique to the use context or a UUIDv4" 3751 }, 3752 "di": { 3753 "$ref": "oic.types-schema.json#/definitions/uuid", 3754 "description": "The device ID which is an UUIDv4 string; used for 3755 backward compatibility with Spec A definition of /oic/res" 3756 }, 3757 "rts": { 3758 "$ref": "oic.core-3759 schema.json#/definitions/oic.core/properties/rt", 3760 "description": "Defines the list of allowable resource types (for 3761 Target and anchors) in links included in the collection; new links being created can only be from 3762 this list" }, 3763 "drel": { 3764 "type": "string", 3765 "description": "When specified this is the default relationship 3766 to use when an OIC Link does not specify an explicit relationship with *rel* parameter" 3767 }, 3768 "links": { 3769 "$ref": "#/definitions/oic.collection.alllinks" 3770 } 3771 } 3772 } 3773 }, 3774 "type": "object", 3775 "allOf": [ 3776 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 3777 {"$ref": "#/definitions/oic.collection"} 3778 ] 3779
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 136
} 3780 3781
example: | 3782
{ 3783 "rt": ["oic.wk.col"], 3784 "id": "unique_example_id", 3785 "rts": [ "oic.r.switch.binary", "oic.r.airflow" ], 3786 "links": [ 3787 { 3788 "href": "switch", 3789 "rt": ["oic.r.switch.binary"], 3790 "if": ["oic.if.a", "oic.if.baseline"], 3791 "eps": [ 3792 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 3793 {"ep": "coaps://[fe80::b1d6]:1122"}, 3794 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 3795 ] 3796 }, 3797 { 3798 "href": "airFlow", 3799 "rt": ["oic.r.airflow"], 3800 "if": ["oic.if.a", "oic.if.baseline"], 3801 "eps": [ 3802 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 3803 {"ep": "coaps://[fe80::b1d6]:1122"}, 3804 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 3805 ] 3806 } 3807 ] 3808 } 3809 3810
post: 3811
description: | 3812 Update on Baseline Interface 3813 3814
body: 3815 application/json: 3816
schema: | 3817
{ 3818 "$schema": "http://json-schema.org/draft-04/schema#", 3819 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 3820 reserved.", 3821 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-3822 schema.json#", 3823 "title": "Collection", 3824 "definitions": { 3825 "oic.collection.setoflinks": { 3826 "description": "A set (array) of simple or individual OIC Links. In addition 3827 to properties required for an OIC Link, the identifier for that link in this set is also required", 3828 "type": "array", 3829 "items": { 3830 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 3831 } 3832 }, 3833 "oic.collection.alllinks": { 3834 "description": "All forms of links in a collection", 3835 "oneOf": [ 3836 { 3837 "$ref": "#/definitions/oic.collection.setoflinks" 3838 } 3839 ] 3840 }, 3841 "oic.collection": { 3842 "type": "object", 3843 "description": "A collection is a set (array) of tagged-link or set (array) 3844 of simple links along with additional properties to describe the collection itself", 3845 "properties": { 3846
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 137
"id": { 3847 "anyOf": [ 3848 { 3849 "type": "integer", 3850 "description": "A number that is unique to that collection; 3851 like an ordinal number that is not repeated" 3852 }, 3853 { 3854 "type": "string", 3855 "description": "A unique string that could be a hash or 3856 similarly unique" 3857 }, 3858 { 3859 "$ref": "oic.types-schema.json#/definitions/uuid", 3860 "description": "A unique string that could be a UUIDv4" 3861 } 3862 ], 3863 "description": "ID for the collection. Can be an value that is unique 3864 to the use context or a UUIDv4" 3865 }, 3866 "di": { 3867 "$ref": "oic.types-schema.json#/definitions/uuid", 3868 "description": "The device ID which is an UUIDv4 string; used for 3869 backward compatibility with Spec A definition of /oic/res" 3870 }, 3871 "rts": { 3872 "$ref": "oic.core-schema.json#/definitions/oic.core/properties/rt", 3873 "description": "Defines the list of allowable resource types (for 3874 Target and anchors) in links included in the collection; new links being created can only be from 3875 this list" }, 3876 "drel": { 3877 "type": "string", 3878 "description": "When specified this is the default relationship to 3879 use when an OIC Link does not specify an explicit relationship with *rel* parameter" 3880 }, 3881 "links": { 3882 "$ref": "#/definitions/oic.collection.alllinks" 3883 } 3884 } 3885 } 3886 }, 3887 "type": "object", 3888 "allOf": [ 3889 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 3890 {"$ref": "#/definitions/oic.collection"} 3891 ] 3892 } 3893 3894
responses : 3895
200: 3896
body: 3897 application/json: 3898
schema: | 3899
{ 3900 "$schema": "http://json-schema.org/draft-04/schema#", 3901 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 3902 reserved.", 3903 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-3904 schema.json#", 3905 "title": "Collection", 3906 "definitions": { 3907 "oic.collection.setoflinks": { 3908 "description": "A set (array) of simple or individual OIC Links. In 3909 addition to properties required for an OIC Link, the identifier for that link in this set is also 3910 required", 3911 "type": "array", 3912 "items": { 3913 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 3914
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 138
} 3915 }, 3916 "oic.collection.alllinks": { 3917 "description": "All forms of links in a collection", 3918 "oneOf": [ 3919 { 3920 "$ref": "#/definitions/oic.collection.setoflinks" 3921 } 3922 ] 3923 }, 3924 "oic.collection": { 3925 "type": "object", 3926 "description": "A collection is a set (array) of tagged-link or set 3927 (array) of simple links along with additional properties to describe the collection itself", 3928 "properties": { 3929 "id": { 3930 "anyOf": [ 3931 { 3932 "type": "integer", 3933 "description": "A number that is unique to that 3934 collection; like an ordinal number that is not repeated" 3935 }, 3936 { 3937 "type": "string", 3938 "description": "A unique string that could be a hash or 3939 similarly unique" 3940 }, 3941 { 3942 "$ref": "oic.types-schema.json#/definitions/uuid", 3943 "description": "A unique string that could be a UUIDv4" 3944 } 3945 ], 3946 "description": "ID for the collection. Can be an value that is 3947 unique to the use context or a UUIDv4" 3948 }, 3949 "di": { 3950 "$ref": "oic.types-schema.json#/definitions/uuid", 3951 "description": "The device ID which is an UUIDv4 string; used for 3952 backward compatibility with Spec A definition of /oic/res" 3953 }, 3954 "rts": { 3955 "$ref": "oic.core-3956 schema.json#/definitions/oic.core/properties/rt", 3957 "description": "Defines the list of allowable resource types (for 3958 Target and anchors) in links included in the collection; new links being created can only be from 3959 this list" }, 3960 "drel": { 3961 "type": "string", 3962 "description": "When specified this is the default relationship 3963 to use when an OIC Link does not specify an explicit relationship with *rel* parameter" 3964 }, 3965 "links": { 3966 "$ref": "#/definitions/oic.collection.alllinks" 3967 } 3968 } 3969 } 3970 }, 3971 "type": "object", 3972 "allOf": [ 3973 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 3974 {"$ref": "#/definitions/oic.collection"} 3975 ] 3976 } 3977 3978
D.2.5 Property Definition 3979
Property name Value type Mandatory Access mode Description
rt array: see schema
yes Resource Type
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 139
di multiple types: see schema
Unique identifier for device (UUID)
title string A title for the link relation. Can be used by the UI to provide a context
eps array: see schema
the Endpoint information of the target Resource
pri (eps)
integer The priority among multiple Endpoints as specified in 10.2.3
ep (eps)
string URI with Transport Protocol Suites + Endpoint Locator as specified in 10.2.1
ins multiple types: see schema
The instance identifier for this web link in an array of web links - used in collections
p object: see schema
Specifies the framework policies on the Resource referenced by the target URI
bm (p)
integer yes Specifies the framework policies on the Resource referenced by the target URI for e.g. observable and discoverable
href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to make it unique.
rel multiple types: see schema
The relation of the target URI
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 140
referenced by the link to the context URI
type array: see schema
A hint at the representation of the resource referenced by the target URI. This represents the media types that are used for both accepting and emitting
anchor string This is used to override the context URI e.g. override the URI of the containing collection
if array: see schema
yes The interface set supported by this resource
D.2.6 CRUDN behavior 3980
Resource Create Read Update Delete Notify
/CollectionBaselineInterfaceURI get post
D.2.7 Referenced JSON schemas 3981
D.2.8 oic.oic-link-schema.json 3982
{ 3983 "$schema": "http://json-schema.org/draft-04/schema#", 3984 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 3985 reserved.", 3986 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.oic-link-schema.json#", 3987 "definitions": { 3988 "oic.oic-link": { 3989 "type": "object", 3990 "properties": { 3991 "href": { 3992 "type": "string", 3993 "maxLength": 256, 3994 "description": "This is the target URI, it can be specified as a Relative Reference or 3995 fully-qualified URI. Relative Reference should be used along with the di parameter to make it 3996 unique.", 3997 "format": "uri" 3998 }, 3999 "rel": { 4000 "oneOf":[ 4001 { 4002 "type": "array", 4003 "items": { 4004 "type": "string", 4005 "maxLength": 64 4006 }, 4007 "minItems": 1, 4008 "default": ["hosts"] 4009 }, 4010 { 4011 "type": "string", 4012 "maxLength": 64, 4013 "default": "hosts" 4014 } 4015 ], 4016
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 141
"description": "The relation of the target URI referenced by the link to the context URI" 4017 }, 4018 "rt": { 4019 "type": "array", 4020 "items" : { 4021 "type" : "string", 4022 "maxLength": 64 4023 }, 4024 "minItems" : 1, 4025 "description": "Resource Type" 4026 }, 4027 "if": { 4028 "type": "array", 4029 "items": { 4030 "type" : "string", 4031 "enum" : ["oic.if.baseline", "oic.if.ll", "oic.if.b", "oic.if.rw", "oic.if.r", 4032 "oic.if.a", "oic.if.s" ] 4033 }, 4034 "minItems": 1, 4035 "description": "The interface set supported by this resource" 4036 }, 4037 "di": { 4038 "$ref": "oic.types-schema.json#/definitions/uuid", 4039 "description": "Unique identifier for device (UUID)" 4040 }, 4041 "p": { 4042 "description": "Specifies the framework policies on the Resource referenced by the target 4043 URI", 4044 "type": "object", 4045 "properties": { 4046 "bm": { 4047 "description": "Specifies the framework policies on the Resource referenced by the 4048 target URI for e.g. observable and discoverable", 4049 "type": "integer" 4050 } 4051 }, 4052 "required" : ["bm"] 4053 }, 4054 "title": { 4055 "type": "string", 4056 "maxLength": 64, 4057 "description": "A title for the link relation. Can be used by the UI to provide a 4058 context" 4059 }, 4060 "anchor": { 4061 "type": "string", 4062 "maxLength": 256, 4063 "description": "This is used to override the context URI e.g. override the URI of the 4064 containing collection", 4065 "format": "uri" 4066 }, 4067 "ins": { 4068 "oneOf": [ 4069 { 4070 "type": "integer", 4071 "description": "An ordinal number that is not repeated - must be unique in the 4072 collection context" 4073 }, 4074 { 4075 "type": "string", 4076 "maxLength": 256, 4077 "format" : "uri", 4078 "description": "Any unique string including a URI" 4079 }, 4080 { 4081 "$ref": "oic.types-schema.json#/definitions/uuid", 4082 "description": "Unique identifier (UUID)" 4083 } 4084 ], 4085 "description": "The instance identifier for this web link in an array of web links - used 4086 in collections" 4087
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 142
}, 4088 "type": { 4089 "type": "array", 4090 "description": "A hint at the representation of the resource referenced by the target 4091 URI. This represents the media types that are used for both accepting and emitting", 4092 "items" : { 4093 "type": "string", 4094 "maxLength": 64 4095 }, 4096 "minItems": 1, 4097 "default": "application/cbor" 4098 }, 4099 "eps": { 4100 "type": "array", 4101 "description": "the Endpoint information of the target Resource", 4102 "items": { 4103 "type": "object", 4104 "properties": { 4105 "ep": { 4106 "type": "string", 4107 "format": "uri", 4108 "description": "URI with Transport Protocol Suites + Endpoint Locator as specified 4109 in 10.2.1" 4110 }, 4111 "pri": { 4112 "type": "integer", 4113 "minimum": 1, 4114 "description": "The priority among multiple Endpoints as specified in 10.2.3" 4115 } 4116 } 4117 } 4118 } 4119 }, 4120 "required": [ "href", "rt", "if" ] 4121 } 4122 }, 4123 "type": "object", 4124 "allOf": [ 4125 { "$ref": "#/definitions/oic.oic-link" } 4126 ] 4127 } 4128 4129
D.3 Device Configuration 4130
D.3.1 Introduction 4131
Resource that allows for Device specific information to be configured. 4132
D.3.2 Example URI 4133
/example/DeviceConfigurationResURI 4134
D.3.3 Resource Type 4135
The resource type (rt) is defined as: oic.wk.con. 4136
D.3.4 RAML Definition 4137
#%RAML 0.8 4138
title: OCF Configuration 4139 version: v1-20160622 4140
traits: 4141 - interface-rw : 4142 queryParameters: 4143
if: 4144 enum: ["oic.if.rw"] 4145
- interface-all : 4146 queryParameters: 4147
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 143
if: 4148 enum: ["oic.if.rw", "oic.if.baseline"] 4149
4150
/example/DeviceConfigurationResURI: 4151
description: | 4152 Resource that allows for Device specific information to be configured. 4153 4154
get: 4155
description: | 4156 Retrieves the current Device configuration settings 4157 4158
is : ['interface-all'] 4159
responses : 4160
200: 4161
body: 4162 application/json: 4163
schema: | 4164
{ 4165 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con-4166 schema.json#", 4167 "$schema": "http://json-schema.org/draft-04/schema#", 4168 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4169 rights reserved.", 4170 "definitions": { 4171 "oic.wk.con": { 4172 "type": "object", 4173 "properties": { 4174 "loc": { 4175 "type": "array", 4176 "description": "Location information", 4177 "items": { 4178 "type": "number" 4179 }, 4180 "minItems": 2, 4181 "maxItems": 2 4182 }, 4183 "locn": { 4184 "type": "string", 4185 "maxLength": 64, 4186 "description": "Human Friendly Name for location" 4187 }, 4188 "c": { 4189 "type": "string", 4190 "maxLength": 64, 4191 "description": "Currency" 4192 }, 4193 "r": { 4194 "type": "string", 4195 "maxLength": 64, 4196 "description": "Region" 4197 }, 4198 "ln": { 4199 "type": "array", 4200 "items" : 4201 { 4202 "type": "object", 4203 "properties": { 4204 "language": { 4205 "$ref": "oic.types-schema.json#/definitions/language-tag", 4206 "description": "An RFC 5646 language tag." 4207 }, 4208 "value": { 4209 "type": "string", 4210 "maxLength": 64, 4211 "description": "Device description in the indicated language." 4212
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 144
} 4213 } 4214 }, 4215 "minItems" : 1, 4216 "description": "Localized names" 4217 }, 4218 "dl": { 4219 "$ref": "oic.types-schema.json#/definitions/language-tag", 4220 "description": "Default Language" 4221 } 4222 } 4223 } 4224 }, 4225 "type": "object", 4226 "allOf": [ 4227 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4228 { "$ref": "#/definitions/oic.wk.con" } 4229 ], 4230 "required": ["n"] 4231 } 4232 4233
example: | 4234
{ 4235 "n": "My Friendly Device Name", 4236 "rt": ["oic.wk.con"], 4237 "loc": [32.777,-96.797], 4238 "locn": "My Location Name", 4239 "c": "USD", 4240 "r": "MyRegion", 4241 "dl": "en" 4242 } 4243 4244
post: 4245
description: | 4246 Update the information about the Device 4247 4248
is : ['interface-rw'] 4249
body: 4250 application/json: 4251
schema: | 4252
{ 4253 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con-Update-4254 schema.json#", 4255 "$schema": "http://json-schema.org/draft-04/schema#", 4256 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 4257 reserved.", 4258 "definitions": { 4259 "oic.wk.con": { 4260 "type": "object", 4261 "properties": { 4262 "loc": { 4263 "type": "array", 4264 "description": "Location information", 4265 "items": { 4266 "type": "number" 4267 }, 4268 "minItems": 2, 4269 "maxItems": 2 4270 }, 4271 "locn": { 4272 "type": "string", 4273 "maxLength": 64, 4274 "description": "Human Friendly Name for location" 4275 }, 4276 "c": { 4277 "type": "string", 4278 "maxLength": 64, 4279
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 145
"description": "Currency" 4280 }, 4281 "r": { 4282 "type": "string", 4283 "maxLength": 64, 4284 "description": "Region" 4285 }, 4286 "ln": { 4287 "type": "array", 4288 "items" : 4289 { 4290 "type": "object", 4291 "properties": { 4292 "language": { 4293 "$ref": "oic.types-schema.json#/definitions/language-tag", 4294 "description": "An RFC 5646 language tag." 4295 }, 4296 "value": { 4297 "type": "string", 4298 "maxLength": 64, 4299 "description": "Device description in the indicated language." 4300 } 4301 } 4302 }, 4303 "minItems" : 1, 4304 "description": "Localized names" 4305 }, 4306 "dl": { 4307 "$ref": "oic.types-schema.json#/definitions/language-tag", 4308 "description": "Default Language" 4309 } 4310 } 4311 } 4312 }, 4313 "type": "object", 4314 "allOf": [ 4315 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4316 { "$ref": "#/definitions/oic.wk.con" } 4317 ], 4318 "required": ["n"] 4319 } 4320 4321
example: | 4322
{ 4323 "n": "Nuevo Nombre Amistoso", 4324 "r": "MyNewRegion", 4325 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 4326 "dl": "es" 4327 } 4328 4329
responses : 4330
200: 4331
body: 4332 application/json: 4333
schema: | 4334
{ 4335 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con-Update-4336 schema.json#", 4337 "$schema": "http://json-schema.org/draft-04/schema#", 4338 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 4339 reserved.", 4340 "definitions": { 4341 "oic.wk.con": { 4342 "type": "object", 4343 "properties": { 4344 "loc": { 4345 "type": "array", 4346
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 146
"description": "Location information", 4347 "items": { 4348 "type": "number" 4349 }, 4350 "minItems": 2, 4351 "maxItems": 2 4352 }, 4353 "locn": { 4354 "type": "string", 4355 "maxLength": 64, 4356 "description": "Human Friendly Name for location" 4357 }, 4358 "c": { 4359 "type": "string", 4360 "maxLength": 64, 4361 "description": "Currency" 4362 }, 4363 "r": { 4364 "type": "string", 4365 "maxLength": 64, 4366 "description": "Region" 4367 }, 4368 "ln": { 4369 "type": "array", 4370 "items" : 4371 { 4372 "type": "object", 4373 "properties": { 4374 "language": { 4375 "$ref": "oic.types-schema.json#/definitions/language-tag", 4376 "description": "An RFC 5646 language tag." 4377 }, 4378 "value": { 4379 "type": "string", 4380 "maxLength": 64, 4381 "description": "Device description in the indicated language." 4382 } 4383 } 4384 }, 4385 "minItems" : 1, 4386 "description": "Localized names" 4387 }, 4388 "dl": { 4389 "$ref": "oic.types-schema.json#/definitions/language-tag", 4390 "description": "Default Language" 4391 } 4392 } 4393 } 4394 }, 4395 "type": "object", 4396 "allOf": [ 4397 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4398 { "$ref": "#/definitions/oic.wk.con" } 4399 ], 4400 "required": ["n"] 4401 } 4402 4403
example: | 4404
{ 4405 "n": "Nuevo Nombre Amistoso", 4406 "r": "MyNewRegion", 4407 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 4408 "dl": "es" 4409 } 4410 4411
D.3.5 Property Definition 4412
Property name Value type Mandatory Access mode Description
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 147
loc array: see schema
Location information
c string Currency
ln array: see schema
Localized names
value (ln)
string Device description in the indicated language.
language (ln)
multiple types: see schema
An RFC 5646 language tag.
locn string Human Friendly Name for location
dl multiple types: see schema
Default Language
r string Region
D.3.6 CRUDN behavior 4413
Resource Create Read Update Delete Notify
/example/DeviceConfigurationResURI get post
D.4 Platform Configuration 4414
D.4.1 Introduction 4415
Resource that allows for platform specific information to be configured. 4416
D.4.2 Example URI 4417
/example/PlatformConfigurationResURI 4418
D.4.3 Resource Type 4419
The resource type (rt) is defined as: oic.wk.con.p. 4420
D.4.4 RAML Definition 4421
#%RAML 0.8 4422
title: OCF Platform Configuration 4423 version: v1-20160622 4424
traits: 4425 - interface-rw : 4426 queryParameters: 4427
if: 4428 enum: ["oic.if.rw"] 4429
- interface-all : 4430 queryParameters: 4431
if: 4432 enum: ["oic.if.rw", "oic.if.baseline"] 4433
4434
/example/PlatformConfigurationResURI: 4435
description: | 4436 Resource that allows for platform specific information to be configured. 4437 4438
get: 4439
description: | 4440 Retrieves the current platform configuration settings 4441 4442
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 148
is : ['interface-all'] 4443
responses : 4444
200: 4445
body: 4446 application/json: 4447
schema: | 4448
{ 4449 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con.p-4450 schema.json#", 4451 "$schema": "http://json-schema.org/draft-04/schema#", 4452 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 4453 reserved.", 4454 "definitions": { 4455 "oic.wk.con.p": { 4456 "type": "object", 4457 "properties": { 4458 "mnpn": { 4459 "type": "array", 4460 "items" : 4461 { 4462 "type": "object", 4463 "properties": { 4464 "language": { 4465 "$ref": "oic.types-schema.json#/definitions/language-tag", 4466 "description": "An RFC 5646 language tag." 4467 }, 4468 "value": { 4469 "type": "string", 4470 "maxLength": 64, 4471 "description": "Platform description in the indicated language." 4472 } 4473 } 4474 }, 4475 "minItems" : 1, 4476 "description": "Platform names" 4477 } 4478 } 4479 } 4480 }, 4481 "type": "object", 4482 "allOf": [ 4483 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4484 { "$ref": "#/definitions/oic.wk.con.p" } 4485 ] 4486 } 4487 4488
example: | 4489
{ 4490 "rt": ["oic.wk.con.p"], 4491 "mnpn": [ { "language": "en", "value": "My Friendly Device Name" } ] 4492 } 4493 4494
post: 4495
description: | 4496 Update the information about the platform 4497 4498
is : ['interface-rw'] 4499
body: 4500 application/json: 4501
schema: | 4502
{ 4503 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con.p-Update-4504 schema.json#", 4505 "$schema": "http://json-schema.org/draft-04/schema#", 4506
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 149
"description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 4507 reserved.", 4508 "definitions": { 4509 "oic.wk.con.p": { 4510 "type": "object", 4511 "properties": { 4512 "mnpn": { 4513 "type": "array", 4514 "items" : 4515 { 4516 "type": "object", 4517 "properties": { 4518 "language": { 4519 "$ref": "oic.types-schema.json#/definitions/language-tag", 4520 "description": "An RFC 5646 language tag." 4521 }, 4522 "value": { 4523 "type": "string", 4524 "maxLength": 64, 4525 "description": "Platform description in the indicated language." 4526 } 4527 } 4528 }, 4529 "minItems" : 1, 4530 "description": "Platform names" 4531 } 4532 } 4533 } 4534 }, 4535 "type": "object", 4536 "allOf": [ 4537 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4538 { "$ref": "#/definitions/oic.wk.con.p" } 4539 ], 4540 "required": ["mnpn"] 4541 } 4542 4543
example: | 4544
{ 4545 "n": "Nuevo nombre", 4546 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 4547 } 4548 4549
responses : 4550
200: 4551
body: 4552 application/json: 4553
schema: | 4554
{ 4555 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con.p-Update-4556 schema.json#", 4557 "$schema": "http://json-schema.org/draft-04/schema#", 4558 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 4559 reserved.", 4560 "definitions": { 4561 "oic.wk.con.p": { 4562 "type": "object", 4563 "properties": { 4564 "mnpn": { 4565 "type": "array", 4566 "items" : 4567 { 4568 "type": "object", 4569 "properties": { 4570 "language": { 4571 "$ref": "oic.types-schema.json#/definitions/language-tag", 4572 "description": "An RFC 5646 language tag." 4573
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 150
}, 4574 "value": { 4575 "type": "string", 4576 "maxLength": 64, 4577 "description": "Platform description in the indicated language." 4578 } 4579 } 4580 }, 4581 "minItems" : 1, 4582 "description": "Platform names" 4583 } 4584 } 4585 } 4586 }, 4587 "type": "object", 4588 "allOf": [ 4589 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4590 { "$ref": "#/definitions/oic.wk.con.p" } 4591 ], 4592 "required": ["mnpn"] 4593 } 4594 4595
example: | 4596
{ 4597 "n": "Nuevo nombre", 4598 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 4599 } 4600 4601
D.4.5 Property Definition 4602
Property name Value type Mandatory Access mode Description
mnpn array: see schema
Platform names
value (mnpn)
string Platform description in the indicated language.
language (mnpn)
multiple types: see schema
An RFC 5646 language tag.
D.4.6 CRUDN behavior 4603
Resource Create Read Update Delete Notify
/example/PlatformConfigurationResURI get post
D.5 Device 4604
D.5.1 Introduction 4605
Known resource that is hosted by every Server. Allows for logical device specific information to be 4606
discovered. 4607
D.5.2 Wellknown URI 4608
/oic/d 4609
D.5.3 Resource Type 4610
The resource type (rt) is defined as: oic.wk.d. 4611
D.5.4 RAML Definition 4612
#%RAML 0.8 4613
title: OIC Root Device 4614 version: v1-20160622 4615
traits: 4616
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 151
- interface : 4617 queryParameters: 4618
if: 4619 enum: ["oic.if.r", "oic.if.baseline"] 4620
4621
/oic/d: 4622
description: | 4623 Known resource that is hosted by every Server. 4624 Allows for logical device specific information to be discovered. 4625 4626
is : ['interface'] 4627
get: 4628
description: | 4629 Retrieve the information about the Device 4630 4631
responses : 4632
200: 4633
body: 4634 application/json: 4635
schema: | 4636
{ 4637 "$schema": "http://json-schemas.org/draft-04/schema#", 4638 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4639 rights reserved.", 4640 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.d-4641 schema.json#", 4642 "definitions": { 4643 "oic.wk.d": { 4644 "type": "object", 4645 "properties": { 4646 "di": { 4647 "$ref": "oic.types-schema.json#/definitions/uuid", 4648 "readOnly": true, 4649 "description": "Unique identifier for device (UUID)" 4650 }, 4651 "icv": { 4652 "type": "string", 4653 "maxLength": 64, 4654 "readOnly": true, 4655 "description": "The version of the OIC Server" 4656 }, 4657 "dmv": { 4658 "type": "string", 4659 "maxLength": 256, 4660 "readOnly": true, 4661 "description": "Spec versions of the Resource and Device Specifications to 4662 which this device data model is implemented" 4663 }, 4664 "ld": { 4665 "type": "array", 4666 "items" : 4667 { 4668 "type": "object", 4669 "properties": { 4670 "language": { 4671 "$ref": "oic.types-schema.json#/definitions/language-tag", 4672 "readOnly": true, 4673 "description": "An RFC 5646 language tag." 4674 }, 4675 "value": { 4676 "type": "string", 4677 "maxLength": 64, 4678 "readOnly": true, 4679 "description": "Device description in the indicated language." 4680
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 152
} 4681 } 4682 }, 4683 "minItems" : 1, 4684 "readOnly": true, 4685 "description": "Localized Description." 4686 }, 4687 "sv": { 4688 "type": "string", 4689 "maxLength": 64, 4690 "readOnly": true, 4691 "description": "Software version." 4692 }, 4693 "dmn": { 4694 "type": "array", 4695 "items" : 4696 { 4697 "type": "object", 4698 "properties": { 4699 "language": { 4700 "$ref": "oic.types-schema.json#/definitions/language-tag", 4701 "readOnly": true, 4702 "description": "An RFC 5646 language tag." 4703 }, 4704 "value": { 4705 "type": "string", 4706 "maxLength": 64, 4707 "readOnly": true, 4708 "description": "Manufacturer name in the indicated language." 4709 } 4710 } 4711 }, 4712 "minItems" : 1, 4713 "readOnly": true, 4714 "description": "Manufacturer Name." 4715 }, 4716 "dmno": { 4717 "type": "string", 4718 "maxLength": 64, 4719 "readOnly": true, 4720 "description": "Model number as designated by manufacturer." 4721 }, 4722 "piid": { 4723 "$ref": "oic.types-schema.json#/definitions/uuid", 4724 "readOnly": true, 4725 "description": "Protocol independent unique identifier for device (UUID) 4726 that is immutable." 4727 } 4728 } 4729 } 4730 }, 4731 "type": "object", 4732 "allOf": [ 4733 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4734 { "$ref": "#/definitions/oic.wk.d" } 4735 ], 4736 "required": [ "n", "di", "icv", "dmv", "piid" ] 4737 } 4738 4739
example: | 4740
{ 4741 "n": "Device 1", 4742 "rt": ["oic.wk.d"], 4743 "di": "54919CA5-4101-4AE4-595B-353C51AA983C", 4744 "icv": "ocf.1.0.0", 4745 "dmv": "ocf.res.1.0.0, ocf.sh.1.0.0", 4746 "piid": "6F0AAC04-2BB0-468D-B57C-16570A26AE48" 4747 } 4748 4749
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 153
D.5.5 Property Definition 4750
Property name Value type Mandatory Access mode Description
ld array: see schema
Read Only Localized Description.
value (ld)
string Read Only Device description in the indicated language.
language (ld)
multiple types: see schema
Read Only An RFC 5646 language tag.
piid multiple types: see schema
yes Read Only Protocol independent unique identifier for device (UUID) that is immutable.
di multiple types: see schema
yes Read Only Unique identifier for device (UUID)
dmno string Read Only Model number as designated by manufacturer.
sv string Read Only Software version.
dmn array: see schema
Read Only Manufacturer Name.
value (dmn)
string Read Only Manufacturer name in the indicated language.
language (dmn)
multiple types: see schema
Read Only An RFC 5646 language tag.
dmv string yes Read Only Spec versions of the Resource and Device Specifications to which this device data model is implemented
icv string yes Read Only The version of the OIC Server
D.5.6 CRUDN behavior 4751
Resource Create Read Update Delete Notify
/oic/d get
D.6 Maintenance 4752
D.6.1 Introduction 4753
The resource through which a Device is maintained and can be used for diagnostic purposes. fr 4754
(Factory Reset) is a boolean. The value 0 means No action (Default), the value 1 means Start 4755
Factory Reset After factory reset, this value shall be changed back to the default value rb (Reboot) 4756
is a boolean. The value 0 means No action (Default), the value 1 means Start Reboot After Reboot, 4757
this value shall be changed back to the default value 4758
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 154
D.6.2 Wellknown URI 4759
/oic/mnt 4760
D.6.3 Resource Type 4761
The resource type (rt) is defined as: oic.wk.mnt. 4762
D.6.4 RAML Definition 4763
#%RAML 0.8 4764
title: Maintenance 4765 version: v1-20160622 4766
traits: 4767 - interface-rw : 4768 queryParameters: 4769
if: 4770 enum: ["oic.if.rw", "oic.if.baseline"] 4771
- interface-all : 4772 queryParameters: 4773
if: 4774 enum: ["oic.if.rw", "oic.if.r", "oic.if.baseline"] 4775
4776
/oic/mnt: 4777
description: | 4778 The resource through which a Device is maintained and can be used for diagnostic purposes. 4779 fr (Factory Reset) is a boolean. 4780 The value 0 means No action (Default), the value 1 means Start Factory Reset 4781 After factory reset, this value shall be changed back to the default value 4782 rb (Reboot) is a boolean. 4783 The value 0 means No action (Default), the value 1 means Start Reboot 4784 After Reboot, this value shall be changed back to the default value 4785 4786
get: 4787
is : ['interface-all'] 4788
description: | 4789 Retrieve the maintenance action status 4790 4791
responses : 4792
200: 4793
body: 4794 application/json: 4795
schema: | 4796
{ 4797 "$schema": "http://json-schemas.org/draft-04/schema#", 4798 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4799 rights reserved.", 4800 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.mnt-4801 schema.json#", 4802 "definitions": { 4803 "oic.wk.mnt": { 4804 "type": "object", 4805 "anyOf": [ 4806 {"required": ["fr"]}, 4807 {"required": ["rb"]} 4808 ], 4809 "properties": { 4810 "fr":{ 4811 "type": "boolean", 4812 "description": "Factory Reset" 4813 }, 4814 "rb": { 4815 "type": "boolean", 4816
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 155
"description": "Reboot Action" 4817 } 4818 } 4819 } 4820 }, 4821 "type": "object", 4822 "allOf": [ 4823 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4824 { "$ref": "#/definitions/oic.wk.mnt" } 4825 ] 4826 } 4827 4828
example: | 4829
{ 4830 "rt": ["oic.wk.mnt"], 4831 "fr": false, 4832 "rb": false 4833 } 4834 4835
post: 4836
is : ['interface-rw'] 4837
description: | 4838 Set the maintenance action(s) 4839 4840
body: 4841 application/json: 4842
schema: | 4843
{ 4844 "$schema": "http://json-schemas.org/draft-04/schema#", 4845 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 4846 reserved.", 4847 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.mnt-schema.json#", 4848 "definitions": { 4849 "oic.wk.mnt": { 4850 "type": "object", 4851 "anyOf": [ 4852 {"required": ["fr"]}, 4853 {"required": ["rb"]} 4854 ], 4855 "properties": { 4856 "fr":{ 4857 "type": "boolean", 4858 "description": "Factory Reset" 4859 }, 4860 "rb": { 4861 "type": "boolean", 4862 "description": "Reboot Action" 4863 } 4864 } 4865 } 4866 }, 4867 "type": "object", 4868 "allOf": [ 4869 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4870 { "$ref": "#/definitions/oic.wk.mnt" } 4871 ] 4872 } 4873 4874
example: | 4875
{ 4876 "fr": false, 4877 "rb": false 4878 } 4879 4880
responses : 4881
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 156
200: 4882
body: 4883 application/json: 4884
schema: | 4885
{ 4886 "$schema": "http://json-schemas.org/draft-04/schema#", 4887 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4888 rights reserved.", 4889 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.mnt-4890 schema.json#", 4891 "definitions": { 4892 "oic.wk.mnt": { 4893 "type": "object", 4894 "anyOf": [ 4895 {"required": ["fr"]}, 4896 {"required": ["rb"]} 4897 ], 4898 "properties": { 4899 "fr":{ 4900 "type": "boolean", 4901 "description": "Factory Reset" 4902 }, 4903 "rb": { 4904 "type": "boolean", 4905 "description": "Reboot Action" 4906 } 4907 } 4908 } 4909 }, 4910 "type": "object", 4911 "allOf": [ 4912 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4913 { "$ref": "#/definitions/oic.wk.mnt" } 4914 ] 4915 } 4916 4917
example: | 4918
{ 4919 "fr": false, 4920 "rb": false 4921 } 4922 4923
D.6.5 Property Definition 4924
Property name Value type Mandatory Access mode Description
fr boolean yes Factory Reset
rb boolean yes Reboot Action
D.6.6 CRUDN behavior 4925
Resource Create Read Update Delete Notify
/oic/mnt get post
D.7 Platform 4926
D.7.1 Introduction 4927
Known resource that is defines the platform on which an Server is hosted. Allows for platform 4928
specific information to be discovered. 4929
D.7.2 Wellknown URI 4930
/oic/p 4931
D.7.3 Resource Type 4932
The resource type (rt) is defined as: oic.wk.p. 4933
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 157
D.7.4 RAML Definition 4934
#%RAML 0.8 4935
title: Platform 4936 version: v1-20160622 4937
traits: 4938 - interface : 4939 queryParameters: 4940
if: 4941 enum: ["oic.if.r", "oic.if.baseline"] 4942
4943
/oic/p: 4944
description: | 4945 Known resource that is defines the platform on which an Server is hosted. 4946 Allows for platform specific information to be discovered. 4947 4948
is : ['interface'] 4949
get: 4950
description: | 4951 Retrieve the information about the Platform 4952 4953
responses : 4954
200: 4955
body: 4956 application/json: 4957
schema: | 4958
{ 4959 "$schema": "http://json-schemas.org/draft-04/schema#", 4960 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4961 rights reserved.", 4962 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.p-4963 schema.json#", 4964 "definitions": { 4965 "oic.wk.p": { 4966 "type": "object", 4967 "properties": { 4968 "pi": { 4969 "$ref": "oic.types-schema.json#/definitions/uuid", 4970 "readOnly": true, 4971 "description": "Platform Identifier as a UUID" 4972 }, 4973 "mnmn": { 4974 "type": "string", 4975 "readOnly": true, 4976 "description": "Manufacturer Name", 4977 "maxLength": 64 4978 }, 4979 "mnml": { 4980 "type": "string", 4981 "readOnly": true, 4982 "description": "Manufacturer's URL", 4983 "maxLength": 256, 4984 "format": "uri" 4985 }, 4986 "mnmo": { 4987 "type": "string", 4988 "maxLength": 64, 4989 "readOnly": true, 4990 "description": "Model number as designated by manufacturer" 4991 }, 4992 "mndt": { 4993 "$ref": "oic.types-schema.json#/definitions/date", 4994 "readOnly": true, 4995
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 158
"description": "Manufacturing Date." 4996 }, 4997 "mnpv": { 4998 "type": "string", 4999 "maxLength": 64, 5000 "readOnly": true, 5001 "description": "Platform Version" 5002 }, 5003 "mnos": { 5004 "type": "string", 5005 "maxLength": 64, 5006 "readOnly": true, 5007 "description": "Platform Resident OS Version" 5008 }, 5009 "mnhw": { 5010 "type": "string", 5011 "maxLength": 64, 5012 "readOnly": true, 5013 "description": "Platform Hardware Version" 5014 }, 5015 "mnfv": { 5016 "type": "string", 5017 "maxLength": 64, 5018 "readOnly": true, 5019 "description": "Manufacturer's firmware version" 5020 }, 5021 "mnsl": { 5022 "type": "string", 5023 "readOnly": true, 5024 "description": "Manufacturer's Support Information URL", 5025 "maxLength": 256, 5026 "format": "uri" 5027 }, 5028 "st": { 5029 "type": "string", 5030 "readOnly": true, 5031 "description": "Reference time for the device as defined in ISO 8601, where 5032 concatenation of 'date' and 'time' with the 'T' as a delimiter between 'date' and 'time'.", 5033 "format": "date-time" 5034 }, 5035 "vid": { 5036 "type": "string", 5037 "maxLength": 64, 5038 "readOnly": true, 5039 "description": "Manufacturer's defined string for the platform. The string 5040 is freeform and up to the manufacturer on what text to populate it" 5041 } 5042 } 5043 } 5044 }, 5045 "type": "object", 5046 "allOf": [ 5047 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 5048 { "$ref": "#/definitions/oic.wk.p" } 5049 ], 5050 "required": [ "pi", "mnmn" ] 5051 } 5052 5053
example: | 5054
{ 5055 "pi": "54919CA5-4101-4AE4-595B-353C51AA983C", 5056 "rt": ["oic.wk.p"], 5057 "mnmn": "Acme, Inc" 5058 } 5059 5060
D.7.5 Property Definition 5061
Property name Value type Mandatory Access mode Description
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 159
mnfv string Read Only Manufacturer's firmware version
vid string Read Only Manufacturer's defined string for the platform. The string is freeform and up to the manufacturer on what text to populate it
mnmn string yes Read Only Manufacturer Name
mnmo string Read Only Model number as designated by manufacturer
mnml string Read Only Manufacturer's URL
mnos string Read Only Platform Resident OS Version
mndt multiple types: see schema
Read Only Manufacturing Date.
st string Read Only Reference time for the device as defined in ISO 8601, where concatenation of 'date' and 'time' with the 'T' as a delimiter between 'date' and 'time'.
mnsl string Read Only Manufacturer's Support Information URL
mnpv string Read Only Platform Version
pi multiple types: see schema
yes Read Only Platform Identifier as a UUID
mnhw string Read Only Platform Hardware Version
D.7.6 CRUDN behavior 5062
Resource Create Read Update Delete Notify
/oic/p get
D.8 Ping 5063
D.8.1 Introduction 5064
The resource using which an Client keeps its Connection with an Server active. 5065
D.8.2 Wellknown URI 5066
/oic/ping 5067
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 160
D.8.3 Resource Type 5068
The resource type (rt) is defined as: oic.wk.ping. 5069
D.8.4 RAML Definition 5070
#%RAML 0.8 5071
title: Ping 5072 version: v1-20160622 5073
traits: 5074 - interface : 5075 queryParameters: 5076
if: 5077 enum: ["oic.if.rw", "oic.if.baseline"] 5078
5079
/oic/ping: 5080
description: | 5081 The resource using which an Client keeps its Connection with an Server active. 5082 5083
is : ['interface'] 5084
get: 5085
description: | 5086 Retrieve the ping information 5087 5088
responses : 5089
200: 5090
body: 5091 application/json: 5092
schema: | 5093
{ 5094 "$schema": "http://json-schemas.org/draft-04/schema#", 5095 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5096 rights reserved.", 5097 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.ping-5098 schema.json#", 5099 "definitions": { 5100 "oic.wk.ping": { 5101 "type": "object", 5102 "properties": { 5103 "in": { 5104 "type": "integer", 5105 "readOnly": false, 5106 "description": "Indicates the interval for which connection shall be kept 5107 alive" 5108 } 5109 } 5110 } 5111 }, 5112 "type": "object", 5113 "allOf": [ 5114 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 5115 { "$ref": "#/definitions/oic.wk.ping"} 5116 ], 5117 "required": [ 5118 "in" 5119 ] 5120 } 5121 5122
example: | 5123
{ 5124 "rt": ["oic.wk.ping"], 5125 "n": "Ping Information", 5126
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 161
"in": 16 5127 } 5128 5129
post: 5130
description: | 5131 Update or reset the alive interval 5132 5133
body: 5134 application/json: 5135
schema: | 5136
{ 5137 "$schema": "http://json-schemas.org/draft-04/schema#", 5138 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 5139 reserved.", 5140 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.ping-schema.json#", 5141 "definitions": { 5142 "oic.wk.ping": { 5143 "type": "object", 5144 "properties": { 5145 "in": { 5146 "type": "integer", 5147 "readOnly": false, 5148 "description": "Indicates the interval for which connection shall be kept 5149 alive" 5150 } 5151 } 5152 } 5153 }, 5154 "type": "object", 5155 "allOf": [ 5156 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 5157 { "$ref": "#/definitions/oic.wk.ping"} 5158 ], 5159 "required": [ 5160 "in" 5161 ] 5162 } 5163 5164
example: | 5165
{ 5166 "in": 16 5167 } 5168 5169
responses : 5170
203: 5171
description: | 5172 Successfully updated & restarted alive interval timer. 5173
body: 5174 application/json: 5175
schema: | 5176
{ 5177 "$schema": "http://json-schemas.org/draft-04/schema#", 5178 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5179 rights reserved.", 5180 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.ping-5181 schema.json#", 5182 "definitions": { 5183 "oic.wk.ping": { 5184 "type": "object", 5185 "properties": { 5186 "in": { 5187 "type": "integer", 5188 "readOnly": false, 5189 "description": "Indicates the interval for which connection shall be kept 5190
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 162
alive" 5191 } 5192 } 5193 } 5194 }, 5195 "type": "object", 5196 "allOf": [ 5197 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 5198 { "$ref": "#/definitions/oic.wk.ping"} 5199 ], 5200 "required": [ 5201 "in" 5202 ] 5203 } 5204 5205
example: | 5206
{ 5207 "in": 16 5208 } 5209 5210
D.8.5 Property Definition 5211
Property name Value type Mandatory Access mode Description
in integer Read Write Indicates the interval for which connection shall be kept alive
D.8.6 CRUDN behavior 5212
Resource Create Read Update Delete Notify
/oic/ping get post
D.9 Discoverable Resources Baseline Interface 5213
D.9.1 Introduction 5214
Baseline representation of /oic/res; list of discoverable resources 5215
D.9.2 Wellknown URI 5216
/oic/res 5217
D.9.3 Resource Type 5218
The resource type (rt) is defined as: oic.wk.res. 5219
D.9.4 RAML Definition 5220
#%RAML 0.8 5221
title: Discoverable Resources 5222 version: v1-20160622 5223
traits: 5224 - interface-ll : 5225 queryParameters: 5226
if: 5227 enum: ["oic.if.ll"] 5228
- interface-baseline : 5229 queryParameters: 5230
if: 5231 enum: ["oic.if.baseline"] 5232
5233
/oic-res-BaselineInterfaceURI: 5234
description: | 5235
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 163
Baseline representation of /oic/res; list of discoverable resources 5236 5237
is : ['interface-baseline'] 5238
get: 5239
description: | 5240 Retrieve the discoverable resource set, baseline interface 5241 5242
responses : 5243
200: 5244
body: 5245 application/json: 5246
schema: | 5247
{ 5248 "$schema": "http://json-schema.org/draft-v4/schema#", 5249 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5250 rights reserved.", 5251 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.res-5252 schema.json#", 5253 "definitions": { 5254 "oic.res-baseline": { 5255 "type": "object", 5256 "properties": { 5257 "rt": { 5258 "type": "array", 5259 "items" : { 5260 "type" : "string", 5261 "maxLength": 64 5262 }, 5263 "minItems" : 1, 5264 "readOnly": true, 5265 "description": "Resource Type" 5266 }, 5267 "if": { 5268 "type": "array", 5269 "items": { 5270 "type" : "string", 5271 "enum" : ["oic.if.baseline", "oic.if.ll"] 5272 }, 5273 "minItems": 1, 5274 "readOnly": true, 5275 "description": "The interface set supported by this resource" 5276 }, 5277 "n": { 5278 "type": "string", 5279 "maxLength": 64, 5280 "readOnly": true, 5281 "description": "Human friendly name" 5282 }, 5283 "mpro": { 5284 "readOnly": true, 5285 "description": "Supported messaging protocols", 5286 "type": "string", 5287 "maxLength": 64 5288 }, 5289 "links": { 5290 "type": "array", 5291 "items": { 5292 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 5293 } 5294 } 5295 }, 5296 "required": ["rt", "if", "links"] 5297 } 5298 }, 5299 "description": "The list of resources expressed as OIC links", 5300 "type": "array", 5301 "items": { 5302
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 164
"$ref": "#/definitions/oic.res-baseline" 5303 } 5304 } 5305 5306
example: | 5307
[ 5308 { 5309 "rt": ["oic.wk.res"], 5310 "if": ["oic.if.baseline", "oic.if.ll" ], 5311 "links": 5312 [ 5313 { 5314 "href": "/humidity", 5315 "rt": ["oic.r.humidity"], 5316 "if": ["oic.if.s"], 5317 "p": {"bm": 3}, 5318 "eps": [ 5319 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 5320 {"ep": "coaps://[fe80::b1d6]:1122"}, 5321 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 5322 ] 5323 }, 5324 { 5325 "href": "/temperature", 5326 "rt": ["oic.r.temperature"], 5327 "if": ["oic.if.s"], 5328 "p": {"bm": 3}, 5329 "eps": [ 5330 {"ep": "coaps://[[2001:db8:a::123]:2222"} 5331 ] 5332 } 5333 ] 5334 } 5335 ] 5336 5337
D.9.5 Property Definition 5338
Property name Value type Mandatory Access mode Description
rt array: see schema
yes Read Only Resource Type
n string Read Only Human friendly name
links array: see schema
yes
mpro string Read Only Supported messaging protocols
if array: see schema
yes Read Only The interface set supported by this resource
D.9.6 CRUDN behavior 5339
Resource Create Read Update Delete Notify
/oic/res get
D.10 Discoverable Resources Link List interface 5340
D.10.1 Introduction 5341
Link list representation of /oic/res; list of discoverable resources 5342
D.10.2 Wellknown URI 5343
/oic/res 5344
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 165
D.10.3 Resource Type 5345
The resource type (rt) is defined as: oic.wk.res. 5346
D.10.4 RAML Definition 5347
#%RAML 0.8 5348
title: Discoverable Resources 5349 version: v1-20160622 5350
traits: 5351 - interface-ll : 5352 queryParameters: 5353
if: 5354 enum: ["oic.if.ll"] 5355
- interface-baseline : 5356 queryParameters: 5357
if: 5358 enum: ["oic.if.baseline"] 5359
5360
/oic-res-llInterfaceURI: 5361
description: | 5362 Link list representation of /oic/res; list of discoverable resources 5363 5364
is : ['interface-ll'] 5365
get: 5366
description: | 5367 Retrieve the discoverable resource set, link list interface 5368 5369
responses : 5370
200: 5371
body: 5372 application/json: 5373
schema: | 5374
{ 5375 "$schema": "http://json-schema.org/draft-v4/schema#", 5376 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5377 rights reserved.", 5378 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.res-schema-5379 ll.json#", 5380 "description": "The list of resources expressed as OCF links without di", 5381 "definitions": { 5382 "oic.res-ll": { 5383 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 5384 } 5385 }, 5386 "type": "array", 5387 "items": { 5388 "$ref": "#/definitions/oic.res-ll" 5389 } 5390 } 5391 5392
example: | 5393
[ 5394 { 5395 "href": "/humidity", 5396 "rt": ["oic.r.humidity"], 5397 "if": ["oic.if.s"], 5398 "p": {"bm": 3}, 5399 "eps": [ 5400 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 5401 {"ep": "coaps://[fe80::b1d6]:1122"}, 5402
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 166
{"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 5403 ] 5404 }, 5405 { 5406 "href": "/temperature", 5407 "rt": ["oic.r.temperature"], 5408 "if": ["oic.if.s"], 5409 "p": {"bm": 3}, 5410 "eps": [ 5411 {"ep": "coaps://[[2001:db8:a::123]:2222"} 5412 ] 5413 } 5414 ] 5415 5416
D.10.5 Property Definition 5417
Property name Value type Mandatory Access mode Description
rt array: see schema
yes Resource Type
di multiple types: see schema
Unique identifier for device (UUID)
title string A title for the link relation. Can be used by the UI to provide a context
eps array: see schema
the Endpoint information of the target Resource
pri (eps)
integer The priority among multiple Endpoints as specified in 10.2.3
ep (eps)
string URI with Transport Protocol Suites + Endpoint Locator as specified in 10.2.1
ins multiple types: see schema
The instance identifier for this web link in an array of web links - used in collections
p object: see schema
Specifies the framework policies on the Resource referenced by the target URI
bm (p)
integer yes Specifies the framework policies on the Resource referenced by the target URI for
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 167
e.g. observable and discoverable
href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to make it unique.
rel multiple types: see schema
The relation of the target URI referenced by the link to the context URI
type array: see schema
A hint at the representation of the resource referenced by the target URI. This represents the media types that are used for both accepting and emitting
anchor string This is used to override the context URI e.g. override the URI of the containing collection
if array: see schema
yes The interface set supported by this resource
D.10.6 CRUDN behavior 5418
Resource Create Read Update Delete Notify
/oic/res get
D.10.7 Referenced JSON schemas 5419
D.10.8 oic.oic-link-schema.json 5420
{ 5421 "$schema": "http://json-schema.org/draft-04/schema#", 5422 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 5423 reserved.", 5424 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.oic-link-schema.json#", 5425 "definitions": { 5426 "oic.oic-link": { 5427 "type": "object", 5428 "properties": { 5429 "href": { 5430 "type": "string", 5431 "maxLength": 256, 5432 "description": "This is the target URI, it can be specified as a Relative Reference or 5433
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 168
fully-qualified URI. Relative Reference should be used along with the di parameter to make it 5434 unique.", 5435 "format": "uri" 5436 }, 5437 "rel": { 5438 "oneOf":[ 5439 { 5440 "type": "array", 5441 "items": { 5442 "type": "string", 5443 "maxLength": 64 5444 }, 5445 "minItems": 1, 5446 "default": ["hosts"] 5447 }, 5448 { 5449 "type": "string", 5450 "maxLength": 64, 5451 "default": "hosts" 5452 } 5453 ], 5454 "description": "The relation of the target URI referenced by the link to the context URI" 5455 }, 5456 "rt": { 5457 "type": "array", 5458 "items" : { 5459 "type" : "string", 5460 "maxLength": 64 5461 }, 5462 "minItems" : 1, 5463 "description": "Resource Type" 5464 }, 5465 "if": { 5466 "type": "array", 5467 "items": { 5468 "type" : "string", 5469 "enum" : ["oic.if.baseline", "oic.if.ll", "oic.if.b", "oic.if.rw", "oic.if.r", 5470 "oic.if.a", "oic.if.s" ] 5471 }, 5472 "minItems": 1, 5473 "description": "The interface set supported by this resource" 5474 }, 5475 "di": { 5476 "$ref": "oic.types-schema.json#/definitions/uuid", 5477 "description": "Unique identifier for device (UUID)" 5478 }, 5479 "p": { 5480 "description": "Specifies the framework policies on the Resource referenced by the target 5481 URI", 5482 "type": "object", 5483 "properties": { 5484 "bm": { 5485 "description": "Specifies the framework policies on the Resource referenced by the 5486 target URI for e.g. observable and discoverable", 5487 "type": "integer" 5488 } 5489 }, 5490 "required" : ["bm"] 5491 }, 5492 "title": { 5493 "type": "string", 5494 "maxLength": 64, 5495 "description": "A title for the link relation. Can be used by the UI to provide a 5496 context" 5497 }, 5498 "anchor": { 5499 "type": "string", 5500 "maxLength": 256, 5501 "description": "This is used to override the context URI e.g. override the URI of the 5502 containing collection", 5503 "format": "uri" 5504
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 169
}, 5505 "ins": { 5506 "oneOf": [ 5507 { 5508 "type": "integer", 5509 "description": "An ordinal number that is not repeated - must be unique in the 5510 collection context" 5511 }, 5512 { 5513 "type": "string", 5514 "maxLength": 256, 5515 "format" : "uri", 5516 "description": "Any unique string including a URI" 5517 }, 5518 { 5519 "$ref": "oic.types-schema.json#/definitions/uuid", 5520 "description": "Unique identifier (UUID)" 5521 } 5522 ], 5523 "description": "The instance identifier for this web link in an array of web links - used 5524 in collections" 5525 }, 5526 "type": { 5527 "type": "array", 5528 "description": "A hint at the representation of the resource referenced by the target 5529 URI. This represents the media types that are used for both accepting and emitting", 5530 "items" : { 5531 "type": "string", 5532 "maxLength": 64 5533 }, 5534 "minItems": 1, 5535 "default": "application/cbor" 5536 }, 5537 "eps": { 5538 "type": "array", 5539 "description": "the Endpoint information of the target Resource", 5540 "items": { 5541 "type": "object", 5542 "properties": { 5543 "ep": { 5544 "type": "string", 5545 "format": "uri", 5546 "description": "URI with Transport Protocol Suites + Endpoint Locator as specified 5547 in 10.2.1" 5548 }, 5549 "pri": { 5550 "type": "integer", 5551 "minimum": 1, 5552 "description": "The priority among multiple Endpoints as specified in 10.2.3" 5553 } 5554 } 5555 } 5556 } 5557 }, 5558 "required": [ "href", "rt", "if" ] 5559 } 5560 }, 5561 "type": "object", 5562 "allOf": [ 5563 { "$ref": "#/definitions/oic.oic-link" } 5564 ] 5565 } 5566 5567
D.11 Scenes (Top level) 5568
D.11.1 Introduction 5569
Toplevel Scene resource. This resource is a generic collection resource. The rts value shall contain 5570
oic.wk.scenecollection resource types. 5571
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 170
D.11.2 Example URI 5572
/SceneListResURI 5573
D.11.3 Resource Type 5574
The resource type (rt) is defined as: oic.wk.scenelist. 5575
D.11.4 RAML Definition 5576
#%RAML 0.8 5577
title: Scene 5578 version: v1-20160622 5579
traits: 5580 - interface : 5581 queryParameters: 5582
if: 5583 enum: ["oic.if.a", "oic.if.ll", "oic.if.baseline"] 5584
5585
/SceneListResURI: 5586
description: | 5587 Toplevel Scene resource. 5588 This resource is a generic collection resource. 5589 The rts value shall contain oic.wk.scenecollection resource types. 5590 5591
get: 5592
description: | 5593 Provides the current list of web links pointing to scenes 5594 5595
responses : 5596
200: 5597
body: 5598 application/json: 5599
schema: | 5600
{ 5601 "$schema": "http://json-schema.org/draft-04/schema#", 5602 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 5603 reserved.", 5604 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-5605 schema.json#", 5606 "title": "Collection", 5607 "definitions": { 5608 "oic.collection.setoflinks": { 5609 "description": "A set (array) of simple or individual OIC Links. In 5610 addition to properties required for an OIC Link, the identifier for that link in this set is also 5611 required", 5612 "type": "array", 5613 "items": { 5614 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 5615 } 5616 }, 5617 "oic.collection.alllinks": { 5618 "description": "All forms of links in a collection", 5619 "oneOf": [ 5620 { 5621 "$ref": "#/definitions/oic.collection.setoflinks" 5622 } 5623 ] 5624 }, 5625 "oic.collection": { 5626 "type": "object", 5627 "description": "A collection is a set (array) of tagged-link or set 5628 (array) of simple links along with additional properties to describe the collection itself", 5629 "properties": { 5630
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 171
"id": { 5631 "anyOf": [ 5632 { 5633 "type": "integer", 5634 "description": "A number that is unique to that 5635 collection; like an ordinal number that is not repeated" 5636 }, 5637 { 5638 "type": "string", 5639 "description": "A unique string that could be a hash or 5640 similarly unique" 5641 }, 5642 { 5643 "$ref": "oic.types-schema.json#/definitions/uuid", 5644 "description": "A unique string that could be a UUIDv4" 5645 } 5646 ], 5647 "description": "ID for the collection. Can be an value that is 5648 unique to the use context or a UUIDv4" 5649 }, 5650 "di": { 5651 "$ref": "oic.types-schema.json#/definitions/uuid", 5652 "description": "The device ID which is an UUIDv4 string; used for 5653 backward compatibility with Spec A definition of /oic/res" 5654 }, 5655 "rts": { 5656 "$ref": "oic.core-5657 schema.json#/definitions/oic.core/properties/rt", 5658 "description": "Defines the list of allowable resource types (for 5659 Target and anchors) in links included in the collection; new links being created can only be from 5660 this list" }, 5661 "drel": { 5662 "type": "string", 5663 "description": "When specified this is the default relationship 5664 to use when an OIC Link does not specify an explicit relationship with *rel* parameter" 5665 }, 5666 "links": { 5667 "$ref": "#/definitions/oic.collection.alllinks" 5668 } 5669 } 5670 } 5671 }, 5672 "type": "object", 5673 "allOf": [ 5674 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 5675 {"$ref": "#/definitions/oic.collection"} 5676 ] 5677 } 5678 5679
example: | 5680
{ 5681 "rt": ["oic.wk.scenelist"], 5682 "n": "list of scene Collections", 5683 "rts": ["oic.wk.scenecollection"], 5684 "links": [ 5685 ] 5686 } 5687 5688
D.11.5 Property Definition 5689
Property name Value type Mandatory Access mode Description
drel string When specified this is the default relationship to use when an OIC Link does not specify an
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 172
explicit relationship with *rel* parameter
links multiple types: see schema
id multiple types: see schema
ID for the collection. Can be an value that is unique to the use context or a UUIDv4
rts multiple types: see schema
Defines the list of allowable resource types (for Target and anchors) in links included in the collection; new links being created can only be from this list
di multiple types: see schema
The device ID which is an UUIDv4 string; used for backward compatibility with Spec A definition of /oic/res
D.11.6 CRUDN behavior 5690
Resource Create Read Update Delete Notify
/SceneListResURI get
D.12 Scene Collections 5691
D.12.1 Introduction 5692
Collection that models a set of Scenes. This resource is a generic collection resource with 5693
additional parameters. The rts value shall contain oic.scenemember resource types. The additional 5694
parameters are lastScene, this is the scene value last set by an y OCF Client sceneValues, this 5695
is the list of available scenes lastScene shall be listed in sceneValues. 5696
D.12.2 Example URI 5697
/SceneCollectionResURI 5698
D.12.3 Resource Type 5699
The resource type (rt) is defined as: oic.wk.scenecollection. 5700
D.12.4 RAML Definition 5701
#%RAML 0.8 5702
title: Scene 5703 version: v1-20160622 5704
traits: 5705 - interface : 5706 queryParameters: 5707
if: 5708
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 173
enum: ["oic.if.a", "oic.if.ll", "oic.if.baseline"] 5709
5710
/SceneCollectionResURI: 5711
description: | 5712 Collection that models a set of Scenes. 5713 This resource is a generic collection resource with additional parameters. 5714 The rts value shall contain oic.scenemember resource types. 5715 The additional parameters are 5716 lastScene, this is the scene value last set by any OCF Client 5717 sceneValues, this is the list of available scenes 5718 lastScene shall be listed in sceneValues. 5719 5720
get: 5721
description: | 5722 Provides the current list of web links pointing to scenes 5723 5724
responses : 5725
200: 5726
body: 5727 application/json: 5728
schema: | 5729
{ 5730 "$schema": "http://json-schema.org/draft-04/schema#", 5731 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5732 rights reserved.", 5733 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneCollection-5734 schema.json#", 5735 "title" : "Scene Collection", 5736 "definitions": { 5737 "oic.sceneCollection": { 5738 "type": "object", 5739 "properties": { 5740 "lastScene": { 5741 "type": "string", 5742 "description": "Last selected Scene, shall be part of sceneValues" 5743 }, 5744 "sceneValues": { 5745 "type": "string", 5746 "readOnly": true, 5747 "description": "All available scene values" 5748 }, 5749 "n": { 5750 "type": "string", 5751 "description": "Used to name the Scene collection" 5752 }, 5753 "id": { 5754 "type": "string", 5755 "description" : "A unique string that could be a hash or 5756 similarly unique" 5757 }, 5758 "rts": { 5759 "$ref": "oic.core-schema.json#/definitions/oic.core/properties/rt", 5760 "description": "Defines the list of allowable resource types in links 5761 included in the collection; new links being created can only be from this list" 5762 }, 5763 "links": { 5764 "type": "array", 5765 "description": "Array of OIC web links that are reference from this 5766 collection", 5767 "items" : { 5768 "allOf": [ 5769 { "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" }, 5770 { "required" : [ "ins" ] } 5771 ] 5772 } 5773
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 174
} 5774 }, 5775 "required": [ "lastScene","sceneValues","rts","id" ] 5776 } 5777 }, 5778 5779 "type": "object", 5780 "allOf" : [ 5781 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 5782 { "$ref": "#/definitions/oic.sceneCollection" } 5783 ] 5784 } 5785 5786
example: | 5787
{ 5788 "lastScene": "off", 5789 "sceneValues": "off,Reading,TVWatching", 5790 "rt": ["oic.wk.scenecollection"], 5791 "n": "My Scenes for my living room", 5792 "id": "0685B960-736F-46F7-BEC0-9E6CBD671ADC1", 5793 "rts": ["oic.wk.scenemember"], 5794 "links": [ 5795 ] 5796 } 5797 5798
post: 5799
description: | 5800 Provides the action to change the last set scene selection. 5801 Calling this method shall update all scene members to the prescribed membervalue. 5802 When this method is called with the same value as the current lastScene value 5803 then all scene members shall be updated. 5804 5805
body: 5806 application/json: 5807
schema: | 5808
{ 5809 "$schema": "http://json-schema.org/draft-04/schema#", 5810 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 5811 reserved.", 5812 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneCollection-5813 schema.json#", 5814 "title" : "Scene Collection", 5815 "definitions": { 5816 "oic.sceneCollection": { 5817 "type": "object", 5818 "properties": { 5819 "lastScene": { 5820 "type": "string", 5821 "description": "Last selected Scene, shall be part of sceneValues" 5822 }, 5823 "sceneValues": { 5824 "type": "string", 5825 "readOnly": true, 5826 "description": "All available scene values" 5827 }, 5828 "n": { 5829 "type": "string", 5830 "description": "Used to name the Scene collection" 5831 }, 5832 "id": { 5833 "type": "string", 5834 "description" : "A unique string that could be a hash or 5835 similarly unique" 5836 }, 5837 "rts": { 5838 "$ref": "oic.core-schema.json#/definitions/oic.core/properties/rt", 5839 "description": "Defines the list of allowable resource types in links included 5840
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 175
in the collection; new links being created can only be from this list" 5841 }, 5842 "links": { 5843 "type": "array", 5844 "description": "Array of OIC web links that are reference from this 5845 collection", 5846 "items" : { 5847 "allOf": [ 5848 { "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" }, 5849 { "required" : [ "ins" ] } 5850 ] 5851 } 5852 } 5853 }, 5854 "required": [ "lastScene" ] 5855 } 5856 }, 5857 5858 "type": "object", 5859 "allOf" : [ 5860 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 5861 { "$ref": "#/definitions/oic.sceneCollection" } 5862 ] 5863 } 5864 5865
example: | 5866
{ 5867 "lastScene": "Reading" 5868 } 5869 5870
responses : 5871
200: 5872
description: | 5873 Indicates that the value is changed. 5874 The changed properties are provided in the response. 5875 5876
body: 5877 application/json: 5878
schema: | 5879
{ 5880 "$schema": "http://json-schema.org/draft-04/schema#", 5881 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5882 rights reserved.", 5883 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneCollection-5884 schema.json#", 5885 "title" : "Scene Collection", 5886 "definitions": { 5887 "oic.sceneCollection": { 5888 "type": "object", 5889 "properties": { 5890 "lastScene": { 5891 "type": "string", 5892 "description": "Last selected Scene, shall be part of sceneValues" 5893 }, 5894 "sceneValues": { 5895 "type": "string", 5896 "readOnly": true, 5897 "description": "All available scene values" 5898 }, 5899 "n": { 5900 "type": "string", 5901 "description": "Used to name the Scene collection" 5902 }, 5903 "id": { 5904 "type": "string", 5905 "description" : "A unique string that could be a hash or 5906 similarly unique" 5907
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 176
}, 5908 "rts": { 5909 "$ref": "oic.core-schema.json#/definitions/oic.core/properties/rt", 5910 "description": "Defines the list of allowable resource types in links 5911 included in the collection; new links being created can only be from this list" 5912 }, 5913 "links": { 5914 "type": "array", 5915 "description": "Array of OIC web links that are reference from this 5916 collection", 5917 "items" : { 5918 "allOf": [ 5919 { "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" }, 5920 { "required" : [ "ins" ] } 5921 ] 5922 } 5923 } 5924 }, 5925 "required": [ "lastScene" ] 5926 } 5927 }, 5928 5929 "type": "object", 5930 "allOf" : [ 5931 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 5932 { "$ref": "#/definitions/oic.sceneCollection" } 5933 ] 5934 } 5935 5936
example: | 5937
{ 5938 "lastScene": "Reading" 5939 } 5940 5941
D.12.5 Property Definition 5942
Property name Value type Mandatory Access mode Description
lastScene string yes Last selected Scene, shall be part of sceneValues
links array: see schema
Array of OIC web links that are reference from this collection
sceneValues string yes Read Only All available scene values
n string Used to name the Scene collection
rts multiple types: see schema
yes Defines the list of allowable resource types in links included in the collection; new links being created can only be from this list
id string yes A unique string that could be a hash or similarly unique
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 177
D.12.6 CRUDN behavior 5943
Resource Create Read Update Delete Notify
/SceneCollectionResURI get post
D.13 Scene Member 5944
D.13.1 Introduction 5945
Collection that models a scene member. 5946
D.13.2 Example URI 5947
/SceneMemberResURI 5948
D.13.3 Resource Type 5949
The resource type (rt) is defined as: oic.wk.scenemember. 5950
D.13.4 RAML Definition 5951
#%RAML 0.8 5952
title: Scene 5953 version: v1-20160622 5954
traits: 5955 - interface : 5956 queryParameters: 5957
if: 5958 enum: ["oic.if.a", "oic.if.ll", "oic.if.baseline"] 5959
5960
/SceneMemberResURI: 5961
description: | 5962 Collection that models a scene member. 5963 5964
get: 5965
description: | 5966 Provides the scene member 5967 5968
responses : 5969
200: 5970
body: 5971 application/json: 5972
schema: | 5973
{ 5974 "$schema": "http://json-schema.org/draft-04/schema#", 5975 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5976 rights reserved.", 5977 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneMember-5978 schema.json#", 5979 "title" : "Scene Member", 5980 "definitions": { 5981 "oic.sceneMember": { 5982 "type": "object", 5983 "properties": { 5984 "n": { 5985 "type": "string", 5986 "description": "Used to name the Scene collection" 5987 }, 5988 "id": { 5989 "type": "string", 5990 "description": "Can be an value that is unique to the use context or a 5991 UUIDv4" 5992 }, 5993 "SceneMappings" : { 5994
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 178
"type": "array", 5995 "description": "array of mappings per scene, can be 1", 5996 "items": { 5997 "type": "object", 5998 "properties": { 5999 "scene": { 6000 "type": "string", 6001 "description": "Specifies a scene value that will acted upon" 6002 }, 6003 "memberProperty": { 6004 "type": "string", 6005 "readOnly": true, 6006 "description": "property name that will be mapped" 6007 }, 6008 "memberValue": { 6009 "type": "string", 6010 "readOnly": true, 6011 "description": "value of the Member Property" 6012 } 6013 }, 6014 "required": [ "scene", "memberProperty", "memberValue" ] 6015 } 6016 }, 6017 6018 "link": { 6019 "type": "string", 6020 "description": "web link that points at a resource", 6021 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 6022 } 6023 }, 6024 "required": [ "link" ] 6025 } 6026 }, 6027 6028 "type": "object", 6029 "allOf" : [ 6030 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 6031 { "$ref": "#/definitions/oic.sceneMember" } 6032 ] 6033 } 6034 6035
example: | 6036
{ 6037 "rt": ["oic.wk.scenemember"], 6038 "id": "0685B960-FFFF-46F7-BEC0-9E6234671ADC1", 6039 "n": "my binary switch (for light bulb) mappings", 6040 "link": { 6041 "href": "binarySwitch", 6042 "rt": ["oic.r.switch.binary"], 6043 "if": ["oic.if.a", "oic.if.baseline"], 6044 "eps": [ 6045 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 6046 {"ep": "coaps://[fe80::b1d6]:1122"}, 6047 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 6048 ] 6049 }, 6050 "sceneMappings": [ 6051 { 6052 "scene": "off", 6053 "memberProperty": "value", 6054 "memberValue": true 6055 }, 6056 { 6057 "scene": "Reading", 6058 "memberProperty": "value", 6059 "memberValue": false 6060 }, 6061 { 6062 "scene": "TVWatching", 6063 "memberProperty": "value", 6064
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 179
"memberValue": true 6065 } 6066 ] 6067 } 6068 6069
D.13.5 Property Definition 6070
Property name Value type Mandatory Access mode Description
SceneMappings array: see schema
array of mappings per scene, can be 1
memberValue (SceneMappings)
string yes Read Only value of the Member Property
memberProperty (SceneMappings)
string yes Read Only property name that will be mapped
scene (SceneMappings)
string yes Specifies a scene value that will acted upon
link string yes web link that points at a resource
id string Can be an value that is unique to the use context or a UUIDv4
n string Used to name the Scene collection
D.13.6 CRUDN behavior 6071
Resource Create Read Update Delete Notify
/SceneMemberResURI get
D.14 Resource directory resource 6072
D.14.1 Introduction 6073
Resource to be exposed by any Device that can act as a Resource Directory. 1) Provides selector 6074
criteria (e.g., integer) with GET request 2) Publish or Update a Link in /oic/res with POST request 6075
3) Delete a Link in /oic/res with DELETE request 6076
D.14.2 Wellknown URI 6077
/oic/rd 6078
D.14.3 Resource Type 6079
The resource type (rt) is defined as: oic.wk.rd. 6080
D.14.4 RAML Definition 6081
#%RAML 0.8 6082
title: Resource Directory 6083 version: v1-20160622 6084
traits: 6085 - rddelete-di : 6086 queryParameters: 6087
di: 6088 description: This is used to determine which set of links to operata on. (Need 6089 authentication to ensure that there is no spoofing). If instance is ommitted then the entire set of 6090 links from this device ID is deleted 6091
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 180
Example: DELETE /oic/rd?di="0685B960-736F-46F7-BEC0-9E6CBD671ADC1" 6092 6093
- rddelete-ins : 6094 queryParameters: 6095
ins: 6096 description: Instance of the link to delete 6097 Value of parameter is a string where instance to be deleted are comma separated 6098 Example: DELETE /oic/rd?di="0685B960-736F-46F7-BEC0-9E6CBD671ADC1";ins="20" 6099 6100
- rdgetinterface : 6101 queryParameters: 6102
if: 6103 enum: ["oic.if.baseline"] 6104 description: Interface is optional since there is only one interface supported for the 6105 Resource Type 6106 Both for RD selectin and for publish. 6107 Example: GET /oic/rd?if=oic.if.baseline 6108 6109
- rdpostinterface : 6110 queryParameters: 6111
rt: 6112 enum: ["oic.wk.rdpub"] 6113 description: Used in POST request to ask the RD to add the Links in payload to /oic/res. 6114 Example: POST /oic/rd?rt=oic.wk.rdpub 6115 6116
6117
/oic/rd: 6118
description: | 6119 Resource to be exposed by any Device that can act as a Resource Directory. 6120 1) Provides selector criteria (e.g., integer) with GET request 6121 2) Publish or Update a Link in /oic/res with POST request 6122 3) Delete a Link in /oic/res with DELETE request 6123 6124
get: 6125
description: | 6126 Get the attributes of the Resource Directory for selection purposes. 6127 6128
is : ['rdgetinterface'] 6129
responses : 6130
200: 6131
description: | 6132 Respond with the selector criteria - either the set of attributes or the bias factor 6133 6134
body: 6135 application/json: 6136
schema: | 6137
{ 6138 "$schema": "http://json-schema.org/draft-04/schema#", 6139 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 6140 rights reserved.", 6141 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.rd.selection-6142 schema.json#", 6143 "title" : "RD Selection", 6144 "definitions": { 6145 "oic.rd.attributes": { 6146 "type": "object", 6147 "oneOf": [ 6148 { 6149 "properties": { 6150 "sel": { 6151 "type": "integer", 6152
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 181
"minimum": 0, 6153 "maximum": 100, 6154 "description": "A bias factor calculated by the Resource directory - 6155 the value is in the range of 0 to 100 - 0 implies that RD is not to be selected. Client chooses RD 6156 with highest bias factor or randomly between RDs that have same bias factor" 6157 } 6158 }, 6159 "required": ["sel"] 6160 }, 6161 { 6162 "properties": { 6163 "sel": { 6164 "description": "Selection criteria that a device wanting to publish to 6165 any RD can use to choose this Resource Directory over others that are discovered", 6166 "type": "object", 6167 "properties": { 6168 "pwr": { 6169 "type": "string", 6170 "enum": [ "ac", "batt", "safe" ], 6171 "description": "A hint about how the RD is powered. If AC then this 6172 is stronger than battery powered. If source is reliable (safe) then appropriate mechanism for 6173 managing power failure exists" 6174 }, 6175 "conn": { 6176 "type": "string", 6177 "enum": [ "wrd", "wrls" ], 6178 "description": "A hint about the networking connectivity of the RD. 6179 *wrd* if wired connected and *wrls* if wireless connected." 6180 }, 6181 "bw": { 6182 "type": "string", 6183 "description": "Qualitative bandwidth of the connection", 6184 "enum": [ "high", "low", "lossy" ] 6185 }, 6186 "mf": { 6187 "type": "integer", 6188 "description": "Memory factor - Ratio of available memory to total 6189 memory expressed as a percentage" 6190 }, 6191 "load": { 6192 "type": "array", 6193 "items": { 6194 "type": "number" 6195 }, 6196 "minItems": 3, 6197 "maxItems": 3, 6198 "description": "Current load capacity of the RD. Expressed as a 6199 load factor 3-tuple (upto two decimal points each). Load factor is based on request processed in a 6200 1 minute, 5 minute window and 15 minute window" 6201 } 6202 } 6203 } 6204 }, 6205 "required": ["sel"] 6206 } 6207 ] 6208 } 6209 }, 6210 "type": "object", 6211 "allOf": [ 6212 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 6213 { "$ref": "#/definitions/oic.rd.attributes" } 6214 ] 6215 } 6216 6217
example: | 6218
{ 6219 "rt": ["oic.wk.rd"], 6220 "if": ["oic.if.baseline"], 6221 "sel": 50 6222
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 182
} 6223 6224
post: 6225
description: | 6226 Publish the resource information for the first time or Update the existing one in /oic/res. 6227 Appropriates parts of the information, i.e., Links of the published Resources will be 6228 discovered through /oic/res. 6229 1) When a Device first publishes a Link, the request payload to RD may include the Links 6230 without "ins" Parameter. 6231 2) Upon granting the request, the RD assigns a unique instance value identifying the Link 6232 among all the Links it advertises 6233 and sends back the instance value in "ins" Parameter in the Link to the publishing Device. 6234 3) When later the publishing Device updates the existing Link, i.e., changing its Endpoint 6235 information, 6236 the request payload to RD needs to include the instance value in "ins" Parameter to 6237 identify the Link to update. 6238 6239
is : ['rdpostinterface'] 6240
body: 6241 application/json: 6242
schema: | 6243
{ 6244 "$schema": "http://json-schema.org/draft-04/schema#", 6245 "description": "Copyright (c) 2016,2017 Open Connectivity Foundation, Inc. All rights 6246 reserved.", 6247 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.rd.publish-6248 schema.json#", 6249 "title": "RD Publish & Update", 6250 "definitions": { 6251 "oic.rd.publish": { 6252 "description": "Publishes resources as OIC Links into the resource directory", 6253 "properties": { 6254 "di": { 6255 "$ref": "oic.types-schema.json#/definitions/uuid", 6256 "description": "A unique identifier for the publishing Device, i.e., its device 6257 ID" 6258 }, 6259 "links": { 6260 "$ref": "oic.collection-schema.json#/definitions/oic.collection.setoflinks" 6261 }, 6262 "ttl": { 6263 "type": "integer", 6264 "description": "Time to indicate a RD, how long to keep this published item. 6265 After this time (in seconds) elapses, the RD invalidates the links. To keep link alive the 6266 publishing device updates the ttl using the update schema" 6267 } 6268 } 6269 } 6270 }, 6271 "type": "object", 6272 "allOf": [ 6273 { 6274 "$ref": "oic.core-schema.json#/definitions/oic.core" 6275 }, 6276 { 6277 "$ref": "#/definitions/oic.rd.publish" 6278 } 6279 ], 6280 "required": [ 6281 "di", 6282 "links", 6283 "ttl" 6284 ] 6285 } 6286 6287
example: | 6288
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 183
{ 6289 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6290 "links": [ 6291 { 6292 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6293 "href": "/myLightSwitch", 6294 "rt": ["oic.r.switch.binary"], 6295 "if": ["oic.if.a", "oic.if.baseline"], 6296 "p": {"bm": 3}, 6297 "eps": [ 6298 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 6299 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 6300 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 6301 ] 6302 }, 6303 { 6304 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6305 "href": "/myLightBrightness", 6306 "rt": ["oic.r.brightness"], 6307 "if": ["oic.if.a", "oic.if.baseline"], 6308 "p": {"bm": 3}, 6309 "eps": [ 6310 {"ep": "coaps://[[2001:db8:a::123]:2222"} 6311 ] 6312 } 6313 ], 6314 "ttl": 600 6315 } 6316 6317
responses : 6318
200: 6319
description: | 6320 Respond with the same schema as publish but, when a Link is first published, 6321 with the additional "ins" Parameter in the Link. 6322 This value is used by the receiver to manage that OCF Link instance. 6323 6324
body: 6325 application/json: 6326
schema: | 6327
{ 6328 "$schema": "http://json-schema.org/draft-04/schema#", 6329 "description": "Copyright (c) 2016,2017 Open Connectivity Foundation, Inc. All 6330 rights reserved.", 6331 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.rd.publish-6332 schema.json#", 6333 "title": "RD Publish & Update", 6334 "definitions": { 6335 "oic.rd.publish": { 6336 "description": "Publishes resources as OIC Links into the resource directory", 6337 "properties": { 6338 "di": { 6339 "$ref": "oic.types-schema.json#/definitions/uuid", 6340 "description": "A unique identifier for the publishing Device, i.e., its 6341 device ID" 6342 }, 6343 "links": { 6344 "$ref": "oic.collection-schema.json#/definitions/oic.collection.setoflinks" 6345 }, 6346 "ttl": { 6347 "type": "integer", 6348 "description": "Time to indicate a RD, how long to keep this published 6349 item. After this time (in seconds) elapses, the RD invalidates the links. To keep link alive the 6350 publishing device updates the ttl using the update schema" 6351 } 6352 } 6353 } 6354 }, 6355 "type": "object", 6356
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 184
"allOf": [ 6357 { 6358 "$ref": "oic.core-schema.json#/definitions/oic.core" 6359 }, 6360 { 6361 "$ref": "#/definitions/oic.rd.publish" 6362 } 6363 ], 6364 "required": [ 6365 "di", 6366 "links", 6367 "ttl" 6368 ] 6369 } 6370 6371
example: | 6372
{ 6373 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6374 "links": [ 6375 { 6376 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6377 "href": "/myLightSwitch", 6378 "rt": ["oic.r.switch.binary"], 6379 "if": ["oic.if.a", "oic.if.baseline"], 6380 "p": {"bm": 3}, 6381 "eps": [ 6382 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 6383 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 6384 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 6385 ], 6386 "ins": "11235" 6387 }, 6388 { 6389 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6390 "href": "/myLightBrightness", 6391 "rt": ["oic.r.brightness"], 6392 "if": ["oic.if.a", "oic.if.baseline"], 6393 "p": {"bm": 3}, 6394 "eps": [ 6395 {"ep": "coaps://[2001:db8:a::123]:2222"} 6396 ], 6397 "ins": "112358" 6398 } 6399 ], 6400 "ttl": 600 6401 } 6402 6403
delete: 6404
description: | 6405 Delete a particular OIC Link - the link may be a simple link or a link in a tagged set. 6406 6407
is : ['rddelete-di','rddelete-ins'] 6408
responses : 6409
200: 6410
description: | 6411 The delete succeeded 6412 6413
D.14.5 Property Definition 6414
Property name Value type Mandatory Access mode Description
sel object: see schema
yes Selection criteria that a device wanting to publish to any
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 185
RD can use to choose this Resource Directory over others that are discovered
mf (sel)
integer Memory factor - Ratio of available memory to total memory expressed as a percentage
load (sel)
array: see schema
Current load capacity of the RD. Expressed as a load factor 3-tuple (upto two decimal points each). Load factor is based on request processed in a 1 minute, 5 minute window and 15 minute window
bw (sel)
string Qualitative bandwidth of the connection
pwr (sel)
string A hint about how the RD is powered. If AC then this is stronger than battery powered. If source is reliable (safe) then appropriate mechanism for managing power failure exists
conn (sel)
string A hint about the networking connectivity of the RD. *wrd* if wired connected and *wrls* if wireless connected.
D.14.6 CRUDN behavior 6415
Resource Create Read Update Delete Notify
/oic/rd get post delete
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 186
D.15 Icon 6416
D.15.1 Introduction 6417
This resource describes the attributes associated with an Icon. 6418
D.15.2 Example URI 6419
/IconResURI 6420
D.15.3 Resource Type 6421
The resource type (rt) is defined as: oic.r.icon. 6422
D.15.4 RAML Definition 6423
#%RAML 0.8 6424
title: OICIcon 6425 version: v1.1.0-20161107 6426
traits: 6427 - interface : 6428 queryParameters: 6429
if: 6430 enum: ["oic.if.r", "oic.if.baseline"] 6431
6432
/IconResURI: 6433
description: | 6434 This resource describes the attributes associated with an Icon. 6435 6436
is : ['interface'] 6437
get: 6438
description: | 6439 Retrieves the current icon properties. 6440 6441
responses : 6442
200: 6443
body: 6444 application/json: 6445
schema: | 6446
{ 6447 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.r.icon.json#", 6448 "$schema": "http://json-schema.org/draft-04/schema#", 6449 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 6450 reserved.", 6451 "title": "Icon", 6452 "definitions": { 6453 "oic.r.icon": { 6454 "properties": { 6455 "mimetype": { 6456 "type": "string", 6457 "maxLength": 64, 6458 "readOnly": true, 6459 "description": "Specifies the format of the MIME Type" 6460 }, 6461 "width": { 6462 "type": "integer", 6463 "minimum": 1, 6464 "readOnly": true, 6465 "description": "Specifies the width in pixels" 6466 }, 6467 "height": { 6468 "type": "integer", 6469 "minimum": 1, 6470 "readOnly": true, 6471
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 187
"description": "Specifies the height in pixels" 6472 }, 6473 "media": { 6474 "type": "string", 6475 "maxLength": 256, 6476 "format" : "uri", 6477 "readOnly": true, 6478 "description": "Specifies the media URL to icon" 6479 } 6480 } 6481 } 6482 }, 6483 "type": "object", 6484 "allOf": [ 6485 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 6486 { "$ref": "#/definitions/oic.r.icon"} 6487 ], 6488 "required": ["mimetype","width","height","media"] 6489 } 6490 6491
example: | 6492
{ 6493 "rt": ["oic.r.icon"], 6494 "id": "unique_example_id", 6495 "mimetype": "image/png", 6496 "width": 256, 6497 "height": 256, 6498 "media": "http://findbetter.ru/public/uploads/1481662800/2043.png" 6499 } 6500 6501
D.15.5 Property Definition 6502
Property name Value type Mandatory Access mode Description
mimetype string yes Read Only Specifies the format of the MIME Type
width integer yes Read Only Specifies the width in pixels
media string yes Read Only Specifies the media URL to icon
height integer yes Read Only Specifies the height in pixels
D.15.6 CRUDN behavior 6503
Resource Create Read Update Delete Notify
/IconResURI get
D.16 Introspection Resource 6504
D.16.1 Introduction 6505
This resource provides the means to get the device introspection data specifiying all the endpoints 6506
of the device. The url hosted by this resource is either a local or an external url. 6507
D.16.2 Example URI 6508
/IntrospectionResURI 6509
D.16.3 Resource Type 6510
The resource type (rt) is defined as: oic.wk.introspection. 6511
D.16.4 RAML Definition 6512
#%RAML 0.8 6513
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 188
title: OICIntrospection 6514 version: v1.0.0-20160707 6515
traits: 6516 - interface : 6517 queryParameters: 6518
if: 6519 enum: ["oic.if.r", "oic.if.baseline"] 6520
6521
/IntrospectionResURI: 6522
description: | 6523 This resource provides the means to get the device introspection data specifiying all the 6524 endpoints of the device. 6525 The url hosted by this resource is either a local or an external url. 6526 6527
is : ['interface'] 6528
get: 6529 responses : 6530
200: 6531
body: 6532 application/json: 6533
schema: | 6534
{ 6535 "id": "http://www.openconnectivity.org/ocf-6536 apis/core/schemas/oic.wk.introspectionInfo.json#", 6537 "$schema": "http://json-schema.org/draft-04/schema#", 6538 "description" : "Copyright (c) 2017 Open Interconnect Consortium, Inc. All rights 6539 reserved.", 6540 "title": "introspection resource", 6541 "definitions": { 6542 "oic.wk.introspectionInfo": { 6543 "type": "object", 6544 "properties": { 6545 "urlInfo": { 6546 "type": "array", 6547 "description": "The valid range for the value Property", 6548 "readOnly": true, 6549 "minItems": 1, 6550 "items": { 6551 "type" : "object", 6552 "properties": { 6553 "url": { 6554 "type": "string", 6555 "format": "uri", 6556 "description" : "url to download the description" 6557 }, 6558 "protocol": { 6559 "type": "string", 6560 "enum": [ "coap", "coaps", "http", "https", "coap+tcp", 6561 "coaps+tcp" ], 6562 "description" : "protocol to be used to download the introspection" 6563 }, 6564 "content-type": { 6565 "type": "string", 6566 "enum": [ "application/json", "application/cbor" ], 6567 "default" : "application/cbor", 6568 "description" : "content-type of the introspection data" 6569 }, 6570 "version": { 6571 "type": "integer", 6572 "enum": [ 1 ], 6573 "default" : 1, 6574 "description" : "version the introspection data that can be 6575 downloaded" 6576 } 6577 }, 6578
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 189
"required" : [ "url","protocol"] 6579 } 6580 } 6581 }, 6582 "required" : ["urlInfo"] 6583 } 6584 }, 6585 "type": "object", 6586 "allOf": [ 6587 {"$ref": "#/definitions/oic.wk.introspectionInfo"}, 6588 {"$ref": "oic.core-schema.json#/definitions/oic.core"} 6589 ] 6590 } 6591 6592
example: | 6593
{ 6594 "rt" : ["oic.wk.introspection"], 6595 "urlInfo" : [ 6596 { 6597 "content-type" : "application/cbor", 6598 "protocol" : "coap", 6599 "url" : "coap://[fe80::1]:1234/IntrospectionExampleURI" 6600 } 6601 ] 6602 } 6603 6604
D.16.5 Property Definition 6605
Property name Value type Mandatory Access mode Description
urlInfo array: see schema
yes Read Only The valid range for the value Property
url (urlInfo)
string yes url to download the description
content-type (urlInfo)
string content-type of the introspection data
version (urlInfo)
integer version the introspection data that can be downloaded
protocol (urlInfo)
string yes protocol to be used to download the introspection
D.16.6 CRUDN behavior 6606
Resource Create Read Update Delete Notify
/IntrospectionResURI get
6607
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 190
Annex E 6608
(informative) 6609
6610
Swagger2.0 definitions 6611
6612
E.1 Icon 6613
E.1.1 Introduction 6614
This resource describes the attributes associated with an Icon. 6615
Retrieves the current icon properties. 6616
6617
E.1.2 Example URI 6618
/IconResURI 6619
E.1.3 Resource Type 6620
The resource type (rt) is defined as: ['oic.r.icon']. 6621
E.1.4 Swagger2.0 Definition 6622
{ 6623 "swagger": "2.0", 6624 "info": { 6625 "title": "Icon", 6626 "version": "v1.1.0-20161107", 6627 "license": { 6628 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 6629 "x-description": "Redistribution and use in source and binary forms, with or without 6630 modification, are permitted provided that the following conditions are met:\n 1. 6631 Redistributions of source code must retain the above copyright notice, this list of conditions and 6632 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 6633 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 6634 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 6635 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 6636 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 6637 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 6638 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 6639 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 6640 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 6641 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 6642 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 6643 OF SUCH DAMAGE.\n" 6644 } 6645 }, 6646 "schemes": ["http"], 6647 "consumes": ["application/json"], 6648 "produces": ["application/json"], 6649 "paths": { 6650 "/IconResURI" : { 6651 "get": { 6652 "description": "This resource describes the attributes associated with an Icon.\nRetrieves 6653 the current icon properties.\n", 6654 "parameters": [ 6655 {"$ref": "#/parameters/interface"} 6656 ], 6657 "responses": { 6658 "200": { 6659 "description" : "", 6660 "x-example": 6661 { 6662 "rt": ["oic.r.icon"], 6663 "id": "unique_example_id", 6664 "mimetype": "image/png", 6665 "width": 256, 6666
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 191
"height": 256, 6667 "media": "http://findbetter.ru/public/uploads/1481662800/2043.png" 6668 } 6669 , 6670 "schema": { "$ref": "#/definitions/Icon" } 6671 } 6672 } 6673 } 6674 } 6675 }, 6676 "parameters": { 6677 "interface" : { 6678 "in" : "query", 6679 "name" : "if", 6680 "type" : "string", 6681 "enum" : ["oic.if.r", "oic.if.baseline"] 6682 } 6683 }, 6684 "definitions": { 6685 "Icon" : 6686 { 6687 "properties": { 6688 "height": { 6689 "description": "Specifies the height in pixels", 6690 "minimum": 1, 6691 "readOnly": true, 6692 "type": "integer" 6693 }, 6694 "id": { 6695 "description": "Instance ID of this specific resource", 6696 "maxLength": 64, 6697 "readOnly": true, 6698 "type": "string" 6699 }, 6700 "if": { 6701 "description": "The interface set supported by this resource", 6702 "items": { 6703 "enum": [ 6704 "oic.if.baseline", 6705 "oic.if.ll", 6706 "oic.if.b", 6707 "oic.if.lb", 6708 "oic.if.rw", 6709 "oic.if.r", 6710 "oic.if.a", 6711 "oic.if.s" 6712 ], 6713 "type": "string" 6714 }, 6715 "minItems": 1, 6716 "readOnly": true, 6717 "type": "array" 6718 }, 6719 "media": { 6720 "description": "Specifies the media URL to icon", 6721 "format": "uri", 6722 "maxLength": 256, 6723 "readOnly": true, 6724 "type": "string" 6725 }, 6726 "mimetype": { 6727 "description": "Specifies the format of the MIME Type", 6728 "maxLength": 64, 6729 "readOnly": true, 6730 "type": "string" 6731 }, 6732 "n": { 6733 "description": "Friendly name of the resource", 6734 "maxLength": 64, 6735 "readOnly": true, 6736 "type": "string" 6737
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 192
}, 6738 "rt": { 6739 "description": "Resource Type", 6740 "items": { 6741 "maxLength": 64, 6742 "type": "string" 6743 }, 6744 "minItems": 1, 6745 "readOnly": true, 6746 "type": "array" 6747 }, 6748 "width": { 6749 "description": "Specifies the width in pixels", 6750 "minimum": 1, 6751 "readOnly": true, 6752 "type": "integer" 6753 } 6754 }, 6755 "required": [ 6756 "mimetype", 6757 "width", 6758 "height", 6759 "media" 6760 ] 6761 } 6762 6763 } 6764 } 6765 6766
E.1.5 Property Definition 6767
Property name Value type Mandatory Access mode Description
width integer yes Read Only Specifies the width in pixels
rt array: see schema
Read Only Resource Type
id string Read Only Instance ID of this specific resource
height integer yes Read Only Specifies the height in pixels
mimetype string yes Read Only Specifies the format of the MIME Type
n string Read Only Friendly name of the resource
if array: see schema
Read Only The interface set supported by this resource
media string yes Read Only Specifies the media URL to icon
E.1.6 CRUDN behavior 6768
Resource Create Read Update Delete Notify
/IconResURI get
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 193
E.2 Introspection Resource 6769
E.2.1 Introduction 6770
This resource provides the means to get the device introspection data specifiying all the endpoints 6771
of the device. 6772
The url hosted by this resource is either a local or an external url. 6773
6774
E.2.2 Example URI 6775
/IntrospectionResURI 6776
E.2.3 Resource Type 6777
The resource type (rt) is defined as: ['oic.wk.introspection']. 6778
E.2.4 Swagger2.0 Definition 6779
{ 6780 "swagger": "2.0", 6781 "info": { 6782 "title": "Introspection Resource", 6783 "version": "v1.0.0-20160707", 6784 "license": { 6785 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 6786 "x-description": "Redistribution and use in source and binary forms, with or without 6787 modification, are permitted provided that the following conditions are met:\n 1. 6788 Redistributions of source code must retain the above copyright notice, this list of conditions and 6789 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 6790 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 6791 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 6792 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 6793 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 6794 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 6795 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 6796 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 6797 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 6798 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 6799 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 6800 OF SUCH DAMAGE.\n" 6801 } 6802 }, 6803 "schemes": ["http"], 6804 "consumes": ["application/json"], 6805 "produces": ["application/json"], 6806 "paths": { 6807 "/IntrospectionResURI" : { 6808 "get": { 6809 "description": "This resource provides the means to get the device introspection data 6810 specifiying all the endpoints of the device.\nThe url hosted by this resource is either a local or 6811 an external url.\n", 6812 "parameters": [ 6813 {"$ref": "#/parameters/interface"} 6814 ], 6815 "responses": { 6816 "200": { 6817 "description" : "", 6818 "x-example": 6819 { 6820 "rt" : ["oic.wk.introspection"], 6821 "urlInfo" : [ 6822 { 6823 "content-type" : "application/cbor", 6824 "protocol" : "coap", 6825 "url" : "coap://[fe80::1]:1234/IntrospectionExampleURI" 6826 } 6827 ] 6828 } 6829 , 6830 "schema": { "$ref": "#/definitions/oic.wk.introspectionInfo" } 6831
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 194
} 6832 } 6833 } 6834 } 6835 }, 6836 "parameters": { 6837 "interface" : { 6838 "in" : "query", 6839 "name" : "if", 6840 "type" : "string", 6841 "enum" : ["oic.if.r", "oic.if.baseline"] 6842 } 6843 }, 6844 "definitions": { 6845 "oic.wk.introspectionInfo" : 6846 { 6847 "properties": { 6848 "id": { 6849 "description": "Instance ID of this specific resource", 6850 "maxLength": 64, 6851 "readOnly": true, 6852 "type": "string" 6853 }, 6854 "if": { 6855 "description": "The interface set supported by this resource", 6856 "items": { 6857 "enum": [ 6858 "oic.if.baseline", 6859 "oic.if.ll", 6860 "oic.if.b", 6861 "oic.if.lb", 6862 "oic.if.rw", 6863 "oic.if.r", 6864 "oic.if.a", 6865 "oic.if.s" 6866 ], 6867 "type": "string" 6868 }, 6869 "minItems": 1, 6870 "readOnly": true, 6871 "type": "array" 6872 }, 6873 "n": { 6874 "description": "Friendly name of the resource", 6875 "maxLength": 64, 6876 "readOnly": true, 6877 "type": "string" 6878 }, 6879 "rt": { 6880 "description": "Resource Type", 6881 "items": { 6882 "maxLength": 64, 6883 "type": "string" 6884 }, 6885 "minItems": 1, 6886 "readOnly": true, 6887 "type": "array" 6888 }, 6889 "urlInfo": { 6890 "description": "The valid range for the value Property", 6891 "items": { 6892 "properties": { 6893 "content-type": { 6894 "default": "application/cbor", 6895 "description": "content-type of the introspection data", 6896 "enum": [ 6897 "application/json", 6898 "application/cbor" 6899 ], 6900 "type": "string" 6901 }, 6902
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 195
"protocol": { 6903 "description": "protocol to be used to download the introspection", 6904 "enum": [ 6905 "coap", 6906 "coaps", 6907 "http", 6908 "https", 6909 "coap+tcp", 6910 "coaps+tcp" 6911 ], 6912 "type": "string" 6913 }, 6914 "url": { 6915 "description": "url to download the description", 6916 "format": "uri", 6917 "type": "string" 6918 }, 6919 "version": { 6920 "default": 1, 6921 "description": "version the introspection data that can be downloaded", 6922 "enum": [ 6923 1 6924 ], 6925 "type": "integer" 6926 } 6927 }, 6928 "required": [ 6929 "url", 6930 "protocol" 6931 ], 6932 "type": "object" 6933 }, 6934 "minItems": 1, 6935 "readOnly": true, 6936 "type": "array" 6937 } 6938 }, 6939 "required": [ 6940 "urlInfo" 6941 ], 6942 "type": "object" 6943 } 6944 6945 } 6946 } 6947 6948
E.2.5 Property Definition 6949
Property name Value type Mandatory Access mode Description
if array: see schema
Read Only The interface set supported by this resource
id string Read Only Instance ID of this specific resource
urlInfo array: see schema
yes Read Only The valid range for the value Property
rt array: see schema
Read Only Resource Type
n string Read Only Friendly name of the resource
E.2.6 CRUDN behavior 6950
Resource Create Read Update Delete Notify
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 196
/IntrospectionResURI get
E.3 OCF Collection 6951
E.3.1 Introduction 6952
OCF Collection Resource Type contains properties and links. 6953
The oic.if.baseline interface exposes a representation of 6954
the links and the properties of the collection resource itself 6955
Retrieve on Baseline Interface 6956
6957
E.3.2 Example URI 6958
/CollectionBaselineInterfaceURI 6959
E.3.3 Resource Type 6960
The resource type (rt) is defined as: ['oic.wk.col']. 6961
E.3.4 Swagger2.0 Definition 6962
{ 6963 "swagger": "2.0", 6964 "info": { 6965 "title": "OCF Collection", 6966 "version": "1.0", 6967 "license": { 6968 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 6969 "x-description": "Redistribution and use in source and binary forms, with or without 6970 modification, are permitted provided that the following conditions are met:\n 1. 6971 Redistributions of source code must retain the above copyright notice, this list of conditions and 6972 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 6973 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 6974 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 6975 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 6976 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 6977 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 6978 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 6979 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 6980 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 6981 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 6982 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 6983 OF SUCH DAMAGE.\n" 6984 } 6985 }, 6986 "schemes": ["http"], 6987 "consumes": ["application/json"], 6988 "produces": ["application/json"], 6989 "paths": { 6990 "/CollectionBaselineInterfaceURI" : { 6991 "get": { 6992 "description": "OCF Collection Resource Type contains properties and links.\nThe 6993 oic.if.baseline interface exposes a representation of\nthe links and the properties of the 6994 collection resource itself\nRetrieve on Baseline Interface\n", 6995 "parameters": [ 6996 {"$ref": "#/parameters/interface-baseline"} 6997 ], 6998 "responses": { 6999 "200": { 7000 "description" : "", 7001 "x-example": 7002 { 7003 "rt": ["oic.wk.col"], 7004 "id": "unique_example_id", 7005 "rts": [ "oic.r.switch.binary", "oic.r.airflow" ], 7006 "links": [ 7007 { 7008 "href": "switch", 7009 "rt": ["oic.r.switch.binary"], 7010
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 197
"if": ["oic.if.a", "oic.if.baseline"], 7011 "eps": [ 7012 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 7013 {"ep": "coaps://[fe80::b1d6]:1122"}, 7014 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 7015 ] 7016 }, 7017 { 7018 "href": "airFlow", 7019 "rt": ["oic.r.airflow"], 7020 "if": ["oic.if.a", "oic.if.baseline"], 7021 "eps": [ 7022 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 7023 {"ep": "coaps://[fe80::b1d6]:1122"}, 7024 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 7025 ] 7026 } 7027 ] 7028 } 7029 , 7030 "schema": { "$ref": "#/definitions/sbaseline" } 7031 } 7032 } 7033 }, 7034 "post": { 7035 "description": "Update on Baseline Interface\n", 7036 "parameters": [ 7037 {"$ref": "#/parameters/interface-baseline"}, 7038 { 7039 "name": "body", 7040 "in": "body", 7041 "required": true, 7042 "schema": { "$ref": "#/definitions/sbaseline" } 7043 } 7044 ], 7045 "responses": { 7046 "200": { 7047 "description" : "", 7048 "schema": { "$ref": "#/definitions/sbaseline" } 7049 } 7050 } 7051 } 7052 }, 7053 "/CollectionBatchInterfaceURI" : { 7054 "get": { 7055 "description": "OCF Collection Resource Type contains properties and links.\nThe oic.if.b 7056 interfacce exposes a composite representation of the\nresources pointed to by the links\nRetrieve 7057 on Batch Interface\n", 7058 "parameters": [ 7059 {"$ref": "#/parameters/interface-b"} 7060 ], 7061 "responses": { 7062 "200": { 7063 "description" : "All targets returned OK status (HTTP 200 or CoAP 2.05 Content)", 7064 "x-example": 7065 [ 7066 { 7067 "href": "switch", 7068 "rep": 7069 { 7070 "value": true 7071 } 7072 }, 7073 { 7074 "href": "airFlow", 7075 "rep": 7076 { 7077 "direction": "floor", 7078 "speed": 3 7079 } 7080 } 7081
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 198
] 7082 , 7083 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 7084 }, 7085 "404": { 7086 "description" : "One or more targets did not return an OK status, return a 7087 representation containing returned properties from the targets that returned OK", 7088 "x-example": 7089 [ 7090 { 7091 "href": "switch", 7092 "rep": 7093 { 7094 "value": true 7095 } 7096 } 7097 ] 7098 , 7099 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 7100 } 7101 } 7102 }, 7103 "post": { 7104 "description": "Update on Batch Interface\n", 7105 "parameters": [ 7106 {"$ref": "#/parameters/interface-b"}, 7107 { 7108 "name": "body", 7109 "in": "body", 7110 "required": true, 7111 "schema": { "$ref": "#/definitions/sbatch-update" }, 7112 "x-example": 7113 [ 7114 { 7115 "href": "switch", 7116 "rep": 7117 { 7118 "value": true 7119 } 7120 }, 7121 { 7122 "href": "airFlow", 7123 "rep": 7124 { 7125 "direction": "floor", 7126 "speed": 3 7127 } 7128 } 7129 ] 7130 } 7131 ], 7132 "responses": { 7133 "200": { 7134 "description" : "all targets returned OK status (HTTP 200 or CoAP 2.04 Changed) 7135 return a representation of the current state of all targets", 7136 "x-example": 7137 [ 7138 { 7139 "href": "switch", 7140 "rep": 7141 { 7142 "value": true 7143 } 7144 }, 7145 { 7146 "href": "airFlow", 7147 "rep": 7148 { 7149 "direction": "demist", 7150 "speed": 5 7151 } 7152
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 199
} 7153 ] 7154 , 7155 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 7156 }, 7157 "403": { 7158 "description" : "one or more targets did not return OK status; return a retrieve 7159 representation of the current state of all targets in the batch", 7160 "x-example": 7161 [ 7162 { 7163 "href": "switch", 7164 "rep": 7165 { 7166 "value": true 7167 } 7168 }, 7169 { 7170 "href": "airFlow", 7171 "rep": 7172 { 7173 "direction": "floor", 7174 "speed": 3 7175 } 7176 } 7177 ] 7178 , 7179 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 7180 } 7181 } 7182 } 7183 }, 7184 "/CollectionLinkListInterfaceURI" : { 7185 "get": { 7186 "description": "OCF Collection Resource Type contains properties and links.\nThe oic.if.ll 7187 interface exposes a representation of the links\nRetrieve on Link List Interface\n", 7188 "parameters": [ 7189 {"$ref": "#/parameters/interface-ll"} 7190 ], 7191 "responses": { 7192 "200": { 7193 "description" : "", 7194 "x-example": 7195 [ 7196 { 7197 "href": "switch", 7198 "rt": ["oic.r.switch.binary"], 7199 "if": ["oic.if.a", "oic.if.baseline"], 7200 "eps": [ 7201 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 7202 {"ep": "coaps://[fe80::b1d6]:1122"}, 7203 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 7204 ] 7205 }, 7206 { 7207 "href": "airFlow", 7208 "rt": ["oic.r.airflow"], 7209 "if": ["oic.if.a", "oic.if.baseline"], 7210 "eps": [ 7211 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 7212 {"ep": "coaps://[fe80::b1d6]:1122"}, 7213 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 7214 ] 7215 } 7216 ] 7217 , 7218 "schema": { "$ref": "#/definitions/slinks" } 7219 } 7220 } 7221 } 7222 } 7223
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 200
}, 7224 "parameters": { 7225 "interface-ll" : { 7226 "in" : "query", 7227 "name" : "if", 7228 "type" : "string", 7229 "enum" : ["oic.if.ll"] 7230 }, 7231 "interface-b" : { 7232 "in" : "query", 7233 "name" : "if", 7234 "type" : "string", 7235 "enum" : ["oic.if.b"] 7236 }, 7237 "interface-baseline" : { 7238 "in" : "query", 7239 "name" : "if", 7240 "type" : "string", 7241 "enum" : ["oic.if.baseline"] 7242 }, 7243 "interface-all" : { 7244 "in" : "query", 7245 "name" : "if", 7246 "type" : "string", 7247 "enum" : ["oic.if.ll", "oic.if.baseline", "oic.if.b"] 7248 } 7249 }, 7250 "definitions": { 7251 "sbaseline" : 7252 { 7253 "description": "A set (array) of simple or individual OIC Links. In addition to properties 7254 required for an OIC Link, the identifier for that link in this set is also required", 7255 "items": { 7256 "properties": { 7257 "anchor": { 7258 "description": "This is used to override the context URI e.g. override the URI of the 7259 containing collection", 7260 "format": "uri", 7261 "maxLength": 256, 7262 "type": "string" 7263 }, 7264 "di": { 7265 "description": "Unique identifier for device (UUID)", 7266 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-7267 9]{12}$", 7268 "type": "string" 7269 }, 7270 "drel": { 7271 "description": "When specified this is the default relationship to use when an OIC 7272 Link does not specify an explicit relationship with *rel* parameter", 7273 "type": "string" 7274 }, 7275 "eps": { 7276 "description": "the Endpoint information of the target Resource", 7277 "items": { 7278 "properties": { 7279 "ep": { 7280 "description": "URI with Transport Protocol Suites + Endpoint Locator as 7281 specified in 10.2.1", 7282 "format": "uri", 7283 "type": "string" 7284 }, 7285 "pri": { 7286 "description": "The priority among multiple Endpoints as specified in 10.2.3", 7287 "minimum": 1, 7288 "type": "integer" 7289 } 7290 }, 7291 "type": "object" 7292 }, 7293 "type": "array" 7294
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 201
}, 7295 "href": { 7296 "description": "This is the target URI, it can be specified as a Relative Reference 7297 or fully-qualified URI. Relative Reference should be used along with the di parameter to make it 7298 unique.", 7299 "format": "uri", 7300 "maxLength": 256, 7301 "type": "string" 7302 }, 7303 "id": { 7304 "description": "Instance ID of this specific resource", 7305 "maxLength": 64, 7306 "readOnly": true, 7307 "type": "string" 7308 }, 7309 "if": { 7310 "description": "The interface set supported by this resource", 7311 "items": { 7312 "enum": [ 7313 "oic.if.baseline", 7314 "oic.if.ll", 7315 "oic.if.b", 7316 "oic.if.rw", 7317 "oic.if.r", 7318 "oic.if.a", 7319 "oic.if.s" 7320 ], 7321 "type": "string" 7322 }, 7323 "minItems": 1, 7324 "type": "array" 7325 }, 7326 "ins": { 7327 "description": "The instance identifier for this web link in an array of web links - 7328 used in collections", 7329 "oneOf": [ 7330 { 7331 "description": "An ordinal number that is not repeated - must be unique in the 7332 collection context", 7333 "type": "integer" 7334 }, 7335 { 7336 "description": "Any unique string including a URI", 7337 "format": "uri", 7338 "maxLength": 256, 7339 "type": "string" 7340 }, 7341 { 7342 "description": "Unique identifier (UUID)", 7343 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-7344 F0-9]{12}$", 7345 "type": "string" 7346 } 7347 ] 7348 }, 7349 "links": { 7350 "description": "All forms of links in a collection", 7351 "oneOf": [ 7352 { 7353 "description": "A set (array) of simple or individual OIC Links. In addition to 7354 properties required for an OIC Link, the identifier for that link in this set is also required", 7355 "items": { 7356 "properties": { 7357 "anchor": { 7358 "description": "This is used to override the context URI e.g. override the 7359 URI of the containing collection", 7360 "format": "uri", 7361 "maxLength": 256, 7362 "type": "string" 7363 }, 7364 "di": { 7365
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 202
"description": "Unique identifier for device (UUID)", 7366 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-7367 [a-fA-F0-9]{12}$", 7368 "type": "string" 7369 }, 7370 "eps": { 7371 "description": "the Endpoint information of the target Resource", 7372 "items": { 7373 "properties": { 7374 "ep": { 7375 "description": "URI with Transport Protocol Suites + Endpoint Locator 7376 as specified in 10.2.1", 7377 "format": "uri", 7378 "type": "string" 7379 }, 7380 "pri": { 7381 "description": "The priority among multiple Endpoints as specified in 7382 10.2.3", 7383 "minimum": 1, 7384 "type": "integer" 7385 } 7386 }, 7387 "type": "object" 7388 }, 7389 "type": "array" 7390 }, 7391 "href": { 7392 "description": "This is the target URI, it can be specified as a Relative 7393 Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to 7394 make it unique.", 7395 "format": "uri", 7396 "maxLength": 256, 7397 "type": "string" 7398 }, 7399 "if": { 7400 "description": "The interface set supported by this resource", 7401 "items": { 7402 "enum": [ 7403 "oic.if.baseline", 7404 "oic.if.ll", 7405 "oic.if.b", 7406 "oic.if.rw", 7407 "oic.if.r", 7408 "oic.if.a", 7409 "oic.if.s" 7410 ], 7411 "type": "string" 7412 }, 7413 "minItems": 1, 7414 "type": "array" 7415 }, 7416 "ins": { 7417 "description": "The instance identifier for this web link in an array of 7418 web links - used in collections", 7419 "oneOf": [ 7420 { 7421 "description": "An ordinal number that is not repeated - must be unique 7422 in the collection context", 7423 "type": "integer" 7424 }, 7425 { 7426 "description": "Any unique string including a URI", 7427 "format": "uri", 7428 "maxLength": 256, 7429 "type": "string" 7430 }, 7431 { 7432 "description": "Unique identifier (UUID)", 7433 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-7434 9]{4}-[a-fA-F0-9]{12}$", 7435 "type": "string" 7436
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 203
} 7437 ] 7438 }, 7439 "p": { 7440 "description": "Specifies the framework policies on the Resource referenced 7441 by the target URI", 7442 "properties": { 7443 "bm": { 7444 "description": "Specifies the framework policies on the Resource 7445 referenced by the target URI for e.g. observable and discoverable", 7446 "type": "integer" 7447 } 7448 }, 7449 "required": [ 7450 "bm" 7451 ], 7452 "type": "object" 7453 }, 7454 "rel": { 7455 "description": "The relation of the target URI referenced by the link to 7456 the context URI", 7457 "oneOf": [ 7458 { 7459 "default": [ 7460 "hosts" 7461 ], 7462 "items": { 7463 "maxLength": 64, 7464 "type": "string" 7465 }, 7466 "minItems": 1, 7467 "type": "array" 7468 }, 7469 { 7470 "default": "hosts", 7471 "maxLength": 64, 7472 "type": "string" 7473 } 7474 ] 7475 }, 7476 "rt": { 7477 "description": "Resource Type", 7478 "items": { 7479 "maxLength": 64, 7480 "type": "string" 7481 }, 7482 "minItems": 1, 7483 "type": "array" 7484 }, 7485 "title": { 7486 "description": "A title for the link relation. Can be used by the UI to 7487 provide a context", 7488 "maxLength": 64, 7489 "type": "string" 7490 }, 7491 "type": { 7492 "default": "application/cbor", 7493 "description": "A hint at the representation of the resource referenced by 7494 the target URI. This represents the media types that are used for both accepting and emitting", 7495 "items": { 7496 "maxLength": 64, 7497 "type": "string" 7498 }, 7499 "minItems": 1, 7500 "type": "array" 7501 } 7502 }, 7503 "required": [ 7504 "href", 7505 "rt", 7506 "if" 7507
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 204
], 7508 "type": "object" 7509 }, 7510 "type": "array" 7511 } 7512 ] 7513 }, 7514 "n": { 7515 "description": "Friendly name of the resource", 7516 "maxLength": 64, 7517 "readOnly": true, 7518 "type": "string" 7519 }, 7520 "p": { 7521 "description": "Specifies the framework policies on the Resource referenced by the 7522 target URI", 7523 "properties": { 7524 "bm": { 7525 "description": "Specifies the framework policies on the Resource referenced by 7526 the target URI for e.g. observable and discoverable", 7527 "type": "integer" 7528 } 7529 }, 7530 "required": [ 7531 "bm" 7532 ], 7533 "type": "object" 7534 }, 7535 "rel": { 7536 "description": "The relation of the target URI referenced by the link to the context 7537 URI", 7538 "oneOf": [ 7539 { 7540 "default": [ 7541 "hosts" 7542 ], 7543 "items": { 7544 "maxLength": 64, 7545 "type": "string" 7546 }, 7547 "minItems": 1, 7548 "type": "array" 7549 }, 7550 { 7551 "default": "hosts", 7552 "maxLength": 64, 7553 "type": "string" 7554 } 7555 ] 7556 }, 7557 "rt": { 7558 "description": "Resource Type", 7559 "items": { 7560 "maxLength": 64, 7561 "type": "string" 7562 }, 7563 "minItems": 1, 7564 "type": "array" 7565 }, 7566 "rts": { 7567 "description": "Defines the list of allowable resource types (for Target and anchors) 7568 in links included in the collection; new links being created can only be from this list", 7569 "items": { 7570 "maxLength": 64, 7571 "type": "string" 7572 }, 7573 "minItems": 1, 7574 "readOnly": true, 7575 "type": "array" 7576 }, 7577 "title": { 7578
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 205
"description": "A title for the link relation. Can be used by the UI to provide a 7579 context", 7580 "maxLength": 64, 7581 "type": "string" 7582 }, 7583 "type": { 7584 "default": "application/cbor", 7585 "description": "A hint at the representation of the resource referenced by the target 7586 URI. This represents the media types that are used for both accepting and emitting", 7587 "items": { 7588 "maxLength": 64, 7589 "type": "string" 7590 }, 7591 "minItems": 1, 7592 "type": "array" 7593 } 7594 }, 7595 "required": [ 7596 "href", 7597 "rt", 7598 "if" 7599 ], 7600 "type": "object" 7601 }, 7602 "type": "array" 7603 } 7604 7605 , 7606 "sbatch-retrieve" : 7607 { 7608 "items": { 7609 "additionalProperties": true, 7610 "properties": { 7611 "href": { 7612 "description": "URI of the target resource relative assuming the collection URI as 7613 anchor", 7614 "format": "uri", 7615 "maxLength": 256, 7616 "type": "string" 7617 }, 7618 "rep": { 7619 "oneOf": [ 7620 { 7621 "description": "The response payload from a single resource", 7622 "type": "object" 7623 }, 7624 { 7625 "description": " The response payload from a collection (batch) resource", 7626 "type": "array" 7627 } 7628 ] 7629 } 7630 }, 7631 "required": [ 7632 "href", 7633 "rep" 7634 ], 7635 "type": "object" 7636 }, 7637 "minItems": 1, 7638 "type": "array" 7639 } 7640 7641 , 7642 "sbatch-update" : 7643 { 7644 "description": "array of resource representations to apply to the batch collection, using 7645 href to indicate which resource(s) in the batch to update. If the href property is empty, 7646 effectively making the URI reference to the collection itself, the representation is to be applied 7647 to all resources in the batch", 7648 "items": { 7649
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 206
"additionalProperties": true, 7650 "properties": { 7651 "href": { 7652 "description": "URI of the target resource relative assuming the collection URI as 7653 anchor", 7654 "format": "uri", 7655 "maxLength": 256, 7656 "type": "string" 7657 }, 7658 "rep": { 7659 "oneOf": [ 7660 { 7661 "description": "The response payload from a single resource", 7662 "type": "object" 7663 }, 7664 { 7665 "description": " The response payload from a collection (batch) resource", 7666 "type": "array" 7667 } 7668 ] 7669 } 7670 }, 7671 "required": [ 7672 "href", 7673 "rep" 7674 ], 7675 "type": "object" 7676 }, 7677 "minItems": 1, 7678 "type": "array" 7679 } 7680 7681 , 7682 "slinks" : 7683 { 7684 "description": "All forms of links in a collection", 7685 "oneOf": [ 7686 { 7687 "description": "A set (array) of simple or individual OIC Links. In addition to 7688 properties required for an OIC Link, the identifier for that link in this set is also required", 7689 "items": { 7690 "properties": { 7691 "anchor": { 7692 "description": "This is used to override the context URI e.g. override the URI of 7693 the containing collection", 7694 "format": "uri", 7695 "maxLength": 256, 7696 "type": "string" 7697 }, 7698 "di": { 7699 "description": "Unique identifier for device (UUID)", 7700 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-7701 F0-9]{12}$", 7702 "type": "string" 7703 }, 7704 "eps": { 7705 "description": "the Endpoint information of the target Resource", 7706 "items": { 7707 "properties": { 7708 "ep": { 7709 "description": "URI with Transport Protocol Suites + Endpoint Locator as 7710 specified in 10.2.1", 7711 "format": "uri", 7712 "type": "string" 7713 }, 7714 "pri": { 7715 "description": "The priority among multiple Endpoints as specified in 7716 10.2.3", 7717 "minimum": 1, 7718 "type": "integer" 7719 } 7720
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 207
}, 7721 "type": "object" 7722 }, 7723 "type": "array" 7724 }, 7725 "href": { 7726 "description": "This is the target URI, it can be specified as a Relative 7727 Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to 7728 make it unique.", 7729 "format": "uri", 7730 "maxLength": 256, 7731 "type": "string" 7732 }, 7733 "if": { 7734 "description": "The interface set supported by this resource", 7735 "items": { 7736 "enum": [ 7737 "oic.if.baseline", 7738 "oic.if.ll", 7739 "oic.if.b", 7740 "oic.if.rw", 7741 "oic.if.r", 7742 "oic.if.a", 7743 "oic.if.s" 7744 ], 7745 "type": "string" 7746 }, 7747 "minItems": 1, 7748 "type": "array" 7749 }, 7750 "ins": { 7751 "description": "The instance identifier for this web link in an array of web 7752 links - used in collections", 7753 "oneOf": [ 7754 { 7755 "description": "An ordinal number that is not repeated - must be unique in 7756 the collection context", 7757 "type": "integer" 7758 }, 7759 { 7760 "description": "Any unique string including a URI", 7761 "format": "uri", 7762 "maxLength": 256, 7763 "type": "string" 7764 }, 7765 { 7766 "description": "Unique identifier (UUID)", 7767 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-7768 fA-F0-9]{12}$", 7769 "type": "string" 7770 } 7771 ] 7772 }, 7773 "p": { 7774 "description": "Specifies the framework policies on the Resource referenced by 7775 the target URI", 7776 "properties": { 7777 "bm": { 7778 "description": "Specifies the framework policies on the Resource referenced 7779 by the target URI for e.g. observable and discoverable", 7780 "type": "integer" 7781 } 7782 }, 7783 "required": [ 7784 "bm" 7785 ], 7786 "type": "object" 7787 }, 7788 "rel": { 7789 "description": "The relation of the target URI referenced by the link to the 7790 context URI", 7791
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 208
"oneOf": [ 7792 { 7793 "default": [ 7794 "hosts" 7795 ], 7796 "items": { 7797 "maxLength": 64, 7798 "type": "string" 7799 }, 7800 "minItems": 1, 7801 "type": "array" 7802 }, 7803 { 7804 "default": "hosts", 7805 "maxLength": 64, 7806 "type": "string" 7807 } 7808 ] 7809 }, 7810 "rt": { 7811 "description": "Resource Type", 7812 "items": { 7813 "maxLength": 64, 7814 "type": "string" 7815 }, 7816 "minItems": 1, 7817 "type": "array" 7818 }, 7819 "title": { 7820 "description": "A title for the link relation. Can be used by the UI to provide a 7821 context", 7822 "maxLength": 64, 7823 "type": "string" 7824 }, 7825 "type": { 7826 "default": "application/cbor", 7827 "description": "A hint at the representation of the resource referenced by the 7828 target URI. This represents the media types that are used for both accepting and emitting", 7829 "items": { 7830 "maxLength": 64, 7831 "type": "string" 7832 }, 7833 "minItems": 1, 7834 "type": "array" 7835 } 7836 }, 7837 "required": [ 7838 "href", 7839 "rt", 7840 "if" 7841 ], 7842 "type": "object" 7843 }, 7844 "type": "array" 7845 } 7846 ] 7847 } 7848 7849 } 7850 } 7851 7852
E.3.5 Property Definition 7853
Property name Value type Mandatory Access mode Description
links multiple types: see schema
All forms of links in a collection
anchor string This is used to override the context URI e.g.
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 209
override the URI of the containing collection
rel multiple types: see schema
The relation of the target URI referenced by the link to the context URI
type array: see schema
A hint at the representation of the resource referenced by the target URI. This represents the media types that are used for both accepting and emitting
if array: see schema
yes The interface set supported by this resource
href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to make it unique.
rt array: see schema
yes Resource Type
p object: see schema
Specifies the framework policies on the Resource referenced by the target URI
ins multiple types: see schema
The instance identifier for this web link in an array of web links - used in collections
n string Read Only Friendly name of the resource
rts array: see schema
Read Only Defines the list of allowable resource types (for Target and anchors) in links included in the
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 210
collection; new links being created can only be from this list
id string Read Only Instance ID of this specific resource
di string Unique identifier for device (UUID)
drel string When specified this is the default relationship to use when an OIC Link does not specify an explicit relationship with *rel* parameter
eps array: see schema
the Endpoint information of the target Resource
title string A title for the link relation. Can be used by the UI to provide a context
rep multiple types: see schema
yes
href string yes URI of the target resource relative assuming the collection URI as anchor
title string A title for the link relation. Can be used by the UI to provide a context
anchor string This is used to override the context URI e.g. override the URI of the containing collection
rel multiple types: see schema
The relation of the target URI referenced by the link to the context URI
type array: see schema
A hint at the representation of the resource referenced by the target URI. This represents the media types
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 211
that are used for both accepting and emitting
di string Unique identifier for device (UUID)
href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to make it unique.
rt array: see schema
yes Resource Type
p object: see schema
Specifies the framework policies on the Resource referenced by the target URI
ins multiple types: see schema
The instance identifier for this web link in an array of web links - used in collections
eps array: see schema
the Endpoint information of the target Resource
if array: see schema
yes The interface set supported by this resource
rep multiple types: see schema
yes
href string yes URI of the target resource relative assuming the collection URI as anchor
E.3.6 CRUDN behavior 7854
Resource Create Read Update Delete Notify
/CollectionBaselineInterfaceURI get post
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 212
E.4 Platform Configuration 7855
E.4.1 Introduction 7856
Resource that allows for platform specific information to be configured. 7857
Retrieves the current platform configuration settings 7858
7859
E.4.2 Example URI 7860
/example/PlatformConfigurationResURI 7861
E.4.3 Resource Type 7862
The resource type (rt) is defined as: ['oic.wk.con.p']. 7863
E.4.4 Swagger2.0 Definition 7864
{ 7865 "swagger": "2.0", 7866 "info": { 7867 "title": "Platform Configuration", 7868 "version": "v1-20160622", 7869 "license": { 7870 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 7871 "x-description": "Redistribution and use in source and binary forms, with or without 7872 modification, are permitted provided that the following conditions are met:\n 1. 7873 Redistributions of source code must retain the above copyright notice, this list of conditions and 7874 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 7875 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 7876 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 7877 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 7878 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 7879 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 7880 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 7881 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 7882 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 7883 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 7884 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 7885 OF SUCH DAMAGE.\n" 7886 } 7887 }, 7888 "schemes": ["http"], 7889 "consumes": ["application/json"], 7890 "produces": ["application/json"], 7891 "paths": { 7892 "/example/PlatformConfigurationResURI" : { 7893 "get": { 7894 "description": "Resource that allows for platform specific information to be 7895 configured.\nRetrieves the current platform configuration settings\n", 7896 "parameters": [ 7897 {"$ref": "#/parameters/interface-all"} 7898 ], 7899 "responses": { 7900 "200": { 7901 "description" : "", 7902 "x-example": 7903 { 7904 "rt": ["oic.wk.con.p"], 7905 "mnpn": [ { "language": "en", "value": "My Friendly Device Name" } ] 7906 } 7907 , 7908 "schema": { "$ref": "#/definitions/Conf_Platform" } 7909 } 7910 } 7911 }, 7912 "post": { 7913 "description": "Update the information about the platform\n", 7914 "parameters": [ 7915 {"$ref": "#/parameters/interface-rw"}, 7916 { 7917
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 213
"name": "body", 7918 "in": "body", 7919 "required": true, 7920 "schema": { "$ref": "#/definitions/Update_Platform" }, 7921 "x-example": 7922 { 7923 "n": "Nuevo nombre", 7924 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 7925 } 7926 } 7927 ], 7928 "responses": { 7929 "200": { 7930 "description" : "", 7931 "x-example": 7932 { 7933 "n": "Nuevo nombre", 7934 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 7935 } 7936 , 7937 "schema": { "$ref": "#/definitions/Update_Platform" } 7938 } 7939 } 7940 } 7941 } 7942 }, 7943 "parameters": { 7944 "interface-rw" : { 7945 "in" : "query", 7946 "name" : "if", 7947 "type" : "string", 7948 "enum" : ["oic.if.rw"] 7949 }, 7950 "interface-all" : { 7951 "in" : "query", 7952 "name" : "if", 7953 "type" : "string", 7954 "enum" : ["oic.if.rw", "oic.if.baseline"] 7955 } 7956 }, 7957 "definitions": { 7958 "Conf_Platform" : 7959 { 7960 "properties": { 7961 "id": { 7962 "description": "Instance ID of this specific resource", 7963 "maxLength": 64, 7964 "readOnly": true, 7965 "type": "string" 7966 }, 7967 "if": { 7968 "description": "The interface set supported by this resource", 7969 "items": { 7970 "enum": [ 7971 "oic.if.baseline", 7972 "oic.if.ll", 7973 "oic.if.b", 7974 "oic.if.lb", 7975 "oic.if.rw", 7976 "oic.if.r", 7977 "oic.if.a", 7978 "oic.if.s" 7979 ], 7980 "type": "string" 7981 }, 7982 "minItems": 1, 7983 "readOnly": true, 7984 "type": "array" 7985 }, 7986 "mnpn": { 7987 "description": "Platform names", 7988
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 214
"items": { 7989 "properties": { 7990 "language": { 7991 "description": "An RFC 5646 language tag.", 7992 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 7993 "type": "string" 7994 }, 7995 "value": { 7996 "description": "Platform description in the indicated language.", 7997 "maxLength": 64, 7998 "type": "string" 7999 } 8000 }, 8001 "type": "object" 8002 }, 8003 "minItems": 1, 8004 "type": "array" 8005 }, 8006 "n": { 8007 "description": "Friendly name of the resource", 8008 "maxLength": 64, 8009 "readOnly": true, 8010 "type": "string" 8011 }, 8012 "rt": { 8013 "description": "Resource Type", 8014 "items": { 8015 "maxLength": 64, 8016 "type": "string" 8017 }, 8018 "minItems": 1, 8019 "readOnly": true, 8020 "type": "array" 8021 } 8022 }, 8023 "type": "object" 8024 } 8025 8026 , 8027 "Update_Platform" : 8028 { 8029 "properties": { 8030 "id": { 8031 "description": "Instance ID of this specific resource", 8032 "maxLength": 64, 8033 "readOnly": true, 8034 "type": "string" 8035 }, 8036 "if": { 8037 "description": "The interface set supported by this resource", 8038 "items": { 8039 "enum": [ 8040 "oic.if.baseline", 8041 "oic.if.ll", 8042 "oic.if.b", 8043 "oic.if.lb", 8044 "oic.if.rw", 8045 "oic.if.r", 8046 "oic.if.a", 8047 "oic.if.s" 8048 ], 8049 "type": "string" 8050 }, 8051 "minItems": 1, 8052 "readOnly": true, 8053 "type": "array" 8054 }, 8055 "mnpn": { 8056 "description": "Platform names", 8057 "items": { 8058 "properties": { 8059
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 215
"language": { 8060 "description": "An RFC 5646 language tag.", 8061 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8062 "type": "string" 8063 }, 8064 "value": { 8065 "description": "Platform description in the indicated language.", 8066 "maxLength": 64, 8067 "type": "string" 8068 } 8069 }, 8070 "type": "object" 8071 }, 8072 "minItems": 1, 8073 "type": "array" 8074 }, 8075 "n": { 8076 "description": "Friendly name of the resource", 8077 "maxLength": 64, 8078 "type": "string" 8079 }, 8080 "rt": { 8081 "description": "Resource Type", 8082 "items": { 8083 "maxLength": 64, 8084 "type": "string" 8085 }, 8086 "minItems": 1, 8087 "readOnly": true, 8088 "type": "array" 8089 } 8090 }, 8091 "required": [ 8092 "mnpn" 8093 ], 8094 "type": "object" 8095 } 8096 8097 } 8098 } 8099 8100
E.4.5 Property Definition 8101
Property name Value type Mandatory Access mode Description
mnpn array: see schema
Platform names
if array: see schema
Read Only The interface set supported by this resource
rt array: see schema
Read Only Resource Type
id string Read Only Instance ID of this specific resource
n string Read Only Friendly name of the resource
mnpn array: see schema
yes Platform names
if array: see schema
Read Only The interface set supported by this resource
rt array: see schema
Read Only Resource Type
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 216
id string Read Only Instance ID of this specific resource
n string Friendly name of the resource
E.4.6 CRUDN behavior 8102
Resource Create Read Update Delete Notify
/example/PlatformConfigurationResURI get post
E.5 Device Configuration 8103
E.5.1 Introduction 8104
Resource that allows for Device specific information to be configured. 8105
Retrieves the current Device configuration settings 8106
8107
E.5.2 Example URI 8108
/example/DeviceConfigurationResURI 8109
E.5.3 Resource Type 8110
The resource type (rt) is defined as: ['oic.wk.con']. 8111
E.5.4 Swagger2.0 Definition 8112
{ 8113 "swagger": "2.0", 8114 "info": { 8115 "title": "Device Configuration", 8116 "version": "v1-20160622", 8117 "license": { 8118 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 8119 "x-description": "Redistribution and use in source and binary forms, with or without 8120 modification, are permitted provided that the following conditions are met:\n 1. 8121 Redistributions of source code must retain the above copyright notice, this list of conditions and 8122 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 8123 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 8124 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 8125 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 8126 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 8127 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 8128 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 8129 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 8130 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 8131 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 8132 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 8133 OF SUCH DAMAGE.\n" 8134 } 8135 }, 8136 "schemes": ["http"], 8137 "consumes": ["application/json"], 8138 "produces": ["application/json"], 8139 "paths": { 8140 "/example/DeviceConfigurationResURI" : { 8141 "get": { 8142 "description": "Resource that allows for Device specific information to be 8143 configured.\nRetrieves the current Device configuration settings\n", 8144 "parameters": [ 8145 {"$ref": "#/parameters/interface-all"} 8146 ], 8147 "responses": { 8148 "200": { 8149 "description" : "", 8150 "x-example": 8151 { 8152 "n": "My Friendly Device Name", 8153
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 217
"rt": ["oic.wk.con"], 8154 "loc": [32.777,-96.797], 8155 "locn": "My Location Name", 8156 "c": "USD", 8157 "r": "MyRegion", 8158 "dl": "en" 8159 } 8160 , 8161 "schema": { "$ref": "#/definitions/Configuration" } 8162 } 8163 } 8164 }, 8165 "post": { 8166 "description": "Update the information about the Device\n", 8167 "parameters": [ 8168 {"$ref": "#/parameters/interface-rw"}, 8169 { 8170 "name": "body", 8171 "in": "body", 8172 "required": true, 8173 "schema": { "$ref": "#/definitions/Update" }, 8174 "x-example": 8175 { 8176 "n": "Nuevo Nombre Amistoso", 8177 "r": "MyNewRegion", 8178 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 8179 "dl": "es" 8180 } 8181 } 8182 ], 8183 "responses": { 8184 "200": { 8185 "description" : "", 8186 "x-example": 8187 { 8188 "n": "Nuevo Nombre Amistoso", 8189 "r": "MyNewRegion", 8190 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 8191 "dl": "es" 8192 } 8193 , 8194 "schema": { "$ref": "#/definitions/Update" } 8195 } 8196 } 8197 } 8198 } 8199 }, 8200 "parameters": { 8201 "interface-rw" : { 8202 "in" : "query", 8203 "name" : "if", 8204 "type" : "string", 8205 "enum" : ["oic.if.rw"] 8206 }, 8207 "interface-all" : { 8208 "in" : "query", 8209 "name" : "if", 8210 "type" : "string", 8211 "enum" : ["oic.if.rw", "oic.if.baseline"] 8212 } 8213 }, 8214 "definitions": { 8215 "Configuration" : 8216 { 8217 "properties": { 8218 "c": { 8219 "description": "Currency", 8220 "maxLength": 64, 8221 "type": "string" 8222 }, 8223 "dl": { 8224
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 218
"description": "Default Language", 8225 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8226 "type": "string" 8227 }, 8228 "id": { 8229 "description": "Instance ID of this specific resource", 8230 "maxLength": 64, 8231 "readOnly": true, 8232 "type": "string" 8233 }, 8234 "if": { 8235 "description": "The interface set supported by this resource", 8236 "items": { 8237 "enum": [ 8238 "oic.if.baseline", 8239 "oic.if.ll", 8240 "oic.if.b", 8241 "oic.if.lb", 8242 "oic.if.rw", 8243 "oic.if.r", 8244 "oic.if.a", 8245 "oic.if.s" 8246 ], 8247 "type": "string" 8248 }, 8249 "minItems": 1, 8250 "readOnly": true, 8251 "type": "array" 8252 }, 8253 "ln": { 8254 "description": "Localized names", 8255 "items": { 8256 "properties": { 8257 "language": { 8258 "description": "An RFC 5646 language tag.", 8259 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8260 "type": "string" 8261 }, 8262 "value": { 8263 "description": "Device description in the indicated language.", 8264 "maxLength": 64, 8265 "type": "string" 8266 } 8267 }, 8268 "type": "object" 8269 }, 8270 "minItems": 1, 8271 "type": "array" 8272 }, 8273 "loc": { 8274 "description": "Location information", 8275 "items": { 8276 "type": "number" 8277 }, 8278 "maxItems": 2, 8279 "minItems": 2, 8280 "type": "array" 8281 }, 8282 "locn": { 8283 "description": "Human Friendly Name for location", 8284 "maxLength": 64, 8285 "type": "string" 8286 }, 8287 "n": { 8288 "description": "Friendly name of the resource", 8289 "maxLength": 64, 8290 "readOnly": true, 8291 "type": "string" 8292 }, 8293 "r": { 8294 "description": "Region", 8295
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 219
"maxLength": 64, 8296 "type": "string" 8297 }, 8298 "rt": { 8299 "description": "Resource Type", 8300 "items": { 8301 "maxLength": 64, 8302 "type": "string" 8303 }, 8304 "minItems": 1, 8305 "readOnly": true, 8306 "type": "array" 8307 } 8308 }, 8309 "required": [ 8310 "n" 8311 ], 8312 "type": "object" 8313 } 8314 8315 , 8316 "Update" : 8317 { 8318 "properties": { 8319 "c": { 8320 "description": "Currency", 8321 "maxLength": 64, 8322 "type": "string" 8323 }, 8324 "dl": { 8325 "description": "Default Language", 8326 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8327 "type": "string" 8328 }, 8329 "id": { 8330 "description": "Instance ID of this specific resource", 8331 "maxLength": 64, 8332 "readOnly": true, 8333 "type": "string" 8334 }, 8335 "if": { 8336 "description": "The interface set supported by this resource", 8337 "items": { 8338 "enum": [ 8339 "oic.if.baseline", 8340 "oic.if.ll", 8341 "oic.if.b", 8342 "oic.if.lb", 8343 "oic.if.rw", 8344 "oic.if.r", 8345 "oic.if.a", 8346 "oic.if.s" 8347 ], 8348 "type": "string" 8349 }, 8350 "minItems": 1, 8351 "readOnly": true, 8352 "type": "array" 8353 }, 8354 "ln": { 8355 "description": "Localized names", 8356 "items": { 8357 "properties": { 8358 "language": { 8359 "description": "An RFC 5646 language tag.", 8360 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8361 "type": "string" 8362 }, 8363 "value": { 8364 "description": "Device description in the indicated language.", 8365 "maxLength": 64, 8366
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 220
"type": "string" 8367 } 8368 }, 8369 "type": "object" 8370 }, 8371 "minItems": 1, 8372 "type": "array" 8373 }, 8374 "loc": { 8375 "description": "Location information", 8376 "items": { 8377 "type": "number" 8378 }, 8379 "maxItems": 2, 8380 "minItems": 2, 8381 "type": "array" 8382 }, 8383 "locn": { 8384 "description": "Human Friendly Name for location", 8385 "maxLength": 64, 8386 "type": "string" 8387 }, 8388 "n": { 8389 "description": "Friendly name of the resource", 8390 "maxLength": 64, 8391 "type": "string" 8392 }, 8393 "r": { 8394 "description": "Region", 8395 "maxLength": 64, 8396 "type": "string" 8397 }, 8398 "rt": { 8399 "description": "Resource Type", 8400 "items": { 8401 "maxLength": 64, 8402 "type": "string" 8403 }, 8404 "minItems": 1, 8405 "readOnly": true, 8406 "type": "array" 8407 } 8408 }, 8409 "required": [ 8410 "n" 8411 ], 8412 "type": "object" 8413 } 8414 8415 } 8416 } 8417 8418
E.5.5 Property Definition 8419
Property name Value type Mandatory Access mode Description
locn string Human Friendly Name for location
dl string Default Language
c string Currency
rt array: see schema
Read Only Resource Type
id string Read Only Instance ID of this specific resource
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 221
ln array: see schema
Localized names
n string yes Read Only Friendly name of the resource
loc array: see schema
Location information
r string Region
if array: see schema
Read Only The interface set supported by this resource
locn string Human Friendly Name for location
dl string Default Language
c string Currency
rt array: see schema
Read Only Resource Type
id string Read Only Instance ID of this specific resource
ln array: see schema
Localized names
n string yes Friendly name of the resource
loc array: see schema
Location information
r string Region
if array: see schema
Read Only The interface set supported by this resource
E.5.6 CRUDN behavior 8420
Resource Create Read Update Delete Notify
/example/DeviceConfigurationResURI get post
E.6 Device 8421
E.6.1 Introduction 8422
Known resource that is hosted by every Server. 8423
Allows for logical device specific information to be discovered. 8424
Retrieve the information about the Device 8425
8426
E.6.2 Wellknown URI 8427
/oic/d 8428
E.6.3 Resource Type 8429
The resource type (rt) is defined as: ['oic.wk.d']. 8430
E.6.4 Swagger2.0 Definition 8431
{ 8432 "swagger": "2.0", 8433 "info": { 8434 "title": "Device", 8435 "version": "v1-20160622", 8436 "license": { 8437
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 222
"name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 8438 "x-description": "Redistribution and use in source and binary forms, with or without 8439 modification, are permitted provided that the following conditions are met:\n 1. 8440 Redistributions of source code must retain the above copyright notice, this list of conditions and 8441 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 8442 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 8443 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 8444 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 8445 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 8446 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 8447 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 8448 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 8449 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 8450 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 8451 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 8452 OF SUCH DAMAGE.\n" 8453 } 8454 }, 8455 "schemes": ["http"], 8456 "consumes": ["application/json"], 8457 "produces": ["application/json"], 8458 "paths": { 8459 "/oic/d" : { 8460 "get": { 8461 "description": "Known resource that is hosted by every Server.\nAllows for logical device 8462 specific information to be discovered.\nRetrieve the information about the Device\n", 8463 "parameters": [ 8464 {"$ref": "#/parameters/interface"} 8465 ], 8466 "responses": { 8467 "200": { 8468 "description" : "", 8469 "x-example": 8470 { 8471 "n": "Device 1", 8472 "rt": ["oic.wk.d"], 8473 "di": "54919CA5-4101-4AE4-595B-353C51AA983C", 8474 "icv": "ocf.1.0.0", 8475 "dmv": "ocf.res.1.0.0, ocf.sh.1.0.0", 8476 "piid": "6F0AAC04-2BB0-468D-B57C-16570A26AE48" 8477 } 8478 , 8479 "schema": { "$ref": "#/definitions/Device" } 8480 } 8481 } 8482 } 8483 } 8484 }, 8485 "parameters": { 8486 "interface" : { 8487 "in" : "query", 8488 "name" : "if", 8489 "type" : "string", 8490 "enum" : ["oic.if.r", "oic.if.baseline"] 8491 } 8492 }, 8493 "definitions": { 8494 "Device" : 8495 { 8496 "properties": { 8497 "di": { 8498 "description": "Unique identifier for device (UUID)", 8499 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-8500 9]{12}$", 8501 "readOnly": true, 8502 "type": "string" 8503 }, 8504 "dmn": { 8505 "description": "Manufacturer Name.", 8506 "items": { 8507 "properties": { 8508
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 223
"language": { 8509 "description": "An RFC 5646 language tag.", 8510 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8511 "readOnly": true, 8512 "type": "string" 8513 }, 8514 "value": { 8515 "description": "Manufacturer name in the indicated language.", 8516 "maxLength": 64, 8517 "readOnly": true, 8518 "type": "string" 8519 } 8520 }, 8521 "type": "object" 8522 }, 8523 "minItems": 1, 8524 "readOnly": true, 8525 "type": "array" 8526 }, 8527 "dmno": { 8528 "description": "Model number as designated by manufacturer.", 8529 "maxLength": 64, 8530 "readOnly": true, 8531 "type": "string" 8532 }, 8533 "dmv": { 8534 "description": "Spec versions of the Resource and Device Specifications to which this 8535 device data model is implemented", 8536 "maxLength": 256, 8537 "readOnly": true, 8538 "type": "string" 8539 }, 8540 "icv": { 8541 "description": "The version of the OIC Server", 8542 "maxLength": 64, 8543 "readOnly": true, 8544 "type": "string" 8545 }, 8546 "id": { 8547 "description": "Instance ID of this specific resource", 8548 "maxLength": 64, 8549 "readOnly": true, 8550 "type": "string" 8551 }, 8552 "if": { 8553 "description": "The interface set supported by this resource", 8554 "items": { 8555 "enum": [ 8556 "oic.if.baseline", 8557 "oic.if.ll", 8558 "oic.if.b", 8559 "oic.if.lb", 8560 "oic.if.rw", 8561 "oic.if.r", 8562 "oic.if.a", 8563 "oic.if.s" 8564 ], 8565 "type": "string" 8566 }, 8567 "minItems": 1, 8568 "readOnly": true, 8569 "type": "array" 8570 }, 8571 "ld": { 8572 "description": "Localized Description.", 8573 "items": { 8574 "properties": { 8575 "language": { 8576 "description": "An RFC 5646 language tag.", 8577 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8578 "readOnly": true, 8579
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 224
"type": "string" 8580 }, 8581 "value": { 8582 "description": "Device description in the indicated language.", 8583 "maxLength": 64, 8584 "readOnly": true, 8585 "type": "string" 8586 } 8587 }, 8588 "type": "object" 8589 }, 8590 "minItems": 1, 8591 "readOnly": true, 8592 "type": "array" 8593 }, 8594 "n": { 8595 "description": "Friendly name of the resource", 8596 "maxLength": 64, 8597 "readOnly": true, 8598 "type": "string" 8599 }, 8600 "piid": { 8601 "description": "Protocol independent unique identifier for device (UUID) that is 8602 immutable.", 8603 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-8604 9]{12}$", 8605 "readOnly": true, 8606 "type": "string" 8607 }, 8608 "rt": { 8609 "description": "Resource Type", 8610 "items": { 8611 "maxLength": 64, 8612 "type": "string" 8613 }, 8614 "minItems": 1, 8615 "readOnly": true, 8616 "type": "array" 8617 }, 8618 "sv": { 8619 "description": "Software version.", 8620 "maxLength": 64, 8621 "readOnly": true, 8622 "type": "string" 8623 } 8624 }, 8625 "required": [ 8626 "n", 8627 "di", 8628 "icv", 8629 "dmv", 8630 "piid" 8631 ], 8632 "type": "object" 8633 } 8634 8635 } 8636 } 8637 8638
E.6.5 Property Definition 8639
Property name Value type Mandatory Access mode Description
dmn array: see schema
Read Only Manufacturer Name.
id string Read Only Instance ID of this specific resource
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 225
if array: see schema
Read Only The interface set supported by this resource
piid string yes Read Only Protocol independent unique identifier for device (UUID) that is immutable.
ld array: see schema
Read Only Localized Description.
dmno string Read Only Model number as designated by manufacturer.
sv string Read Only Software version.
rt array: see schema
Read Only Resource Type
dmv string yes Read Only Spec versions of the Resource and Device Specifications to which this device data model is implemented
icv string yes Read Only The version of the OIC Server
di string yes Read Only Unique identifier for device (UUID)
n string yes Read Only Friendly name of the resource
E.6.6 CRUDN behavior 8640
Resource Create Read Update Delete Notify
/oic/d get
E.7 Maintenance 8641
E.7.1 Introduction 8642
The resource through which a Device is maintained and can be used for diagnostic purposes. 8643
fr (Factory Reset) is a boolean. 8644
The value 0 means No action (Default), the value 1 means Start Factory Reset 8645
After factory reset, this value shall be changed back to the default value 8646
rb (Reboot) is a boolean. 8647
The value 0 means No action (Default), the value 1 means Start Reboot 8648
After Reboot, this value shall be changed back to the default value 8649
Retrieve the maintenance action status 8650
E.7.2 Wellknown URI 8651
/oic/mnt 8652
E.7.3 Resource Type 8653
The resource type (rt) is defined as: ['oic.wk.mnt']. 8654
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 226
E.7.4 Swagger2.0 Definition 8655
{ 8656 "swagger": "2.0", 8657 "info": { 8658 "title": "Maintenance", 8659 "version": "v1-20160622", 8660 "license": { 8661 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 8662 "x-description": "Redistribution and use in source and binary forms, with or without 8663 modification, are permitted provided that the following conditions are met:\n 1. 8664 Redistributions of source code must retain the above copyright notice, this list of conditions and 8665 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 8666 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 8667 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 8668 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 8669 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 8670 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 8671 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 8672 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 8673 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 8674 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 8675 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 8676 OF SUCH DAMAGE.\n" 8677 } 8678 }, 8679 "schemes": ["http"], 8680 "consumes": ["application/json"], 8681 "produces": ["application/json"], 8682 "paths": { 8683 "/oic/mnt" : { 8684 "get": { 8685 "description": "The resource through which a Device is maintained and can be used for 8686 diagnostic purposes.\nfr (Factory Reset) is a boolean.\n The value 0 means No action (Default), 8687 the value 1 means Start Factory Reset\nAfter factory reset, this value shall be changed back to the 8688 default value\nrb (Reboot) is a boolean.\n The value 0 means No action (Default), the value 1 8689 means Start Reboot\nAfter Reboot, this value shall be changed back to the default value\nRetrieve 8690 the maintenance action status", 8691 "parameters": [ 8692 {"$ref": "#/parameters/interface-all"} 8693 ], 8694 "responses": { 8695 "200": { 8696 "description" : "", 8697 "x-example": 8698 { 8699 "rt": ["oic.wk.mnt"], 8700 "fr": false, 8701 "rb": false 8702 } 8703 , 8704 "schema": { "$ref": "#/definitions/MNT" } 8705 } 8706 } 8707 }, 8708 "post": { 8709 "description": "Set the maintenance action(s)\n", 8710 "parameters": [ 8711 {"$ref": "#/parameters/interface-rw"}, 8712 { 8713 "name": "body", 8714 "in": "body", 8715 "required": true, 8716 "schema": { "$ref": "#/definitions/MNT" }, 8717 "x-example": 8718 { 8719 "fr": false, 8720 "rb": false 8721 } 8722 } 8723 ], 8724
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 227
"responses": { 8725 "200": { 8726 "description" : "", 8727 "x-example": 8728 { 8729 "fr": false, 8730 "rb": false 8731 } 8732 , 8733 "schema": { "$ref": "#/definitions/MNT" } 8734 } 8735 } 8736 } 8737 } 8738 }, 8739 "parameters": { 8740 "interface-rw" : { 8741 "in" : "query", 8742 "name" : "if", 8743 "type" : "string", 8744 "enum" : ["oic.if.rw", "oic.if.baseline"] 8745 }, 8746 "interface-all" : { 8747 "in" : "query", 8748 "name" : "if", 8749 "type" : "string", 8750 "enum" : ["oic.if.rw", "oic.if.r", "oic.if.baseline"] 8751 } 8752 }, 8753 "definitions": { 8754 "MNT" : 8755 { 8756 "anyOf": [ 8757 { 8758 "required": [ 8759 "fr" 8760 ] 8761 }, 8762 { 8763 "required": [ 8764 "rb" 8765 ] 8766 } 8767 ], 8768 "properties": { 8769 "fr": { 8770 "description": "Factory Reset", 8771 "type": "boolean" 8772 }, 8773 "id": { 8774 "description": "Instance ID of this specific resource", 8775 "maxLength": 64, 8776 "readOnly": true, 8777 "type": "string" 8778 }, 8779 "if": { 8780 "description": "The interface set supported by this resource", 8781 "items": { 8782 "enum": [ 8783 "oic.if.baseline", 8784 "oic.if.ll", 8785 "oic.if.b", 8786 "oic.if.lb", 8787 "oic.if.rw", 8788 "oic.if.r", 8789 "oic.if.a", 8790 "oic.if.s" 8791 ], 8792 "type": "string" 8793 }, 8794 "minItems": 1, 8795
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 228
"readOnly": true, 8796 "type": "array" 8797 }, 8798 "n": { 8799 "description": "Friendly name of the resource", 8800 "maxLength": 64, 8801 "readOnly": true, 8802 "type": "string" 8803 }, 8804 "rb": { 8805 "description": "Reboot Action", 8806 "type": "boolean" 8807 }, 8808 "rt": { 8809 "description": "Resource Type", 8810 "items": { 8811 "maxLength": 64, 8812 "type": "string" 8813 }, 8814 "minItems": 1, 8815 "readOnly": true, 8816 "type": "array" 8817 } 8818 }, 8819 "type": "object" 8820 } 8821 8822 } 8823 } 8824 8825
E.7.5 Property Definition 8826
Property name Value type Mandatory Access mode Description
id string Read Only Instance ID of this specific resource
n string Read Only Friendly name of the resource
rb boolean yes Reboot Action
rt array: see schema
Read Only Resource Type
if array: see schema
Read Only The interface set supported by this resource
fr boolean Factory Reset
E.7.6 CRUDN behavior 8827
Resource Create Read Update Delete Notify
/oic/mnt get post
E.8 Platform 8828
E.8.1 Introduction 8829
Known resource that is defines the platform on which an Server is hosted. 8830
Allows for platform specific information to be discovered. 8831
Retrieve the information about the Platform 8832
8833
E.8.2 Wellknown URI 8834
/oic/p 8835
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 229
E.8.3 Resource Type 8836
The resource type (rt) is defined as: ['oic.wk.p']. 8837
E.8.4 Swagger2.0 Definition 8838
{ 8839 "swagger": "2.0", 8840 "info": { 8841 "title": "Platform", 8842 "version": "v1-20160622", 8843 "license": { 8844 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 8845 "x-description": "Redistribution and use in source and binary forms, with or without 8846 modification, are permitted provided that the following conditions are met:\n 1. 8847 Redistributions of source code must retain the above copyright notice, this list of conditions and 8848 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 8849 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 8850 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 8851 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 8852 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 8853 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 8854 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 8855 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 8856 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 8857 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 8858 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 8859 OF SUCH DAMAGE.\n" 8860 } 8861 }, 8862 "schemes": ["http"], 8863 "consumes": ["application/json"], 8864 "produces": ["application/json"], 8865 "paths": { 8866 "/oic/p" : { 8867 "get": { 8868 "description": "Known resource that is defines the platform on which an Server is 8869 hosted.\nAllows for platform specific information to be discovered.\nRetrieve the information about 8870 the Platform\n", 8871 "parameters": [ 8872 {"$ref": "#/parameters/interface"} 8873 ], 8874 "responses": { 8875 "200": { 8876 "description" : "", 8877 "x-example": 8878 { 8879 "pi": "54919CA5-4101-4AE4-595B-353C51AA983C", 8880 "rt": ["oic.wk.p"], 8881 "mnmn": "Acme, Inc" 8882 } 8883 , 8884 "schema": { "$ref": "#/definitions/Platform" } 8885 } 8886 } 8887 } 8888 } 8889 }, 8890 "parameters": { 8891 "interface" : { 8892 "in" : "query", 8893 "name" : "if", 8894 "type" : "string", 8895 "enum" : ["oic.if.r", "oic.if.baseline"] 8896 } 8897 }, 8898 "definitions": { 8899 "Platform" : 8900 { 8901 "properties": { 8902 "id": { 8903 "description": "Instance ID of this specific resource", 8904
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 230
"maxLength": 64, 8905 "readOnly": true, 8906 "type": "string" 8907 }, 8908 "if": { 8909 "description": "The interface set supported by this resource", 8910 "items": { 8911 "enum": [ 8912 "oic.if.baseline", 8913 "oic.if.ll", 8914 "oic.if.b", 8915 "oic.if.lb", 8916 "oic.if.rw", 8917 "oic.if.r", 8918 "oic.if.a", 8919 "oic.if.s" 8920 ], 8921 "type": "string" 8922 }, 8923 "minItems": 1, 8924 "readOnly": true, 8925 "type": "array" 8926 }, 8927 "mndt": { 8928 "description": "Manufacturing Date.", 8929 "pattern": "^([0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|2[0-9]|1[0-9]|0[1-9])$", 8930 "readOnly": true, 8931 "type": "string" 8932 }, 8933 "mnfv": { 8934 "description": "Manufacturer's firmware version", 8935 "maxLength": 64, 8936 "readOnly": true, 8937 "type": "string" 8938 }, 8939 "mnhw": { 8940 "description": "Platform Hardware Version", 8941 "maxLength": 64, 8942 "readOnly": true, 8943 "type": "string" 8944 }, 8945 "mnml": { 8946 "description": "Manufacturer's URL", 8947 "format": "uri", 8948 "maxLength": 256, 8949 "readOnly": true, 8950 "type": "string" 8951 }, 8952 "mnmn": { 8953 "description": "Manufacturer Name", 8954 "maxLength": 64, 8955 "readOnly": true, 8956 "type": "string" 8957 }, 8958 "mnmo": { 8959 "description": "Model number as designated by manufacturer", 8960 "maxLength": 64, 8961 "readOnly": true, 8962 "type": "string" 8963 }, 8964 "mnos": { 8965 "description": "Platform Resident OS Version", 8966 "maxLength": 64, 8967 "readOnly": true, 8968 "type": "string" 8969 }, 8970 "mnpv": { 8971 "description": "Platform Version", 8972 "maxLength": 64, 8973 "readOnly": true, 8974 "type": "string" 8975
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 231
}, 8976 "mnsl": { 8977 "description": "Manufacturer's Support Information URL", 8978 "format": "uri", 8979 "maxLength": 256, 8980 "readOnly": true, 8981 "type": "string" 8982 }, 8983 "n": { 8984 "description": "Friendly name of the resource", 8985 "maxLength": 64, 8986 "readOnly": true, 8987 "type": "string" 8988 }, 8989 "pi": { 8990 "description": "Platform Identifier as a UUID", 8991 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-8992 9]{12}$", 8993 "readOnly": true, 8994 "type": "string" 8995 }, 8996 "rt": { 8997 "description": "Resource Type", 8998 "items": { 8999 "maxLength": 64, 9000 "type": "string" 9001 }, 9002 "minItems": 1, 9003 "readOnly": true, 9004 "type": "array" 9005 }, 9006 "st": { 9007 "description": "Reference time for the device as defined in ISO 8601, where 9008 concatenation of 'date' and 'time' with the 'T' as a delimiter between 'date' and 'time'.", 9009 "format": "date-time", 9010 "readOnly": true, 9011 "type": "string" 9012 }, 9013 "vid": { 9014 "description": "Manufacturer's defined string for the platform. The string is freeform 9015 and up to the manufacturer on what text to populate it", 9016 "maxLength": 64, 9017 "readOnly": true, 9018 "type": "string" 9019 } 9020 }, 9021 "required": [ 9022 "pi", 9023 "mnmn" 9024 ], 9025 "type": "object" 9026 } 9027 9028 } 9029 } 9030 9031
E.8.5 Property Definition 9032
Property name Value type Mandatory Access mode Description
n string Read Only Friendly name of the resource
if array: see schema
Read Only The interface set supported by this resource
mnmo string Read Only Model number as designated by manufacturer
mnpv string Read Only Platform Version
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 232
mnos string Read Only Platform Resident OS Version
pi string yes Read Only Platform Identifier as a UUID
mndt string Read Only Manufacturing Date.
mnfv string Read Only Manufacturer's firmware version
mnml string Read Only Manufacturer's URL
st string Read Only Reference time for the device as defined in ISO 8601, where concatenation of 'date' and 'time' with the 'T' as a delimiter between 'date' and 'time'.
rt array: see schema
Read Only Resource Type
mnsl string Read Only Manufacturer's Support Information URL
mnmn string yes Read Only Manufacturer Name
mnhw string Read Only Platform Hardware Version
vid string Read Only Manufacturer's defined string for the platform. The string is freeform and up to the manufacturer on what text to populate it
id string Read Only Instance ID of this specific resource
E.8.6 CRUDN behavior 9033
Resource Create Read Update Delete Notify
/oic/p get
E.9 Ping 9034
E.9.1 Introduction 9035
The resource using which an Client keeps its Connection with an Server active. 9036
Retrieve the ping information 9037
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 233
E.9.2 Wellknown URI 9038
/oic/ping 9039
E.9.3 Resource Type 9040
The resource type (rt) is defined as: ['oic.wk.ping']. 9041
E.9.4 Swagger2.0 Definition 9042
{ 9043 "swagger": "2.0", 9044 "info": { 9045 "title": "Ping", 9046 "version": "v1-20160622", 9047 "license": { 9048 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 9049 "x-description": "Redistribution and use in source and binary forms, with or without 9050 modification, are permitted provided that the following conditions are met:\n 1. 9051 Redistributions of source code must retain the above copyright notice, this list of conditions and 9052 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 9053 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 9054 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 9055 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 9056 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 9057 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 9058 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 9059 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 9060 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 9061 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 9062 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 9063 OF SUCH DAMAGE.\n" 9064 } 9065 }, 9066 "schemes": ["http"], 9067 "consumes": ["application/json"], 9068 "produces": ["application/json"], 9069 "paths": { 9070 "/oic/ping" : { 9071 "get": { 9072 "description": "The resource using which an Client keeps its Connection with an Server 9073 active.\nRetrieve the ping information", 9074 "parameters": [ 9075 {"$ref": "#/parameters/interface"} 9076 ], 9077 "responses": { 9078 "200": { 9079 "description" : "", 9080 "x-example": 9081 { 9082 "rt": ["oic.wk.ping"], 9083 "n": "Ping Information", 9084 "in": 16 9085 } 9086 , 9087 "schema": { "$ref": "#/definitions/PING" } 9088 } 9089 } 9090 }, 9091 "post": { 9092 "description": "Update or reset the alive interval", 9093 "parameters": [ 9094 {"$ref": "#/parameters/interface"}, 9095 { 9096 "name": "body", 9097 "in": "body", 9098 "required": true, 9099 "schema": { "$ref": "#/definitions/PING" }, 9100 "x-example": 9101 { 9102 "in": 16 9103 } 9104
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 234
} 9105 ], 9106 "responses": { 9107 "203": { 9108 "description" : "Successfully updated & restarted alive interval timer.", 9109 "x-example": 9110 { 9111 "in": 16 9112 } 9113 , 9114 "schema": { "$ref": "#/definitions/PING" } 9115 } 9116 } 9117 } 9118 } 9119 }, 9120 "parameters": { 9121 "interface" : { 9122 "in" : "query", 9123 "name" : "if", 9124 "type" : "string", 9125 "enum" : ["oic.if.rw", "oic.if.baseline"] 9126 } 9127 }, 9128 "definitions": { 9129 "PING" : 9130 { 9131 "properties": { 9132 "id": { 9133 "description": "Instance ID of this specific resource", 9134 "maxLength": 64, 9135 "readOnly": true, 9136 "type": "string" 9137 }, 9138 "if": { 9139 "description": "The interface set supported by this resource", 9140 "items": { 9141 "enum": [ 9142 "oic.if.baseline", 9143 "oic.if.ll", 9144 "oic.if.b", 9145 "oic.if.lb", 9146 "oic.if.rw", 9147 "oic.if.r", 9148 "oic.if.a", 9149 "oic.if.s" 9150 ], 9151 "type": "string" 9152 }, 9153 "minItems": 1, 9154 "readOnly": true, 9155 "type": "array" 9156 }, 9157 "in": { 9158 "description": "Indicates the interval for which connection shall be kept alive", 9159 "readOnly": false, 9160 "type": "integer" 9161 }, 9162 "n": { 9163 "description": "Friendly name of the resource", 9164 "maxLength": 64, 9165 "readOnly": true, 9166 "type": "string" 9167 }, 9168 "rt": { 9169 "description": "Resource Type", 9170 "items": { 9171 "maxLength": 64, 9172 "type": "string" 9173 }, 9174 "minItems": 1, 9175
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 235
"readOnly": true, 9176 "type": "array" 9177 } 9178 }, 9179 "required": [ 9180 "in" 9181 ], 9182 "type": "object" 9183 } 9184 9185 } 9186 } 9187 9188
E.9.5 Property Definition 9189
Property name Value type Mandatory Access mode Description
if array: see schema
Read Only The interface set supported by this resource
rt array: see schema
Read Only Resource Type
id string Read Only Instance ID of this specific resource
in integer yes Read Write Indicates the interval for which connection shall be kept alive
n string Read Only Friendly name of the resource
E.9.6 CRUDN behavior 9190
Resource Create Read Update Delete Notify
/oic/ping get post
E.10 Resource directory resource 9191
E.10.1 Introduction 9192
Resource to be exposed by any Device that can act as a Resource Directory. 9193
1) Provides selector criteria (e.g., integer) with GET request 9194
2) Publish or Update a Link in /oic/res with POST request 9195
3) Delete a Link in /oic/res with DELETE request 9196
Get the attributes of the Resource Directory for selection purposes. 9197
9198
E.10.2 Wellknown URI 9199
/oic/rd 9200
E.10.3 Resource Type 9201
The resource type (rt) is defined as: ['oic.wk.rd']. 9202
E.10.4 Swagger2.0 Definition 9203
{ 9204 "swagger": "2.0", 9205 "info": { 9206 "title": "Resource directory resource", 9207 "version": "v1-20160622", 9208 "license": { 9209 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 9210 "x-description": "Redistribution and use in source and binary forms, with or without 9211
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 236
modification, are permitted provided that the following conditions are met:\n 1. 9212 Redistributions of source code must retain the above copyright notice, this list of conditions and 9213 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 9214 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 9215 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 9216 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 9217 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 9218 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 9219 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 9220 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 9221 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 9222 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 9223 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 9224 OF SUCH DAMAGE.\n" 9225 } 9226 }, 9227 "schemes": ["http"], 9228 "consumes": ["application/json"], 9229 "produces": ["application/json"], 9230 "paths": { 9231 "/oic/rd" : { 9232 "get": { 9233 "description": "Resource to be exposed by any Device that can act as a Resource 9234 Directory.\n1) Provides selector criteria (e.g., integer) with GET request\n2) Publish or Update a 9235 Link in /oic/res with POST request\n3) Delete a Link in /oic/res with DELETE request\nGet the 9236 attributes of the Resource Directory for selection purposes.\n", 9237 "parameters": [ 9238 {"$ref": "#/parameters/rdgetinterface"} 9239 ], 9240 "responses": { 9241 "200": { 9242 "description" : "Respond with the selector criteria - either the set of attributes or 9243 the bias factor\n", 9244 "x-example": 9245 { 9246 "rt": ["oic.wk.rd"], 9247 "if": ["oic.if.baseline"], 9248 "sel": 50 9249 } 9250 , 9251 "schema": { "$ref": "#/definitions/rdSelection" } 9252 } 9253 } 9254 }, 9255 "post": { 9256 "description": "Publish the resource information for the first time or Update the existing 9257 one in /oic/res.\nAppropriates parts of the information, i.e., Links of the published Resources 9258 will be discovered through /oic/res.\n1) When a Device first publishes a Link, the request payload 9259 to RD may include the Links without \"ins\" Parameter.\n2) Upon granting the request, the RD 9260 assigns a unique instance value identifying the Link among all the Links it advertises\n and 9261 sends back the instance value in \"ins\" Parameter in the Link to the publishing Device.\n3) When 9262 later the publishing Device updates the existing Link, i.e., changing its Endpoint information,\n 9263 the request payload to RD needs to include the instance value in \"ins\" Parameter to identify the 9264 Link to update.\n", 9265 "parameters": [ 9266 {"$ref": "#/parameters/rdpostinterface"}, 9267 { 9268 "name": "body", 9269 "in": "body", 9270 "required": true, 9271 "schema": { "$ref": "#/definitions/rdPublish" }, 9272 "x-example": 9273 { 9274 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 9275 "links": [ 9276 { 9277 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 9278 "href": "/myLightSwitch", 9279 "rt": ["oic.r.switch.binary"], 9280 "if": ["oic.if.a", "oic.if.baseline"], 9281 "p": {"bm": 3}, 9282
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 237
"eps": [ 9283 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 9284 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 9285 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 9286 ] 9287 }, 9288 { 9289 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 9290 "href": "/myLightBrightness", 9291 "rt": ["oic.r.brightness"], 9292 "if": ["oic.if.a", "oic.if.baseline"], 9293 "p": {"bm": 3}, 9294 "eps": [ 9295 {"ep": "coaps://[[2001:db8:a::123]:2222"} 9296 ] 9297 } 9298 ], 9299 "ttl": 600 9300 } 9301 } 9302 ], 9303 "responses": { 9304 "200": { 9305 "description" : "Respond with the same schema as publish but, when a Link is first 9306 published,\nwith the additional \"ins\" Parameter in the Link.\nThis value is used by the receiver 9307 to manage that OCF Link instance.\n", 9308 "x-example": 9309 { 9310 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 9311 "links": [ 9312 { 9313 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 9314 "href": "/myLightSwitch", 9315 "rt": ["oic.r.switch.binary"], 9316 "if": ["oic.if.a", "oic.if.baseline"], 9317 "p": {"bm": 3}, 9318 "eps": [ 9319 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 9320 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 9321 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 9322 ], 9323 "ins": "11235" 9324 }, 9325 { 9326 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 9327 "href": "/myLightBrightness", 9328 "rt": ["oic.r.brightness"], 9329 "if": ["oic.if.a", "oic.if.baseline"], 9330 "p": {"bm": 3}, 9331 "eps": [ 9332 {"ep": "coaps://[2001:db8:a::123]:2222"} 9333 ], 9334 "ins": "112358" 9335 } 9336 ], 9337 "ttl": 600 9338 } 9339 , 9340 "schema": { "$ref": "#/definitions/rdPublish" } 9341 } 9342 } 9343 }, 9344 "delete": { 9345 "description": "Delete a particular OIC Link - the link may be a simple link or a link in a 9346 tagged set.\n", 9347 "parameters": [ 9348 {"$ref": "#/parameters/rddelete-di"}, 9349 {"$ref": "#/parameters/rddelete-ins"} 9350 ], 9351 "responses": { 9352 "200": { 9353
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 238
"description" : "The delete succeeded", 9354 "x-example": 9355 {} 9356 } 9357 } 9358 } 9359 } 9360 }, 9361 "parameters": { 9362 "rddelete-di" : { 9363 "in" : "query", 9364 "name" : "di", 9365 "type" : "string", 9366 "description" : "description" 9367 }, 9368 "rddelete-ins" : { 9369 "in" : "query", 9370 "name" : "ins", 9371 "type" : "string", 9372 "description" : "description" 9373 }, 9374 "rdgetinterface" : { 9375 "in" : "query", 9376 "name" : "if", 9377 "type" : "string", 9378 "enum" : ["oic.if.baseline"], 9379 "description" : "enumdescription" 9380 }, 9381 "rdpostinterface" : { 9382 "in" : "query", 9383 "name" : "rt", 9384 "type" : "string", 9385 "enum" : ["oic.wk.rdpub"], 9386 "description" : "enumdescription" 9387 } 9388 }, 9389 "definitions": { 9390 "rdSelection" : 9391 { 9392 "oneOf": [ 9393 { 9394 "properties": { 9395 "sel": { 9396 "description": "A bias factor calculated by the Resource directory - the value is 9397 in the range of 0 to 100 - 0 implies that RD is not to be selected. Client chooses RD with highest 9398 bias factor or randomly between RDs that have same bias factor", 9399 "maximum": 100, 9400 "minimum": 0, 9401 "type": "integer" 9402 } 9403 }, 9404 "required": [ 9405 "sel" 9406 ] 9407 }, 9408 { 9409 "properties": { 9410 "id": { 9411 "description": "Instance ID of this specific resource", 9412 "maxLength": 64, 9413 "readOnly": true, 9414 "type": "string" 9415 }, 9416 "if": { 9417 "description": "The interface set supported by this resource", 9418 "items": { 9419 "enum": [ 9420 "oic.if.baseline", 9421 "oic.if.ll", 9422 "oic.if.b", 9423 "oic.if.lb", 9424
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 239
"oic.if.rw", 9425 "oic.if.r", 9426 "oic.if.a", 9427 "oic.if.s" 9428 ], 9429 "type": "string" 9430 }, 9431 "minItems": 1, 9432 "readOnly": true, 9433 "type": "array" 9434 }, 9435 "n": { 9436 "description": "Friendly name of the resource", 9437 "maxLength": 64, 9438 "readOnly": true, 9439 "type": "string" 9440 }, 9441 "rt": { 9442 "description": "Resource Type", 9443 "items": { 9444 "maxLength": 64, 9445 "type": "string" 9446 }, 9447 "minItems": 1, 9448 "readOnly": true, 9449 "type": "array" 9450 }, 9451 "sel": { 9452 "description": "Selection criteria that a device wanting to publish to any RD can 9453 use to choose this Resource Directory over others that are discovered", 9454 "properties": { 9455 "bw": { 9456 "description": "Qualitative bandwidth of the connection", 9457 "enum": [ 9458 "high", 9459 "low", 9460 "lossy" 9461 ], 9462 "type": "string" 9463 }, 9464 "conn": { 9465 "description": "A hint about the networking connectivity of the RD. *wrd* if 9466 wired connected and *wrls* if wireless connected.", 9467 "enum": [ 9468 "wrd", 9469 "wrls" 9470 ], 9471 "type": "string" 9472 }, 9473 "load": { 9474 "description": "Current load capacity of the RD. Expressed as a load factor 3-9475 tuple (upto two decimal points each). Load factor is based on request processed in a 1 minute, 5 9476 minute window and 15 minute window", 9477 "items": { 9478 "type": "number" 9479 }, 9480 "maxItems": 3, 9481 "minItems": 3, 9482 "type": "array" 9483 }, 9484 "mf": { 9485 "description": "Memory factor - Ratio of available memory to total memory 9486 expressed as a percentage", 9487 "type": "integer" 9488 }, 9489 "pwr": { 9490 "description": "A hint about how the RD is powered. If AC then this is stronger 9491 than battery powered. If source is reliable (safe) then appropriate mechanism for managing power 9492 failure exists", 9493 "enum": [ 9494 "ac", 9495
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 240
"batt", 9496 "safe" 9497 ], 9498 "type": "string" 9499 } 9500 }, 9501 "type": "object" 9502 } 9503 }, 9504 "required": [ 9505 "sel" 9506 ] 9507 } 9508 ], 9509 "type": "object" 9510 } 9511 9512 , 9513 "rdPublish" : 9514 { 9515 "description": "Publishes resources as OIC Links into the resource directory", 9516 "properties": { 9517 "di": { 9518 "description": "A unique identifier for the publishing Device, i.e., its device ID", 9519 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9520 9]{12}$", 9521 "type": "string" 9522 }, 9523 "id": { 9524 "description": "Instance ID of this specific resource", 9525 "maxLength": 64, 9526 "readOnly": true, 9527 "type": "string" 9528 }, 9529 "if": { 9530 "description": "The interface set supported by this resource", 9531 "items": { 9532 "enum": [ 9533 "oic.if.baseline", 9534 "oic.if.ll", 9535 "oic.if.b", 9536 "oic.if.lb", 9537 "oic.if.rw", 9538 "oic.if.r", 9539 "oic.if.a", 9540 "oic.if.s" 9541 ], 9542 "type": "string" 9543 }, 9544 "minItems": 1, 9545 "readOnly": true, 9546 "type": "array" 9547 }, 9548 "links": { 9549 "description": "A set (array) of simple or individual OIC Links. In addition to 9550 properties required for an OIC Link, the identifier for that link in this set is also required", 9551 "items": { 9552 "properties": { 9553 "anchor": { 9554 "description": "This is used to override the context URI e.g. override the URI of 9555 the containing collection", 9556 "format": "uri", 9557 "maxLength": 256, 9558 "type": "string" 9559 }, 9560 "di": { 9561 "description": "Unique identifier for device (UUID)", 9562 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-9563 F0-9]{12}$", 9564 "type": "string" 9565 }, 9566
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 241
"eps": { 9567 "description": "the Endpoint information of the target Resource", 9568 "items": { 9569 "properties": { 9570 "ep": { 9571 "description": "URI with Transport Protocol Suites + Endpoint Locator as 9572 specified in 10.2.1", 9573 "format": "uri", 9574 "type": "string" 9575 }, 9576 "pri": { 9577 "description": "The priority among multiple Endpoints as specified in 9578 10.2.3", 9579 "minimum": 1, 9580 "type": "integer" 9581 } 9582 }, 9583 "type": "object" 9584 }, 9585 "type": "array" 9586 }, 9587 "href": { 9588 "description": "This is the target URI, it can be specified as a Relative 9589 Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to 9590 make it unique.", 9591 "format": "uri", 9592 "maxLength": 256, 9593 "type": "string" 9594 }, 9595 "if": { 9596 "description": "The interface set supported by this resource", 9597 "items": { 9598 "enum": [ 9599 "oic.if.baseline", 9600 "oic.if.ll", 9601 "oic.if.b", 9602 "oic.if.rw", 9603 "oic.if.r", 9604 "oic.if.a", 9605 "oic.if.s" 9606 ], 9607 "type": "string" 9608 }, 9609 "minItems": 1, 9610 "type": "array" 9611 }, 9612 "ins": { 9613 "description": "The instance identifier for this web link in an array of web 9614 links - used in collections", 9615 "oneOf": [ 9616 { 9617 "description": "An ordinal number that is not repeated - must be unique in 9618 the collection context", 9619 "type": "integer" 9620 }, 9621 { 9622 "description": "Any unique string including a URI", 9623 "format": "uri", 9624 "maxLength": 256, 9625 "type": "string" 9626 }, 9627 { 9628 "description": "Unique identifier (UUID)", 9629 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-9630 fA-F0-9]{12}$", 9631 "type": "string" 9632 } 9633 ] 9634 }, 9635 "p": { 9636 "description": "Specifies the framework policies on the Resource referenced by 9637
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 242
the target URI", 9638 "properties": { 9639 "bm": { 9640 "description": "Specifies the framework policies on the Resource referenced 9641 by the target URI for e.g. observable and discoverable", 9642 "type": "integer" 9643 } 9644 }, 9645 "required": [ 9646 "bm" 9647 ], 9648 "type": "object" 9649 }, 9650 "rel": { 9651 "description": "The relation of the target URI referenced by the link to the 9652 context URI", 9653 "oneOf": [ 9654 { 9655 "default": [ 9656 "hosts" 9657 ], 9658 "items": { 9659 "maxLength": 64, 9660 "type": "string" 9661 }, 9662 "minItems": 1, 9663 "type": "array" 9664 }, 9665 { 9666 "default": "hosts", 9667 "maxLength": 64, 9668 "type": "string" 9669 } 9670 ] 9671 }, 9672 "rt": { 9673 "description": "Resource Type", 9674 "items": { 9675 "maxLength": 64, 9676 "type": "string" 9677 }, 9678 "minItems": 1, 9679 "type": "array" 9680 }, 9681 "title": { 9682 "description": "A title for the link relation. Can be used by the UI to provide a 9683 context", 9684 "maxLength": 64, 9685 "type": "string" 9686 }, 9687 "type": { 9688 "default": "application/cbor", 9689 "description": "A hint at the representation of the resource referenced by the 9690 target URI. This represents the media types that are used for both accepting and emitting", 9691 "items": { 9692 "maxLength": 64, 9693 "type": "string" 9694 }, 9695 "minItems": 1, 9696 "type": "array" 9697 } 9698 }, 9699 "required": [ 9700 "href", 9701 "rt", 9702 "if" 9703 ], 9704 "type": "object" 9705 }, 9706 "type": "array" 9707 }, 9708
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 243
"n": { 9709 "description": "Friendly name of the resource", 9710 "maxLength": 64, 9711 "readOnly": true, 9712 "type": "string" 9713 }, 9714 "rt": { 9715 "description": "Resource Type", 9716 "items": { 9717 "maxLength": 64, 9718 "type": "string" 9719 }, 9720 "minItems": 1, 9721 "readOnly": true, 9722 "type": "array" 9723 }, 9724 "ttl": { 9725 "description": "Time to indicate a RD, how long to keep this published item. After this 9726 time (in seconds) elapses, the RD invalidates the links. To keep link alive the publishing device 9727 updates the ttl using the update schema", 9728 "type": "integer" 9729 } 9730 } 9731 } 9732 9733 } 9734 } 9735 9736
E.10.5 Property Definition 9737
Property name Value type Mandatory Access mode Description
id string Read Only Instance ID of this specific resource
n string Read Only Friendly name of the resource
ttl integer Time to indicate a RD, how long to keep this published item. After this time (in seconds) elapses, the RD invalidates the links. To keep link alive the publishing device updates the ttl using the update schema
links array: see schema
A set (array) of simple or individual OIC Links. In addition to properties required for an OIC Link, the identifier for that link in this set is also required
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 244
if array: see schema
yes Read Only The interface set supported by this resource
rt array: see schema
yes Read Only Resource Type
di string A unique identifier for the publishing Device, i.e., its device ID
id string Read Only Instance ID of this specific resource
sel object: see schema
yes Selection criteria that a device wanting to publish to any RD can use to choose this Resource Directory over others that are discovered
if array: see schema
Read Only The interface set supported by this resource
rt array: see schema
Read Only Resource Type
n string Read Only Friendly name of the resource
E.10.6 CRUDN behavior 9738
Resource Create Read Update Delete Notify
/oic/rd get post delete
E.11 Discoverable Resources 9739
E.11.1 Introduction 9740
Retrieve the discoverable resource set. 9741
9742
E.11.2 Wellknown URI 9743
/oic/res 9744
E.11.3 Resource Type 9745
E.11.4 Swagger2.0 Definition 9746
{ 9747 "swagger": "2.0", 9748 "info": { 9749 "title": "Discoverable Resources Baseline Interface", 9750 "version": "v1-20160622", 9751 "license": { 9752 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 9753 "x-description": "Redistribution and use in source and binary forms, with or without 9754 modification, are permitted provided that the following conditions are met:\n 1. 9755 Redistributions of source code must retain the above copyright notice, this list of conditions and 9756 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 9757 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 9758
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 245
other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 9759 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 9760 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 9761 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 9762 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 9763 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 9764 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 9765 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 9766 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 9767 OF SUCH DAMAGE.\n" 9768 } 9769 }, 9770 "schemes": ["http"], 9771 "consumes": ["application/json"], 9772 "produces": ["application/json"], 9773 "paths": { 9774 "/oic-res-BaselineInterfaceURI" : { 9775 "get": { 9776 "description": "Baseline representation of /oic/res; list of discoverable 9777 resources\nRetrieve the discoverable resource set, baseline interface\n", 9778 "parameters": [ 9779 {"$ref": "#/parameters/interface-baseline"} 9780 ], 9781 "responses": { 9782 "200": { 9783 "description" : "", 9784 "x-example": 9785 [ 9786 { 9787 "rt": ["oic.wk.res"], 9788 "if": ["oic.if.baseline", "oic.if.ll" ], 9789 "links": 9790 [ 9791 { 9792 "href": "/humidity", 9793 "rt": ["oic.r.humidity"], 9794 "if": ["oic.if.s"], 9795 "p": {"bm": 3}, 9796 "eps": [ 9797 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 9798 {"ep": "coaps://[fe80::b1d6]:1122"}, 9799 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 9800 ] 9801 }, 9802 { 9803 "href": "/temperature", 9804 "rt": ["oic.r.temperature"], 9805 "if": ["oic.if.s"], 9806 "p": {"bm": 3}, 9807 "eps": [ 9808 {"ep": "coaps://[[2001:db8:a::123]:2222"} 9809 ] 9810 } 9811 ] 9812 } 9813 ] 9814 , 9815 "schema": { "$ref": "#/definitions/sbaseline" } 9816 } 9817 } 9818 } 9819 }, 9820 "/oic-res-llInterfaceURI" : { 9821 "get": { 9822 "description": "Link list representation of /oic/res; list of discoverable 9823 resources\nRetrieve the discoverable resource set, link list interface\n", 9824 "parameters": [ 9825 {"$ref": "#/parameters/interface-ll"} 9826 ], 9827 "responses": { 9828 "200": { 9829
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 246
"description" : "", 9830 "x-example": 9831 [ 9832 { 9833 "href": "/humidity", 9834 "rt": ["oic.r.humidity"], 9835 "if": ["oic.if.s"], 9836 "p": {"bm": 3}, 9837 "eps": [ 9838 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 9839 {"ep": "coaps://[fe80::b1d6]:1122"}, 9840 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 9841 ] 9842 }, 9843 { 9844 "href": "/temperature", 9845 "rt": ["oic.r.temperature"], 9846 "if": ["oic.if.s"], 9847 "p": {"bm": 3}, 9848 "eps": [ 9849 {"ep": "coaps://[[2001:db8:a::123]:2222"} 9850 ] 9851 } 9852 ] 9853 , 9854 "schema": { "$ref": "#/definitions/slinklist" } 9855 } 9856 } 9857 } 9858 } 9859 }, 9860 "parameters": { 9861 "interface-ll" : { 9862 "in" : "query", 9863 "name" : "if", 9864 "type" : "string", 9865 "enum" : ["oic.if.ll"] 9866 }, 9867 "interface-baseline" : { 9868 "in" : "query", 9869 "name" : "if", 9870 "type" : "string", 9871 "enum" : ["oic.if.baseline"] 9872 } 9873 }, 9874 "definitions": { 9875 "sbaseline" : 9876 { 9877 "properties": { 9878 "if": { 9879 "description": "The interface set supported by this resource", 9880 "items": { 9881 "enum": [ 9882 "oic.if.baseline", 9883 "oic.if.ll" 9884 ], 9885 "type": "string" 9886 }, 9887 "minItems": 1, 9888 "readOnly": true, 9889 "type": "array" 9890 }, 9891 "links": { 9892 "items": { 9893 "properties": { 9894 "anchor": { 9895 "description": "This is used to override the context URI e.g. override the URI of 9896 the containing collection", 9897 "format": "uri", 9898 "maxLength": 256, 9899 "type": "string" 9900
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 247
}, 9901 "di": { 9902 "description": "Unique identifier for device (UUID)", 9903 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-9904 F0-9]{12}$", 9905 "type": "string" 9906 }, 9907 "eps": { 9908 "description": "the Endpoint information of the target Resource", 9909 "items": { 9910 "properties": { 9911 "ep": { 9912 "description": "URI with Transport Protocol Suites + Endpoint Locator as 9913 specified in 10.2.1", 9914 "format": "uri", 9915 "type": "string" 9916 }, 9917 "pri": { 9918 "description": "The priority among multiple Endpoints as specified in 9919 10.2.3", 9920 "minimum": 1, 9921 "type": "integer" 9922 } 9923 }, 9924 "type": "object" 9925 }, 9926 "type": "array" 9927 }, 9928 "href": { 9929 "description": "This is the target URI, it can be specified as a Relative 9930 Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to 9931 make it unique.", 9932 "format": "uri", 9933 "maxLength": 256, 9934 "type": "string" 9935 }, 9936 "if": { 9937 "description": "The interface set supported by this resource", 9938 "items": { 9939 "enum": [ 9940 "oic.if.baseline", 9941 "oic.if.ll", 9942 "oic.if.b", 9943 "oic.if.rw", 9944 "oic.if.r", 9945 "oic.if.a", 9946 "oic.if.s" 9947 ], 9948 "type": "string" 9949 }, 9950 "minItems": 1, 9951 "type": "array" 9952 }, 9953 "ins": { 9954 "description": "The instance identifier for this web link in an array of web 9955 links - used in collections", 9956 "oneOf": [ 9957 { 9958 "description": "An ordinal number that is not repeated - must be unique in 9959 the collection context", 9960 "type": "integer" 9961 }, 9962 { 9963 "description": "Any unique string including a URI", 9964 "format": "uri", 9965 "maxLength": 256, 9966 "type": "string" 9967 }, 9968 { 9969 "description": "Unique identifier (UUID)", 9970 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-9971
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 248
fA-F0-9]{12}$", 9972 "type": "string" 9973 } 9974 ] 9975 }, 9976 "p": { 9977 "description": "Specifies the framework policies on the Resource referenced by 9978 the target URI", 9979 "properties": { 9980 "bm": { 9981 "description": "Specifies the framework policies on the Resource referenced 9982 by the target URI for e.g. observable and discoverable", 9983 "type": "integer" 9984 } 9985 }, 9986 "required": [ 9987 "bm" 9988 ], 9989 "type": "object" 9990 }, 9991 "rel": { 9992 "description": "The relation of the target URI referenced by the link to the 9993 context URI", 9994 "oneOf": [ 9995 { 9996 "default": [ 9997 "hosts" 9998 ], 9999 "items": { 10000 "maxLength": 64, 10001 "type": "string" 10002 }, 10003 "minItems": 1, 10004 "type": "array" 10005 }, 10006 { 10007 "default": "hosts", 10008 "maxLength": 64, 10009 "type": "string" 10010 } 10011 ] 10012 }, 10013 "rt": { 10014 "description": "Resource Type", 10015 "items": { 10016 "maxLength": 64, 10017 "type": "string" 10018 }, 10019 "minItems": 1, 10020 "type": "array" 10021 }, 10022 "title": { 10023 "description": "A title for the link relation. Can be used by the UI to provide a 10024 context", 10025 "maxLength": 64, 10026 "type": "string" 10027 }, 10028 "type": { 10029 "default": "application/cbor", 10030 "description": "A hint at the representation of the resource referenced by the 10031 target URI. This represents the media types that are used for both accepting and emitting", 10032 "items": { 10033 "maxLength": 64, 10034 "type": "string" 10035 }, 10036 "minItems": 1, 10037 "type": "array" 10038 } 10039 }, 10040 "required": [ 10041 "href", 10042
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 249
"rt", 10043 "if" 10044 ], 10045 "type": "object" 10046 }, 10047 "type": "array" 10048 }, 10049 "mpro": { 10050 "description": "Supported messaging protocols", 10051 "maxLength": 64, 10052 "readOnly": true, 10053 "type": "string" 10054 }, 10055 "n": { 10056 "description": "Human friendly name", 10057 "maxLength": 64, 10058 "readOnly": true, 10059 "type": "string" 10060 }, 10061 "rt": { 10062 "description": "Resource Type", 10063 "items": { 10064 "maxLength": 64, 10065 "type": "string" 10066 }, 10067 "minItems": 1, 10068 "readOnly": true, 10069 "type": "array" 10070 } 10071 }, 10072 "required": [ 10073 "rt", 10074 "if", 10075 "links" 10076 ], 10077 "type": "object" 10078 } 10079 10080 , 10081 "slinklist" : 10082 { 10083 "properties": { 10084 "anchor": { 10085 "description": "This is used to override the context URI e.g. override the URI of the 10086 containing collection", 10087 "format": "uri", 10088 "maxLength": 256, 10089 "type": "string" 10090 }, 10091 "di": { 10092 "description": "Unique identifier for device (UUID)", 10093 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10094 9]{12}$", 10095 "type": "string" 10096 }, 10097 "eps": { 10098 "description": "the Endpoint information of the target Resource", 10099 "items": { 10100 "properties": { 10101 "ep": { 10102 "description": "URI with Transport Protocol Suites + Endpoint Locator as 10103 specified in 10.2.1", 10104 "format": "uri", 10105 "type": "string" 10106 }, 10107 "pri": { 10108 "description": "The priority among multiple Endpoints as specified in 10.2.3", 10109 "minimum": 1, 10110 "type": "integer" 10111 } 10112 }, 10113
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 250
"type": "object" 10114 }, 10115 "type": "array" 10116 }, 10117 "href": { 10118 "description": "This is the target URI, it can be specified as a Relative Reference or 10119 fully-qualified URI. Relative Reference should be used along with the di parameter to make it 10120 unique.", 10121 "format": "uri", 10122 "maxLength": 256, 10123 "type": "string" 10124 }, 10125 "if": { 10126 "description": "The interface set supported by this resource", 10127 "items": { 10128 "enum": [ 10129 "oic.if.baseline", 10130 "oic.if.ll", 10131 "oic.if.b", 10132 "oic.if.rw", 10133 "oic.if.r", 10134 "oic.if.a", 10135 "oic.if.s" 10136 ], 10137 "type": "string" 10138 }, 10139 "minItems": 1, 10140 "type": "array" 10141 }, 10142 "ins": { 10143 "description": "The instance identifier for this web link in an array of web links - 10144 used in collections", 10145 "oneOf": [ 10146 { 10147 "description": "An ordinal number that is not repeated - must be unique in the 10148 collection context", 10149 "type": "integer" 10150 }, 10151 { 10152 "description": "Any unique string including a URI", 10153 "format": "uri", 10154 "maxLength": 256, 10155 "type": "string" 10156 }, 10157 { 10158 "description": "Unique identifier (UUID)", 10159 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10160 9]{12}$", 10161 "type": "string" 10162 } 10163 ] 10164 }, 10165 "p": { 10166 "description": "Specifies the framework policies on the Resource referenced by the 10167 target URI", 10168 "properties": { 10169 "bm": { 10170 "description": "Specifies the framework policies on the Resource referenced by the 10171 target URI for e.g. observable and discoverable", 10172 "type": "integer" 10173 } 10174 }, 10175 "required": [ 10176 "bm" 10177 ], 10178 "type": "object" 10179 }, 10180 "rel": { 10181 "description": "The relation of the target URI referenced by the link to the context 10182 URI", 10183 "oneOf": [ 10184
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 251
{ 10185 "default": [ 10186 "hosts" 10187 ], 10188 "items": { 10189 "maxLength": 64, 10190 "type": "string" 10191 }, 10192 "minItems": 1, 10193 "type": "array" 10194 }, 10195 { 10196 "default": "hosts", 10197 "maxLength": 64, 10198 "type": "string" 10199 } 10200 ] 10201 }, 10202 "rt": { 10203 "description": "Resource Type", 10204 "items": { 10205 "maxLength": 64, 10206 "type": "string" 10207 }, 10208 "minItems": 1, 10209 "type": "array" 10210 }, 10211 "title": { 10212 "description": "A title for the link relation. Can be used by the UI to provide a 10213 context", 10214 "maxLength": 64, 10215 "type": "string" 10216 }, 10217 "type": { 10218 "default": "application/cbor", 10219 "description": "A hint at the representation of the resource referenced by the target 10220 URI. This represents the media types that are used for both accepting and emitting", 10221 "items": { 10222 "maxLength": 64, 10223 "type": "string" 10224 }, 10225 "minItems": 1, 10226 "type": "array" 10227 } 10228 }, 10229 "required": [ 10230 "href", 10231 "rt", 10232 "if" 10233 ], 10234 "type": "object" 10235 } 10236 10237 } 10238 } 10239 10240
E.11.5 Property Definition 10241
Property name Value type Mandatory Access mode Description
links array: see schema
yes
mpro string Read Only Supported messaging protocols
if array: see schema
yes Read Only The interface set supported by this resource
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 252
rt array: see schema
yes Read Only Resource Type
n string Read Only Human friendly name
p object: see schema
Specifies the framework policies on the Resource referenced by the target URI
type array: see schema
A hint at the representation of the resource referenced by the target URI. This represents the media types that are used for both accepting and emitting
if array: see schema
yes The interface set supported by this resource
rt array: see schema
yes Resource Type
anchor string This is used to override the context URI e.g. override the URI of the containing collection
ins multiple types: see schema
The instance identifier for this web link in an array of web links - used in collections
eps array: see schema
the Endpoint information of the target Resource
di string Unique identifier for device (UUID)
title string A title for the link relation. Can be used by the UI to provide a context
href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI. Relative Reference
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 253
should be used along with the di parameter to make it unique.
rel multiple types: see schema
The relation of the target URI referenced by the link to the context URI
E.11.6 CRUDN behavior 10242
Resource Create Read Update Delete Notify
/oic-res-llInterfaceURI
get
E.12 Scenes 10243
E.12.1 Introduction 10244
Toplevel Scene resource. 10245
This resource is a generic collection resource. 10246
The rts value shall contain oic.wk.scenecollection resource types. 10247
Provides the current list of web links pointing to scenes 10248
10249
E.12.2 Example URI 10250
/SceneListResURI 10251
E.12.3 Resource Type 10252
The resource types (rt) are defined as: 10253
['oic.wk.scenelist',’oic.wk.scenemember’,’oic.wk.scenecollection’]. 10254
E.12.4 Swagger2.0 Definition 10255
{ 10256 "swagger": "2.0", 10257 "info": { 10258 "title": "Scenes (Top level)", 10259 "version": "v1-20160622", 10260 "license": { 10261 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 10262 "x-description": "Redistribution and use in source and binary forms, with or without 10263 modification, are permitted provided that the following conditions are met:\n 1. 10264 Redistributions of source code must retain the above copyright notice, this list of conditions and 10265 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 10266 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 10267 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 10268 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 10269 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 10270 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 10271 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 10272 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 10273 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 10274 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 10275 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 10276 OF SUCH DAMAGE.\n" 10277 } 10278 }, 10279 "schemes": ["http"], 10280 "consumes": ["application/json"], 10281 "produces": ["application/json"], 10282 "paths": { 10283 "/SceneListResURI" : { 10284 "get": { 10285
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 254
"description": "Toplevel Scene resource.\nThis resource is a generic collection 10286 resource.\nThe rts value shall contain oic.wk.scenecollection resource types.\nProvides the current 10287 list of web links pointing to scenes\n", 10288 "parameters": [ 10289 ], 10290 "responses": { 10291 "200": { 10292 "description" : "", 10293 "x-example": 10294 { 10295 "rt": ["oic.wk.scenelist"], 10296 "n": "list of scene Collections", 10297 "rts": ["oic.wk.scenecollection"], 10298 "links": [ 10299 ] 10300 } 10301 , 10302 "schema": { "$ref": "#/definitions/Collection" } 10303 } 10304 } 10305 } 10306 }, 10307 "/SceneMemberResURI" : { 10308 "get": { 10309 "description": "Collection that models a scene member.\nProvides the scene member\n", 10310 "parameters": [ 10311 ], 10312 "responses": { 10313 "200": { 10314 "description" : "", 10315 "x-example": 10316 { 10317 "rt": ["oic.wk.scenemember"], 10318 "id": "0685B960-FFFF-46F7-BEC0-9E6234671ADC1", 10319 "n": "my binary switch (for light bulb) mappings", 10320 "link": { 10321 "href": "binarySwitch", 10322 "rt": ["oic.r.switch.binary"], 10323 "if": ["oic.if.a", "oic.if.baseline"], 10324 "eps": [ 10325 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 10326 {"ep": "coaps://[fe80::b1d6]:1122"}, 10327 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 10328 ] 10329 }, 10330 "sceneMappings": [ 10331 { 10332 "scene": "off", 10333 "memberProperty": "value", 10334 "memberValue": true 10335 }, 10336 { 10337 "scene": "Reading", 10338 "memberProperty": "value", 10339 "memberValue": false 10340 }, 10341 { 10342 "scene": "TVWatching", 10343 "memberProperty": "value", 10344 "memberValue": true 10345 } 10346 ] 10347 } 10348 , 10349 "schema": { "$ref": "#/definitions/SceneMember" } 10350 } 10351 } 10352 } 10353 }, 10354 "/SceneCollectionResURI" : { 10355 "get": { 10356
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 255
"description": "Collection that models a set of Scenes.\nThis resource is a generic 10357 collection resource with additional parameters.\nThe rts value shall contain oic.scenemember 10358 resource types.\nThe additional parameters are\n lastScene, this is the scene value last set by 10359 any OCF Client\n sceneValues, this is the list of available scenes\n lastScene shall be listed in 10360 sceneValues.\nProvides the current list of web links pointing to scenes\n", 10361 "parameters": [ 10362 ], 10363 "responses": { 10364 "200": { 10365 "description" : "", 10366 "x-example": 10367 { 10368 "lastScene": "off", 10369 "sceneValues": "off,Reading,TVWatching", 10370 "rt": ["oic.wk.scenecollection"], 10371 "n": "My Scenes for my living room", 10372 "id": "0685B960-736F-46F7-BEC0-9E6CBD671ADC1", 10373 "rts": ["oic.wk.scenemember"], 10374 "links": [ 10375 ] 10376 } 10377 , 10378 "schema": { "$ref": "#/definitions/SceneCollection" } 10379 } 10380 } 10381 }, 10382 "post": { 10383 "description": "Provides the action to change the last set scene selection.\nCalling this 10384 method shall update all scene members to the prescribed membervalue.\nWhen this method is called 10385 with the same value as the current lastScene value\nthen all scene members shall be updated.\n", 10386 "parameters": [ 10387 { 10388 "name": "body", 10389 "in": "body", 10390 "required": true, 10391 "schema": { "$ref": "#/definitions/SceneCollectionUpdate" }, 10392 "x-example": 10393 { 10394 "lastScene": "Reading" 10395 } 10396 } 10397 ], 10398 "responses": { 10399 "200": { 10400 "description" : "Indicates that the value is changed.\nThe changed properties are 10401 provided in the response.\n", 10402 "x-example": 10403 { 10404 "lastScene": "Reading" 10405 } 10406 , 10407 "schema": { "$ref": "#/definitions/SceneCollectionUpdate" } 10408 } 10409 } 10410 } 10411 } 10412 }, 10413 "parameters": { 10414 "interface" : { 10415 "in" : "query", 10416 "name" : "if", 10417 "type" : "string", 10418 "enum" : ["oic.if.a", "oic.if.ll", "oic.if.baseline"] 10419 } 10420 }, 10421 "definitions": { 10422 "Collection" : 10423 { 10424 "description": "A set (array) of simple or individual OIC Links. In addition to properties 10425 required for an OIC Link, the identifier for that link in this set is also required", 10426 "items": { 10427
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 256
"properties": { 10428 "anchor": { 10429 "description": "This is used to override the context URI e.g. override the URI of the 10430 containing collection", 10431 "format": "uri", 10432 "maxLength": 256, 10433 "type": "string" 10434 }, 10435 "di": { 10436 "description": "Unique identifier for device (UUID)", 10437 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10438 9]{12}$", 10439 "type": "string" 10440 }, 10441 "drel": { 10442 "description": "When specified this is the default relationship to use when an OIC 10443 Link does not specify an explicit relationship with *rel* parameter", 10444 "type": "string" 10445 }, 10446 "eps": { 10447 "description": "the Endpoint information of the target Resource", 10448 "items": { 10449 "properties": { 10450 "ep": { 10451 "description": "URI with Transport Protocol Suites + Endpoint Locator as 10452 specified in 10.2.1", 10453 "format": "uri", 10454 "type": "string" 10455 }, 10456 "pri": { 10457 "description": "The priority among multiple Endpoints as specified in 10.2.3", 10458 "minimum": 1, 10459 "type": "integer" 10460 } 10461 }, 10462 "type": "object" 10463 }, 10464 "type": "array" 10465 }, 10466 "href": { 10467 "description": "This is the target URI, it can be specified as a Relative Reference 10468 or fully-qualified URI. Relative Reference should be used along with the di parameter to make it 10469 unique.", 10470 "format": "uri", 10471 "maxLength": 256, 10472 "type": "string" 10473 }, 10474 "id": { 10475 "description": "Instance ID of this specific resource", 10476 "maxLength": 64, 10477 "readOnly": true, 10478 "type": "string" 10479 }, 10480 "if": { 10481 "description": "The interface set supported by this resource", 10482 "items": { 10483 "enum": [ 10484 "oic.if.baseline", 10485 "oic.if.ll", 10486 "oic.if.b", 10487 "oic.if.rw", 10488 "oic.if.r", 10489 "oic.if.a", 10490 "oic.if.s" 10491 ], 10492 "type": "string" 10493 }, 10494 "minItems": 1, 10495 "type": "array" 10496 }, 10497 "ins": { 10498
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 257
"description": "The instance identifier for this web link in an array of web links - 10499 used in collections", 10500 "oneOf": [ 10501 { 10502 "description": "An ordinal number that is not repeated - must be unique in the 10503 collection context", 10504 "type": "integer" 10505 }, 10506 { 10507 "description": "Any unique string including a URI", 10508 "format": "uri", 10509 "maxLength": 256, 10510 "type": "string" 10511 }, 10512 { 10513 "description": "Unique identifier (UUID)", 10514 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-10515 F0-9]{12}$", 10516 "type": "string" 10517 } 10518 ] 10519 }, 10520 "links": { 10521 "description": "All forms of links in a collection", 10522 "oneOf": [ 10523 { 10524 "description": "A set (array) of simple or individual OIC Links. In addition to 10525 properties required for an OIC Link, the identifier for that link in this set is also required", 10526 "items": { 10527 "properties": { 10528 "anchor": { 10529 "description": "This is used to override the context URI e.g. override the 10530 URI of the containing collection", 10531 "format": "uri", 10532 "maxLength": 256, 10533 "type": "string" 10534 }, 10535 "di": { 10536 "description": "Unique identifier for device (UUID)", 10537 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-10538 [a-fA-F0-9]{12}$", 10539 "type": "string" 10540 }, 10541 "eps": { 10542 "description": "the Endpoint information of the target Resource", 10543 "items": { 10544 "properties": { 10545 "ep": { 10546 "description": "URI with Transport Protocol Suites + Endpoint Locator 10547 as specified in 10.2.1", 10548 "format": "uri", 10549 "type": "string" 10550 }, 10551 "pri": { 10552 "description": "The priority among multiple Endpoints as specified in 10553 10.2.3", 10554 "minimum": 1, 10555 "type": "integer" 10556 } 10557 }, 10558 "type": "object" 10559 }, 10560 "type": "array" 10561 }, 10562 "href": { 10563 "description": "This is the target URI, it can be specified as a Relative 10564 Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to 10565 make it unique.", 10566 "format": "uri", 10567 "maxLength": 256, 10568 "type": "string" 10569
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 258
}, 10570 "if": { 10571 "description": "The interface set supported by this resource", 10572 "items": { 10573 "enum": [ 10574 "oic.if.baseline", 10575 "oic.if.ll", 10576 "oic.if.b", 10577 "oic.if.rw", 10578 "oic.if.r", 10579 "oic.if.a", 10580 "oic.if.s" 10581 ], 10582 "type": "string" 10583 }, 10584 "minItems": 1, 10585 "type": "array" 10586 }, 10587 "ins": { 10588 "description": "The instance identifier for this web link in an array of 10589 web links - used in collections", 10590 "oneOf": [ 10591 { 10592 "description": "An ordinal number that is not repeated - must be unique 10593 in the collection context", 10594 "type": "integer" 10595 }, 10596 { 10597 "description": "Any unique string including a URI", 10598 "format": "uri", 10599 "maxLength": 256, 10600 "type": "string" 10601 }, 10602 { 10603 "description": "Unique identifier (UUID)", 10604 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10605 9]{4}-[a-fA-F0-9]{12}$", 10606 "type": "string" 10607 } 10608 ] 10609 }, 10610 "p": { 10611 "description": "Specifies the framework policies on the Resource referenced 10612 by the target URI", 10613 "properties": { 10614 "bm": { 10615 "description": "Specifies the framework policies on the Resource 10616 referenced by the target URI for e.g. observable and discoverable", 10617 "type": "integer" 10618 } 10619 }, 10620 "required": [ 10621 "bm" 10622 ], 10623 "type": "object" 10624 }, 10625 "rel": { 10626 "description": "The relation of the target URI referenced by the link to 10627 the context URI", 10628 "oneOf": [ 10629 { 10630 "default": [ 10631 "hosts" 10632 ], 10633 "items": { 10634 "maxLength": 64, 10635 "type": "string" 10636 }, 10637 "minItems": 1, 10638 "type": "array" 10639 }, 10640
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 259
{ 10641 "default": "hosts", 10642 "maxLength": 64, 10643 "type": "string" 10644 } 10645 ] 10646 }, 10647 "rt": { 10648 "description": "Resource Type", 10649 "items": { 10650 "maxLength": 64, 10651 "type": "string" 10652 }, 10653 "minItems": 1, 10654 "type": "array" 10655 }, 10656 "title": { 10657 "description": "A title for the link relation. Can be used by the UI to 10658 provide a context", 10659 "maxLength": 64, 10660 "type": "string" 10661 }, 10662 "type": { 10663 "default": "application/cbor", 10664 "description": "A hint at the representation of the resource referenced by 10665 the target URI. This represents the media types that are used for both accepting and emitting", 10666 "items": { 10667 "maxLength": 64, 10668 "type": "string" 10669 }, 10670 "minItems": 1, 10671 "type": "array" 10672 } 10673 }, 10674 "required": [ 10675 "href", 10676 "rt", 10677 "if" 10678 ], 10679 "type": "object" 10680 }, 10681 "type": "array" 10682 } 10683 ] 10684 }, 10685 "n": { 10686 "description": "Friendly name of the resource", 10687 "maxLength": 64, 10688 "readOnly": true, 10689 "type": "string" 10690 }, 10691 "p": { 10692 "description": "Specifies the framework policies on the Resource referenced by the 10693 target URI", 10694 "properties": { 10695 "bm": { 10696 "description": "Specifies the framework policies on the Resource referenced by 10697 the target URI for e.g. observable and discoverable", 10698 "type": "integer" 10699 } 10700 }, 10701 "required": [ 10702 "bm" 10703 ], 10704 "type": "object" 10705 }, 10706 "rel": { 10707 "description": "The relation of the target URI referenced by the link to the context 10708 URI", 10709 "oneOf": [ 10710 { 10711
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 260
"default": [ 10712 "hosts" 10713 ], 10714 "items": { 10715 "maxLength": 64, 10716 "type": "string" 10717 }, 10718 "minItems": 1, 10719 "type": "array" 10720 }, 10721 { 10722 "default": "hosts", 10723 "maxLength": 64, 10724 "type": "string" 10725 } 10726 ] 10727 }, 10728 "rt": { 10729 "description": "Resource Type", 10730 "items": { 10731 "maxLength": 64, 10732 "type": "string" 10733 }, 10734 "minItems": 1, 10735 "type": "array" 10736 }, 10737 "rts": { 10738 "description": "Defines the list of allowable resource types (for Target and anchors) 10739 in links included in the collection; new links being created can only be from this list", 10740 "items": { 10741 "maxLength": 64, 10742 "type": "string" 10743 }, 10744 "minItems": 1, 10745 "readOnly": true, 10746 "type": "array" 10747 }, 10748 "title": { 10749 "description": "A title for the link relation. Can be used by the UI to provide a 10750 context", 10751 "maxLength": 64, 10752 "type": "string" 10753 }, 10754 "type": { 10755 "default": "application/cbor", 10756 "description": "A hint at the representation of the resource referenced by the target 10757 URI. This represents the media types that are used for both accepting and emitting", 10758 "items": { 10759 "maxLength": 64, 10760 "type": "string" 10761 }, 10762 "minItems": 1, 10763 "type": "array" 10764 } 10765 }, 10766 "required": [ 10767 "href", 10768 "rt", 10769 "if" 10770 ], 10771 "type": "object" 10772 }, 10773 "type": "array" 10774 } 10775 10776 , 10777 "SceneMember" : 10778 { 10779 "properties": { 10780 "SceneMappings": { 10781 "description": "array of mappings per scene, can be 1", 10782
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 261
"items": { 10783 "properties": { 10784 "memberProperty": { 10785 "description": "property name that will be mapped", 10786 "readOnly": true, 10787 "type": "string" 10788 }, 10789 "memberValue": { 10790 "description": "value of the Member Property", 10791 "readOnly": true, 10792 "type": "string" 10793 }, 10794 "scene": { 10795 "description": "Specifies a scene value that will acted upon", 10796 "type": "string" 10797 } 10798 }, 10799 "required": [ 10800 "scene", 10801 "memberProperty", 10802 "memberValue" 10803 ], 10804 "type": "object" 10805 }, 10806 "type": "array" 10807 }, 10808 "id": { 10809 "description": "Can be an value that is unique to the use context or a UUIDv4", 10810 "type": "string" 10811 }, 10812 "if": { 10813 "description": "The interface set supported by this resource", 10814 "items": { 10815 "enum": [ 10816 "oic.if.baseline", 10817 "oic.if.ll", 10818 "oic.if.b", 10819 "oic.if.lb", 10820 "oic.if.rw", 10821 "oic.if.r", 10822 "oic.if.a", 10823 "oic.if.s" 10824 ], 10825 "type": "string" 10826 }, 10827 "minItems": 1, 10828 "readOnly": true, 10829 "type": "array" 10830 }, 10831 "link": { 10832 "description": "web link that points at a resource", 10833 "properties": { 10834 "anchor": { 10835 "description": "This is used to override the context URI e.g. override the URI of 10836 the containing collection", 10837 "format": "uri", 10838 "maxLength": 256, 10839 "type": "string" 10840 }, 10841 "di": { 10842 "description": "Unique identifier for device (UUID)", 10843 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10844 9]{12}$", 10845 "type": "string" 10846 }, 10847 "eps": { 10848 "description": "the Endpoint information of the target Resource", 10849 "items": { 10850 "properties": { 10851 "ep": { 10852 "description": "URI with Transport Protocol Suites + Endpoint Locator as 10853
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 262
specified in 10.2.1", 10854 "format": "uri", 10855 "type": "string" 10856 }, 10857 "pri": { 10858 "description": "The priority among multiple Endpoints as specified in 10859 10.2.3", 10860 "minimum": 1, 10861 "type": "integer" 10862 } 10863 }, 10864 "type": "object" 10865 }, 10866 "type": "array" 10867 }, 10868 "href": { 10869 "description": "This is the target URI, it can be specified as a Relative Reference 10870 or fully-qualified URI. Relative Reference should be used along with the di parameter to make it 10871 unique.", 10872 "format": "uri", 10873 "maxLength": 256, 10874 "type": "string" 10875 }, 10876 "if": { 10877 "description": "The interface set supported by this resource", 10878 "items": { 10879 "enum": [ 10880 "oic.if.baseline", 10881 "oic.if.ll", 10882 "oic.if.b", 10883 "oic.if.rw", 10884 "oic.if.r", 10885 "oic.if.a", 10886 "oic.if.s" 10887 ], 10888 "type": "string" 10889 }, 10890 "minItems": 1, 10891 "type": "array" 10892 }, 10893 "ins": { 10894 "description": "The instance identifier for this web link in an array of web links 10895 - used in collections", 10896 "oneOf": [ 10897 { 10898 "description": "An ordinal number that is not repeated - must be unique in the 10899 collection context", 10900 "type": "integer" 10901 }, 10902 { 10903 "description": "Any unique string including a URI", 10904 "format": "uri", 10905 "maxLength": 256, 10906 "type": "string" 10907 }, 10908 { 10909 "description": "Unique identifier (UUID)", 10910 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-10911 F0-9]{12}$", 10912 "type": "string" 10913 } 10914 ] 10915 }, 10916 "p": { 10917 "description": "Specifies the framework policies on the Resource referenced by the 10918 target URI", 10919 "properties": { 10920 "bm": { 10921 "description": "Specifies the framework policies on the Resource referenced by 10922 the target URI for e.g. observable and discoverable", 10923 "type": "integer" 10924
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 263
} 10925 }, 10926 "required": [ 10927 "bm" 10928 ], 10929 "type": "object" 10930 }, 10931 "rel": { 10932 "description": "The relation of the target URI referenced by the link to the 10933 context URI", 10934 "oneOf": [ 10935 { 10936 "default": [ 10937 "hosts" 10938 ], 10939 "items": { 10940 "maxLength": 64, 10941 "type": "string" 10942 }, 10943 "minItems": 1, 10944 "type": "array" 10945 }, 10946 { 10947 "default": "hosts", 10948 "maxLength": 64, 10949 "type": "string" 10950 } 10951 ] 10952 }, 10953 "rt": { 10954 "description": "Resource Type", 10955 "items": { 10956 "maxLength": 64, 10957 "type": "string" 10958 }, 10959 "minItems": 1, 10960 "type": "array" 10961 }, 10962 "title": { 10963 "description": "A title for the link relation. Can be used by the UI to provide a 10964 context", 10965 "maxLength": 64, 10966 "type": "string" 10967 }, 10968 "type": { 10969 "default": "application/cbor", 10970 "description": "A hint at the representation of the resource referenced by the 10971 target URI. This represents the media types that are used for both accepting and emitting", 10972 "items": { 10973 "maxLength": 64, 10974 "type": "string" 10975 }, 10976 "minItems": 1, 10977 "type": "array" 10978 } 10979 }, 10980 "required": [ 10981 "href", 10982 "rt", 10983 "if" 10984 ], 10985 "type": "string" 10986 }, 10987 "n": { 10988 "description": "Used to name the Scene collection", 10989 "type": "string" 10990 }, 10991 "rt": { 10992 "description": "Resource Type", 10993 "items": { 10994 "maxLength": 64, 10995
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 264
"type": "string" 10996 }, 10997 "minItems": 1, 10998 "readOnly": true, 10999 "type": "array" 11000 } 11001 }, 11002 "required": [ 11003 "link" 11004 ], 11005 "type": "object" 11006 } 11007 11008 , 11009 "SceneCollection" : 11010 { 11011 "properties": { 11012 "id": { 11013 "description": "A unique string that could be a hash or similarly unique", 11014 "type": "string" 11015 }, 11016 "if": { 11017 "description": "The interface set supported by this resource", 11018 "items": { 11019 "enum": [ 11020 "oic.if.baseline", 11021 "oic.if.ll", 11022 "oic.if.b", 11023 "oic.if.lb", 11024 "oic.if.rw", 11025 "oic.if.r", 11026 "oic.if.a", 11027 "oic.if.s" 11028 ], 11029 "type": "string" 11030 }, 11031 "minItems": 1, 11032 "readOnly": true, 11033 "type": "array" 11034 }, 11035 "lastScene": { 11036 "description": "Last selected Scene, shall be part of sceneValues", 11037 "type": "string" 11038 }, 11039 "links": { 11040 "description": "Array of OIC web links that are reference from this collection", 11041 "items": { 11042 "allOf": [ 11043 { 11044 "properties": { 11045 "anchor": { 11046 "description": "This is used to override the context URI e.g. override the 11047 URI of the containing collection", 11048 "format": "uri", 11049 "maxLength": 256, 11050 "type": "string" 11051 }, 11052 "di": { 11053 "description": "Unique identifier for device (UUID)", 11054 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-11055 fA-F0-9]{12}$", 11056 "type": "string" 11057 }, 11058 "eps": { 11059 "description": "the Endpoint information of the target Resource", 11060 "items": { 11061 "properties": { 11062 "ep": { 11063 "description": "URI with Transport Protocol Suites + Endpoint Locator 11064 as specified in 10.2.1", 11065 "format": "uri", 11066
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 265
"type": "string" 11067 }, 11068 "pri": { 11069 "description": "The priority among multiple Endpoints as specified in 11070 10.2.3", 11071 "minimum": 1, 11072 "type": "integer" 11073 } 11074 }, 11075 "type": "object" 11076 }, 11077 "type": "array" 11078 }, 11079 "href": { 11080 "description": "This is the target URI, it can be specified as a Relative 11081 Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to 11082 make it unique.", 11083 "format": "uri", 11084 "maxLength": 256, 11085 "type": "string" 11086 }, 11087 "if": { 11088 "description": "The interface set supported by this resource", 11089 "items": { 11090 "enum": [ 11091 "oic.if.baseline", 11092 "oic.if.ll", 11093 "oic.if.b", 11094 "oic.if.rw", 11095 "oic.if.r", 11096 "oic.if.a", 11097 "oic.if.s" 11098 ], 11099 "type": "string" 11100 }, 11101 "minItems": 1, 11102 "type": "array" 11103 }, 11104 "ins": { 11105 "description": "The instance identifier for this web link in an array of web 11106 links - used in collections", 11107 "oneOf": [ 11108 { 11109 "description": "An ordinal number that is not repeated - must be unique 11110 in the collection context", 11111 "type": "integer" 11112 }, 11113 { 11114 "description": "Any unique string including a URI", 11115 "format": "uri", 11116 "maxLength": 256, 11117 "type": "string" 11118 }, 11119 { 11120 "description": "Unique identifier (UUID)", 11121 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-11122 [a-fA-F0-9]{12}$", 11123 "type": "string" 11124 } 11125 ] 11126 }, 11127 "p": { 11128 "description": "Specifies the framework policies on the Resource referenced 11129 by the target URI", 11130 "properties": { 11131 "bm": { 11132 "description": "Specifies the framework policies on the Resource 11133 referenced by the target URI for e.g. observable and discoverable", 11134 "type": "integer" 11135 } 11136 }, 11137
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 266
"required": [ 11138 "bm" 11139 ], 11140 "type": "object" 11141 }, 11142 "rel": { 11143 "description": "The relation of the target URI referenced by the link to the 11144 context URI", 11145 "oneOf": [ 11146 { 11147 "default": [ 11148 "hosts" 11149 ], 11150 "items": { 11151 "maxLength": 64, 11152 "type": "string" 11153 }, 11154 "minItems": 1, 11155 "type": "array" 11156 }, 11157 { 11158 "default": "hosts", 11159 "maxLength": 64, 11160 "type": "string" 11161 } 11162 ] 11163 }, 11164 "rt": { 11165 "description": "Resource Type", 11166 "items": { 11167 "maxLength": 64, 11168 "type": "string" 11169 }, 11170 "minItems": 1, 11171 "type": "array" 11172 }, 11173 "title": { 11174 "description": "A title for the link relation. Can be used by the UI to 11175 provide a context", 11176 "maxLength": 64, 11177 "type": "string" 11178 }, 11179 "type": { 11180 "default": "application/cbor", 11181 "description": "A hint at the representation of the resource referenced by 11182 the target URI. This represents the media types that are used for both accepting and emitting", 11183 "items": { 11184 "maxLength": 64, 11185 "type": "string" 11186 }, 11187 "minItems": 1, 11188 "type": "array" 11189 } 11190 }, 11191 "required": [ 11192 "href", 11193 "rt", 11194 "if" 11195 ], 11196 "type": "object" 11197 }, 11198 { 11199 "required": [ 11200 "ins" 11201 ] 11202 } 11203 ] 11204 }, 11205 "type": "array" 11206 }, 11207 "n": { 11208
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 267
"description": "Used to name the Scene collection", 11209 "type": "string" 11210 }, 11211 "rt": { 11212 "description": "Resource Type", 11213 "items": { 11214 "maxLength": 64, 11215 "type": "string" 11216 }, 11217 "minItems": 1, 11218 "readOnly": true, 11219 "type": "array" 11220 }, 11221 "rts": { 11222 "description": "Defines the list of allowable resource types in links included in the 11223 collection; new links being created can only be from this list", 11224 "items": { 11225 "maxLength": 64, 11226 "type": "string" 11227 }, 11228 "minItems": 1, 11229 "readOnly": true, 11230 "type": "array" 11231 }, 11232 "sceneValues": { 11233 "description": "All available scene values", 11234 "readOnly": true, 11235 "type": "string" 11236 } 11237 }, 11238 "required": [ 11239 "lastScene", 11240 "sceneValues", 11241 "rts", 11242 "id" 11243 ], 11244 "type": "object" 11245 } 11246 11247 , 11248 "SceneCollectionUpdate" : 11249 { 11250 "properties": { 11251 "id": { 11252 "description": "A unique string that could be a hash or similarly unique", 11253 "type": "string" 11254 }, 11255 "if": { 11256 "description": "The interface set supported by this resource", 11257 "items": { 11258 "enum": [ 11259 "oic.if.baseline", 11260 "oic.if.ll", 11261 "oic.if.b", 11262 "oic.if.lb", 11263 "oic.if.rw", 11264 "oic.if.r", 11265 "oic.if.a", 11266 "oic.if.s" 11267 ], 11268 "type": "string" 11269 }, 11270 "minItems": 1, 11271 "readOnly": true, 11272 "type": "array" 11273 }, 11274 "lastScene": { 11275 "description": "Last selected Scene, shall be part of sceneValues", 11276 "type": "string" 11277 }, 11278 "links": { 11279
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 268
"description": "Array of OIC web links that are reference from this collection", 11280 "items": { 11281 "allOf": [ 11282 { 11283 "properties": { 11284 "anchor": { 11285 "description": "This is used to override the context URI e.g. override the 11286 URI of the containing collection", 11287 "format": "uri", 11288 "maxLength": 256, 11289 "type": "string" 11290 }, 11291 "di": { 11292 "description": "Unique identifier for device (UUID)", 11293 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-11294 fA-F0-9]{12}$", 11295 "type": "string" 11296 }, 11297 "eps": { 11298 "description": "the Endpoint information of the target Resource", 11299 "items": { 11300 "properties": { 11301 "ep": { 11302 "description": "URI with Transport Protocol Suites + Endpoint Locator 11303 as specified in 10.2.1", 11304 "format": "uri", 11305 "type": "string" 11306 }, 11307 "pri": { 11308 "description": "The priority among multiple Endpoints as specified in 11309 10.2.3", 11310 "minimum": 1, 11311 "type": "integer" 11312 } 11313 }, 11314 "type": "object" 11315 }, 11316 "type": "array" 11317 }, 11318 "href": { 11319 "description": "This is the target URI, it can be specified as a Relative 11320 Reference or fully-qualified URI. Relative Reference should be used along with the di parameter to 11321 make it unique.", 11322 "format": "uri", 11323 "maxLength": 256, 11324 "type": "string" 11325 }, 11326 "if": { 11327 "description": "The interface set supported by this resource", 11328 "items": { 11329 "enum": [ 11330 "oic.if.baseline", 11331 "oic.if.ll", 11332 "oic.if.b", 11333 "oic.if.rw", 11334 "oic.if.r", 11335 "oic.if.a", 11336 "oic.if.s" 11337 ], 11338 "type": "string" 11339 }, 11340 "minItems": 1, 11341 "type": "array" 11342 }, 11343 "ins": { 11344 "description": "The instance identifier for this web link in an array of web 11345 links - used in collections", 11346 "oneOf": [ 11347 { 11348 "description": "An ordinal number that is not repeated - must be unique 11349 in the collection context", 11350
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 269
"type": "integer" 11351 }, 11352 { 11353 "description": "Any unique string including a URI", 11354 "format": "uri", 11355 "maxLength": 256, 11356 "type": "string" 11357 }, 11358 { 11359 "description": "Unique identifier (UUID)", 11360 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-11361 [a-fA-F0-9]{12}$", 11362 "type": "string" 11363 } 11364 ] 11365 }, 11366 "p": { 11367 "description": "Specifies the framework policies on the Resource referenced 11368 by the target URI", 11369 "properties": { 11370 "bm": { 11371 "description": "Specifies the framework policies on the Resource 11372 referenced by the target URI for e.g. observable and discoverable", 11373 "type": "integer" 11374 } 11375 }, 11376 "required": [ 11377 "bm" 11378 ], 11379 "type": "object" 11380 }, 11381 "rel": { 11382 "description": "The relation of the target URI referenced by the link to the 11383 context URI", 11384 "oneOf": [ 11385 { 11386 "default": [ 11387 "hosts" 11388 ], 11389 "items": { 11390 "maxLength": 64, 11391 "type": "string" 11392 }, 11393 "minItems": 1, 11394 "type": "array" 11395 }, 11396 { 11397 "default": "hosts", 11398 "maxLength": 64, 11399 "type": "string" 11400 } 11401 ] 11402 }, 11403 "rt": { 11404 "description": "Resource Type", 11405 "items": { 11406 "maxLength": 64, 11407 "type": "string" 11408 }, 11409 "minItems": 1, 11410 "type": "array" 11411 }, 11412 "title": { 11413 "description": "A title for the link relation. Can be used by the UI to 11414 provide a context", 11415 "maxLength": 64, 11416 "type": "string" 11417 }, 11418 "type": { 11419 "default": "application/cbor", 11420 "description": "A hint at the representation of the resource referenced by 11421
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 270
the target URI. This represents the media types that are used for both accepting and emitting", 11422 "items": { 11423 "maxLength": 64, 11424 "type": "string" 11425 }, 11426 "minItems": 1, 11427 "type": "array" 11428 } 11429 }, 11430 "required": [ 11431 "href", 11432 "rt", 11433 "if" 11434 ], 11435 "type": "object" 11436 }, 11437 { 11438 "required": [ 11439 "ins" 11440 ] 11441 } 11442 ] 11443 }, 11444 "type": "array" 11445 }, 11446 "n": { 11447 "description": "Used to name the Scene collection", 11448 "type": "string" 11449 }, 11450 "rt": { 11451 "description": "Resource Type", 11452 "items": { 11453 "maxLength": 64, 11454 "type": "string" 11455 }, 11456 "minItems": 1, 11457 "readOnly": true, 11458 "type": "array" 11459 }, 11460 "rts": { 11461 "description": "Defines the list of allowable resource types in links included in the 11462 collection; new links being created can only be from this list", 11463 "items": { 11464 "maxLength": 64, 11465 "type": "string" 11466 }, 11467 "minItems": 1, 11468 "readOnly": true, 11469 "type": "array" 11470 }, 11471 "sceneValues": { 11472 "description": "All available scene values", 11473 "readOnly": true, 11474 "type": "string" 11475 } 11476 }, 11477 "required": [ 11478 "lastScene" 11479 ], 11480 "type": "object" 11481 } 11482 11483 } 11484 } 11485 11486
E.12.5 Property Definition 11487
Property name Value type Mandatory Access mode Description
lastScene string yes Last selected Scene, shall be
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 271
part of sceneValues
sceneValues string Read Only All available scene values
n string Used to name the Scene collection
rts array: see schema
Read Only Defines the list of allowable resource types in links included in the collection; new links being created can only be from this list
rt array: see schema
Read Only Resource Type
links array: see schema
Array of OIC web links that are reference from this collection
id string A unique string that could be a hash or similarly unique
if array: see schema
Read Only The interface set supported by this resource
lastScene string yes Last selected Scene, shall be part of sceneValues
sceneValues string yes Read Only All available scene values
n string Used to name the Scene collection
rts array: see schema
yes Read Only Defines the list of allowable resource types in links included in the collection; new links being created can only be from this list
rt array: see schema
Read Only Resource Type
links array: see schema
Array of OIC web links that are reference from this collection
id string yes A unique string that could be a hash or similarly unique
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 272
if array: see schema
Read Only The interface set supported by this resource
ins multiple types: see schema
The instance identifier for this web link in an array of web links - used in collections
type array: see schema
A hint at the representation of the resource referenced by the target URI. This represents the media types that are used for both accepting and emitting
n string Read Only Friendly name of the resource
rt array: see schema
yes Resource Type
id string Read Only Instance ID of this specific resource
drel string When specified this is the default relationship to use when an OIC Link does not specify an explicit relationship with *rel* parameter
rel multiple types: see schema
The relation of the target URI referenced by the link to the context URI
di string Unique identifier for device (UUID)
anchor string This is used to override the context URI e.g. override the URI of the containing collection
href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI. Relative
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 273
Reference should be used along with the di parameter to make it unique.
eps array: see schema
the Endpoint information of the target Resource
rts array: see schema
Read Only Defines the list of allowable resource types (for Target and anchors) in links included in the collection; new links being created can only be from this list
p object: see schema
Specifies the framework policies on the Resource referenced by the target URI
links multiple types: see schema
All forms of links in a collection
title string A title for the link relation. Can be used by the UI to provide a context
if array: see schema
yes The interface set supported by this resource
SceneMappings array: see schema
array of mappings per scene, can be 1
n string Used to name the Scene collection
link string yes web link that points at a resource
rt array: see schema
Read Only Resource Type
id string Can be an value that is unique to the use context or a UUIDv4
if array: see schema
Read Only The interface set supported by this resource
E.12.6 CRUDN behavior 11488
Resource Create Read Update Delete Notify
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 274
/SceneListResURI get
Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 275
11489