OCF Core Specifiation - Open Connectivity Foundation … D.2.7 Referenced JSON schemas ..... 140 167...

CONTACT [email protected]

Copyright Open Connectivity Foundation, Inc. © 2016-2017.

All Rights Reserved.

OCF Core Specifiation

VERSION 1.0.0 | June 2017Part 1

mailto:[email protected]

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


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


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


RETRIEVE response ..................................................................................... 64 74

8.4 UPDATE ............................................................................................................... 64 75

UPDATE request ........................................................................................... 65 76


UPDATE response ........................................................................................ 65 78

8.5 DELETE ............................................................................................................... 65 79

DELETE request ........................................................................................... 66 80


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


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


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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.6 CRUDN behavior ......................................................................................... 195 282


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.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.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.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.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.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.6 CRUDN behavior ......................................................................................... 232 324

E.9 Ping .................................................................................................................... 232 325

E.9.1 Introduction ................................................................................................. 232 326


E.9.2 Wellknown URI ............................................................................................ 233 327

E.9.3 Resource Type ............................................................................................ 233 328



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.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.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.6 CRUDN behavior ......................................................................................... 273 352

353

354


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


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


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


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


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


IETF RFC 3986, Uniform Resource Identifier (URI): General Syntax, January 2005 . 486


IETF RFC 4122, A Universally Unique IDentifier (UUID) URN Namespace , July 2005 488


IETF RFC 4287, The Atom Syndication Format, December 2005, 490


IETF RFC 4193, Unique Local IPv6 Unicast Addresses , October 2005 492


IETF RFC 4291, IP Version 6 Addressing Architecture, February 2006 494


IETF RFC 4443, Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 496

(IPv6) Specification, March 2006 497


https://tools.ietf.org/rfc/rfc1981.txt

https://tools.ietf.org/rfc/rfc2460.txt

http://www.ietf.org/rfc/rfc2616.txt









IETF RFC 4861, Neighbor Discovery for IP version 6 (IPv6) , September 2007 499


IETF RFC 4862, IPv6 Stateless Address Autoconfiguration , September 2007 501


IETF RFC 4941, Privacy Extensions for Stateless Address Autoconfiguration in IPv6 , September 503

2007 504


IETF RFC 4944, Transmission of IPv6 Packets over IEEE 802.15.4 Networks , September 2007 506


IETF RFC 5646, Tags for Identifying Languages, September 2009 508


IETF RFC 5988, Web Linking: General Syntax, October 2010 510


IETF RFC 6434, IPv6 Node Requirements, December 2011 512


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


IETF RFC 6690, Constrained RESTful Environments (CoRE) Link Format , August 2012 518


IETF RFC 6762, Multicast DNS February 2013 520


IETF RFC 6763, DNS-Based Service Discovery , February 2013 522


IETF RFC 6775, Neighbor Discovery Optimization for IPv6 over Low-Power Wireless Personal 524

Area Networks (6LoWPANs), November 2012 525


IETF RFC 7049, Concise Binary Object Representation (CBOR) , October 2013 527


IETF RFC 7084, Basic Requirements for IPv6 Customer Edge Routers, November 2013 529


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







https://www.ietf.org/rfc/rfc6455.txt








http://www/ietf.org/rfc/rfc7159.txt

http://tools.ietf.org/rfc/rfc7252.txt

https://tools.ietf.org/html/rfc7301


IETF RFC 7428, Transmission of IPv6 Packets over ITU-T G.9959 Networks, February 2015 538


IETF RFC 7641, Observing Resources in the Constrained Application Protocol 540

(CoAP), September 2015 541


IETF RFC 7668, IPv6 over BLUETOOTH(r) Low Energy, October 2015 543


IETF RFC 7721, Security and Privacy Considerations for IPv6 Address Generation Mechanisms , 545

March 20016 546


IETF RFC 7959, Block-Wise Transfers in the Constrained Application Protocol (CoAP) , August 548

2016 549


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






http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf

http://www.iana.org/assignments/ipv6-multicast-addresses/ipv6-multicast-addresses.xhtml

http://www.iana.org/assignments/media-types/media-types.xhtml


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

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

http://www.w3.org/TR/2008/REC-xml-20081126/#syntax


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


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


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


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.


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


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


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


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


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


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


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


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


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


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


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


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


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


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


Value type

Value rule Unit Access mode


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


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


Value type Value rule Unit Access mode


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


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


Value type

Value rule

Unit Access mode


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"]

}


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


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


Value type

Value rule

Unit Access mode


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


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


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"],


"eps":[

{"ep": "coaps://[2001:db8:a::b1d4]:55555"}]

},

{




"eps": [{"ep":

"coaps://[2001:db8:a::b1d4]:55555"}]

},

{

"href": "/my/fan/1",



"eps":[

{"ep": "coaps://[2001:db8:a::b1d4]:55555"}]

{

"href": "/his/fan/2",



"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


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


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"]},


{"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

{


"ins": "light-1",


"value": false

}

/the/light/2

{


"ins": :"light-2",


"value": true

}

/the/fan/1

{


"ins": "fan-1",


"value": true


}

/the/fan/2

{


"ins": "fan-2",


"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"}

},

{


"rep": {"value": false}

},


{


"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

[

{


"rep": {

"value": false

}


(UPDATE has POST semantics)

},

{


"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


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": "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": "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,


"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


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


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


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

http://www.iana.org/assignments/link-relations/link-relations.xhtml


“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


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}

}


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


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",


"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


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


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",



"type": ["application/cbor"]

}

]

}

IRI/URI (resource)

Properties (resource)

Parameters (link)


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


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


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


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


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


to: URI of the resource the Client is targeting 1809

ri: Identifier of the RETRIEVE request 1810

op: RETRIEVE 1811


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



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


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


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


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



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


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


to: URI of the target resource which is the target of deletion 1869

ri: Identifier of the DELETE request 1870

op: DELETE 1871


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



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


to: URI of the Resource target of the NOTIFICATION message 1893


ri: Identifier included in the CREATE request 1894

op: NOTIFY 1895

cn: The updated state of the resource 1896

9 Network and connectivity 1897


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


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


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


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


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


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",



"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


2044

[

{

"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",

"href": "/oic/res",

"rel": "self",



"p": {"bm": 3},

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:55555"},

{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]

},

{


"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"}]

},

{


"href": "/oic/p",

"rt": ["oic.wk.p"],


"p": {"bm": 3},

"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}]

},

{


"href": "/mySecureMode",

"rt": ["oic.r.securemode"],

"if": ["oic.if.rw", "oic.if.baseline"],

"p": {"bm": 3},


},

{


"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"}]

},

{


"href": "/oic/sec/pstat",

"rt": ["oic.r.pstat"],


"p": {"bm": 1},


},

{


"href": "/oic/sec/cred",

"rt": ["oic.r.cred"],


"p": {"bm": 1},



},

{


"href": "/oic/sec/acl2",

"rt": ["oic.r.acl2"],


"p": {"bm": 1},


},

{


"href": "/myIntrospection",

"rt": ["oic.wk.introspection"],


"p": {"bm": 3},


},

{

"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989",

"href": "/oic/res",



"p": {"bm": 3},

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"},

{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]

},

{


"href": "/oic/d",

"rt": ["oic.wk.d", "oic.d.light", "oic.d.virtual"],


"p": {"bm": 3},

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"},

{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]

},

{


"href": "/oic/p",

"rt": ["oic.wk.p"],


"p": {"bm": 3},


},

{


"href": "/myLight",



"p": {"bm": 3},


},

{





"p": {"bm": 1},

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"},

{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]

},

{






"p": {"bm": 1},


}, {





"p": {"bm": 1},


},

{





"p": {"bm": 1},


},

{


"href": "/myLightIntrospection",



"p": {"bm": 3},


},

{

"anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49",

"href": "/oic/res",



"p": {"bm": 3},

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"},

{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]

},

{


"href": "/oic/d",

"rt": ["oic.wk.d", "oic.d.fan", "oic.d.virtual"],


"p": {"bm": 3},

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"},

{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]

},

{


"href": "/oic/p",

"rt": ["oic.wk.p"],


"p": {"bm": 3},


},

{


"href": "/myFan",



"p": {"bm": 3},



},

{





"p": {"bm": 1},

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"},

{"ep": "coaps://[2001:db8:a::b1d4]:33333"}]

},

{





"p": {"bm": 1},


},

{





"p": {"bm": 1},


},

{





"p": {"bm": 1},


},

{


"href": "/myFanIntrospection",



"p": {"bm": 3},


}

]

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


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


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


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


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


(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


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


Value type

Value rule

Unit Access mode


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


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


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


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


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



“/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


2233

Table 18 defines “oic.wk.res” Resource Type. 2234

Table 18. “oic.wk.res” Resource Type definition 2235


Value type

Value rule

Unit Access mode


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


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


Value type

Value rule

Unit Access mode


(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


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.


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


Value type

Value rule

Unit Access mode


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.


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


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


"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


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


"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


"p": {"bm": 3}, 2394

"eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2395

{"ep": "coaps://[fe80::b1d6]:11111"} 2396

] 2397

}, 2398

{ 2399

"href": "/oic/d", 2400




"p": {"bm": 3}, 2404

"eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2405

{"ep": "coaps://[fe80::b1d6]:11111"} 2406

] 2407

}, 2408

{ 2409

"href": "/myLight", 2410




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


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



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)


“/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


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


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


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


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


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

http://www.teamquest.com/import/pdfs/whitepaper/ldavg1.pdf


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": [

{





"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}

]

},

{


"href": "/myLightBrightness",

"rt": ["oic.r.brightness"],


"p": {"bm": 3},


"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": [

{





"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"

},

{


"href": "/myLightBrightness",

"rt": ["oic.r.brightness"],



"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


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


[ 2709

{ 2710

"di": "88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2711

"links": [ 2712

{ 2713


"rel": "self", 2715

"rt": ["oic.wk.res"], 2716


"p": {"bm": 3, "sec": false, "port": 33333} 2718

}, 2719

{ 2720

"href": "/oic/d", 2721

"rt": ["oic.wk.d", "oic.d.fan"], 2722



}, 2725

{ 2726

"href": "/oic/p", 2727

"rt": ["oic.wk.p"], 2728


"p": {"bm": 3, "sec": true, "port": 33333} 2730

}, 2731

{ 2732

"href": "/myFanIntrospection", 2733

"rt": ["oic.wk.introspection"], 2734


"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



"p": {"bm": 3, "sec": true, "port": 33333} 2748

}, 2749

{ 2750

"href": "/oic/sec/doxm", 2751

"rt": ["oic.r.doxm"], 2752



}, 2755

{ 2756

"href": "/oic/sec/pstat", 2757

"rt": ["oic.r.pstat"], 2758


"p": {"bm": 1, "sec": true, "port": 33333} 2760

}, 2761

{ 2762

"href": "/oic/sec/cred", 2763

"rt": ["oic.r.cred"], 2764


"p": {"bm": 1, "sec": true, "port": 33333} 2766

}, 2767

{ 2768

"href": "/oic/sec/acl2", 2769

"rt": ["oic.r.acl2"], 2770



"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



}, 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


"p": {"bm": 3, "sec": true, "port": 22222} 2791

}, 2792

{ 2793


"href": "coaps://[2001:db8:b::c2e5]:22222/myLightSwitch", 2795



"p": {"bm": 3, "sec": true, "port": 22222} 2798

}, 2799

{ 2800


"href": "coaps://[2001:db8:b::c2e5]:22222/myLightBrightness", 2802

"rt": ["oic.r.brightness"], 2803


"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


"rel": "self", 2821

"rt": ["oic.wk.res"], 2822


"p": {"bm": 3}, 2824

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2825

{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2826

}, 2827

{ 2828


"href": "/oic/d", 2830


"rt": ["oic.wk.d", "oic.d.fan"], 2831


"p": {"bm": 3}, 2833

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2834

{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2835

}, 2836

{ 2837


"href": "/oic/p", 2839

"rt": ["oic.wk.p"], 2840


"p": {"bm": 3}, 2842

"eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2843

}, 2844

{ 2845


"href": "/myFanIntrospection", 2847

"rt": ["oic.wk.introspection"], 2848


"p": {"bm": 3}, 2850


}, 2852

{ 2853


"href": "/oic/rd", 2855

"rt": ["oic.wk.rd"], 2856


"p": {"bm": 3}, 2858


}, 2860

{ 2861


"href": "/myFanSwitch", 2863



"p": {"bm": 3}, 2866


}, 2868

{ 2869


"href": "/oic/sec/doxm", 2871

"rt": ["oic.r.doxm"], 2872


"p": {"bm": 1}, 2874

"eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2875

{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2876

}, 2877

{ 2878


"href": "/oic/sec/pstat", 2880

"rt": ["oic.r.pstat"], 2881


"p": {"bm": 1}, 2883


}, 2885

{ 2886


"href": "/oic/sec/cred", 2888

"rt": ["oic.r.cred"], 2889


"p": {"bm": 1}, 2891


}, 2893


{ 2894


"href": "/oic/sec/acl2", 2896

"rt": ["oic.r.acl2"], 2897


"p": {"bm": 1}, 2899


}, 2901

2902

{ 2903

"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2904

"href": "/oic/d", 2905



"p": {"bm": 3}, 2908

"eps": [{"ep": "coap://[2001:db8:b::c2e5]:66666"}, 2909

{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2910

}, 2911

{ 2912


"href": "/oic/p", 2914

"rt": ["oic.wk.p"], 2915


"p": {"bm": 3}, 2917

"eps": [{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2918

}, 2919

{ 2920


"href": "/myLightSwitch", 2922



"p": {"bm": 3}, 2925


}, 2927

{ 2928


"href": "/myLightBrightness", 2930

"rt": ["oic.r.brightness"], 2931


"p": {"bm": 3}, 2933


} 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


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


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



ri: Identifier included in the RETRIEVE request 2975

cn: Information resource representation as requested by the Client 2976


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



“/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


Table 26. “oic.wk.mnt” Resource Type definition 3008


Value type

Value rule

Unit Access mode


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


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


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


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


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


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


Resource 3085

The icon Resource is as defined in Table 28. 3086

Table 28. Optional Icon Core Resource 3087

URI Resource Type Title



“/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


Value type

Value rule

Unit Access mode


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


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


{ 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)


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


Value type

Value rule

Unit Access mode


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


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


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


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


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


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)


DELETE for DELETE

- Method code: DELETE (0.04)

- Request URI: an existing URI for the Resource to be deleted.


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


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


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


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


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


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


12.3 CoAP serialization over TCP 3342


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)


/oic/ping

Ping oic.wk.ping

“oic.if.rw” The resource using which a Client keeps its Connection with a Server active.

KeepAlive


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


Value type

Value rule

Unit Access mode


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


3416


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


Value type



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


Value type



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


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


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


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


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


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


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


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


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


Value type

Value rule

Unit Access mode


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.


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


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


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


"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


} 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


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


"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


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


} 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


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


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


"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


}, 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


Resource that allows for Device specific information to be configured. 4132


/example/DeviceConfigurationResURI 4134


The resource type (rt) is defined as: oic.wk.con. 4136


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



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


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


} 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


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


"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


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


"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




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



/example/DeviceConfigurationResURI get post

D.4 Platform Configuration 4414


Resource that allows for platform specific information to be configured. 4416


/example/PlatformConfigurationResURI 4418


The resource type (rt) is defined as: oic.wk.con.p. 4420


#%RAML 0.8 4422

title: OCF Platform Configuration 4423 version: v1-20160622 4424


if: 4428 enum: ["oic.if.rw"] 4429



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



responses : 4444

200: 4445


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



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


"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


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


}, 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



mnpn array: see schema

Platform names

value (mnpn)

string Platform description in the indicated language.

language (mnpn)


An RFC 5646 language tag.



/example/PlatformConfigurationResURI get post

D.5 Device 4604


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


The resource type (rt) is defined as: oic.wk.d. 4611


#%RAML 0.8 4613

title: OIC Root Device 4614 version: v1-20160622 4615

traits: 4616


- 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


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


} 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




ld array: see schema

Read Only Localized Description.

value (ld)

string Read Only Device description in the indicated language.

language (ld)


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.


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)


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



/oic/d get

D.6 Maintenance 4752


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



/oic/mnt 4760


The resource type (rt) is defined as: oic.wk.mnt. 4762


#%RAML 0.8 4764

title: Maintenance 4765 version: v1-20160622 4766




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


description: | 4789 Retrieve the maintenance action status 4790 4791

responses : 4792

200: 4793


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


"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


description: | 4838 Set the maintenance action(s) 4839 4840


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


200: 4882


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



fr boolean yes Factory Reset

rb boolean yes Reboot Action



/oic/mnt get post

D.7 Platform 4926


Known resource that is defines the platform on which an Server is hosted. Allows for platform 4928

specific information to be discovered. 4929


/oic/p 4931


The resource type (rt) is defined as: oic.wk.p. 4933



#%RAML 0.8 4935

title: Platform 4936 version: v1-20160622 4937

traits: 4938 - interface : 4939 queryParameters: 4940


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


get: 4950

description: | 4951 Retrieve the information about the Platform 4952 4953

responses : 4954

200: 4955


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


"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




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



/oic/p get

D.8 Ping 5063


The resource using which an Client keeps its Connection with an Server active. 5065


/oic/ping 5067



The resource type (rt) is defined as: oic.wk.ping. 5069


#%RAML 0.8 5071

title: Ping 5072 version: v1-20160622 5073



5079

/oic/ping: 5080

description: | 5081 The resource using which an Client keeps its Connection with an Server active. 5082 5083


get: 5085

description: | 5086 Retrieve the ping information 5087 5088

responses : 5089

200: 5090


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


"in": 16 5127 } 5128 5129

post: 5130

description: | 5131 Update or reset the alive interval 5132 5133


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


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


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



in integer Read Write Indicates the interval for which connection shall be kept alive



/oic/ping get post

D.9 Discoverable Resources Baseline Interface 5213


Baseline representation of /oic/res; list of discoverable resources 5215


/oic/res 5217


The resource type (rt) is defined as: oic.wk.res. 5219


#%RAML 0.8 5221

title: Discoverable Resources 5222 version: v1-20160622 5223


if: 5227 enum: ["oic.if.ll"] 5228



5233

/oic-res-BaselineInterfaceURI: 5234

description: | 5235


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


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


"$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




yes Read Only Resource Type

n string Read Only Human friendly name

links array: see schema

yes

mpro string Read Only Supported messaging protocols


yes Read Only The interface set supported by this resource



/oic/res get

D.10 Discoverable Resources Link List interface 5340


Link list representation of /oic/res; list of discoverable resources 5342


/oic/res 5344



The resource type (rt) is defined as: oic.wk.res. 5346


#%RAML 0.8 5348

title: Discoverable Resources 5349 version: v1-20160622 5350


if: 5354 enum: ["oic.if.ll"] 5355



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


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


{"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




yes Resource Type


Unique identifier for device (UUID)




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





bm (p)

integer yes Specifies the framework policies on the Resource referenced by the target URI for


e.g. observable and discoverable



The relation of the target URI referenced by the link to the context URI








/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


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


}, 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


Toplevel Scene resource. This resource is a generic collection resource. The rts value shall contain 5570

oic.wk.scenecollection resource types. 5571



/SceneListResURI 5573


The resource type (rt) is defined as: oic.wk.scenelist. 5575


#%RAML 0.8 5577

title: Scene 5578 version: v1-20160622 5579


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


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


"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



drel string When specified this is the default relationship to use when an OIC Link does not specify an


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


The device ID which is an UUIDv4 string; used for backward compatibility with Spec A definition of /oic/res



/SceneListResURI get

D.12 Scene Collections 5691


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


/SceneCollectionResURI 5698


The resource type (rt) is defined as: oic.wk.scenecollection. 5700


#%RAML 0.8 5702



if: 5708


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


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


} 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


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


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


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


}, 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



lastScene string yes Last selected Scene, shall be part of sceneValues


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




/SceneCollectionResURI get post

D.13 Scene Member 5944


Collection that models a scene member. 5946


/SceneMemberResURI 5948


The resource type (rt) is defined as: oic.wk.scenemember. 5950


#%RAML 0.8 5952



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


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


"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


"memberValue": true 6065 } 6066 ] 6067 } 6068 6069



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




/SceneMemberResURI get

D.14 Resource directory resource 6072


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


/oic/rd 6078


The resource type (rt) is defined as: oic.wk.rd. 6080


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


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


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


"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


} 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


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


{ 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


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


"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



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

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.



/oic/rd get post delete


D.15 Icon 6416


This resource describes the attributes associated with an Icon. 6418


/IconResURI 6420


The resource type (rt) is defined as: oic.r.icon. 6422


#%RAML 0.8 6424

title: OICIcon 6425 version: v1.1.0-20161107 6426



6432

/IconResURI: 6433

description: | 6434 This resource describes the attributes associated with an Icon. 6435 6436


get: 6438

description: | 6439 Retrieves the current icon properties. 6440 6441

responses : 6442

200: 6443


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


"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



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



/IconResURI get

D.16 Introspection Resource 6504


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


/IntrospectionResURI 6509


The resource type (rt) is defined as: oic.wk.introspection. 6511


#%RAML 0.8 6513


title: OICIntrospection 6514 version: v1.0.0-20160707 6515



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


get: 6529 responses : 6530

200: 6531


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


"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



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



/IntrospectionResURI get

6607


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


"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


}, 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


width integer yes Read Only Specifies the width in pixels


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


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


/IconResURI get


E.2 Introspection Resource 6769


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


/IntrospectionResURI 6776


The resource type (rt) is defined as: ['oic.wk.introspection']. 6778


{ 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


} 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


"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






urlInfo array: see schema

yes Read Only The valid range for the value Property







/IntrospectionResURI get

E.3 OCF Collection 6951


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


/CollectionBaselineInterfaceURI 6959


The resource type (rt) is defined as: ['oic.wk.col']. 6961


{ 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


"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


] 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


} 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


}, 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


}, 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


"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


} 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


], 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


"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


"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


}, 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


"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




All forms of links in a collection

anchor string This is used to override the context URI e.g.


override the URI of the containing collection









yes Resource Type






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


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




rep multiple types: see schema

yes

href string yes URI of the target resource relative assuming the collection URI as anchor






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




yes Resource Type









rep multiple types: see schema

yes

href string yes URI of the target resource relative assuming the collection URI as anchor



/CollectionBaselineInterfaceURI get post


E.4 Platform Configuration 7855


Resource that allows for platform specific information to be configured. 7857

Retrieves the current platform configuration settings 7858

7859


/example/PlatformConfigurationResURI 7861


The resource type (rt) is defined as: ['oic.wk.con.p']. 7863


{ 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


"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


"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


"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




Platform names








yes Platform names







n string Friendly name of the resource



/example/PlatformConfigurationResURI get post

E.5 Device Configuration 8103


Resource that allows for Device specific information to be configured. 8105

Retrieves the current Device configuration settings 8106

8107


/example/DeviceConfigurationResURI 8109


The resource type (rt) is defined as: ['oic.wk.con']. 8111


{ 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


"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


"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


"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


"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




dl string Default Language

c string Currency






Localized names

n string yes Read Only Friendly name of the resource



r string Region




dl string Default Language

c string Currency





Localized names

n string yes Friendly name of the resource



r string Region





/example/DeviceConfigurationResURI get post

E.6 Device 8421


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


The resource type (rt) is defined as: ['oic.wk.d']. 8430


{ 8432 "swagger": "2.0", 8433 "info": { 8434 "title": "Device", 8435 "version": "v1-20160622", 8436 "license": { 8437


"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


"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


"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



dmn array: see schema

Read Only Manufacturer Name.





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.



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



/oic/d get

E.7 Maintenance 8641


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


/oic/mnt 8652


The resource type (rt) is defined as: ['oic.wk.mnt']. 8654



{ 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


"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


"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





rb boolean yes Reboot Action





fr boolean Factory Reset



/oic/mnt get post

E.8 Platform 8828


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


/oic/p 8835



The resource type (rt) is defined as: ['oic.wk.p']. 8837


{ 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


"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


}, 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






mnmo string Read Only Model number as designated by manufacturer

mnpv string Read Only Platform Version


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



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




/oic/p get

E.9 Ping 9034


The resource using which an Client keeps its Connection with an Server active. 9036

Retrieve the ping information 9037



/oic/ping 9039


The resource type (rt) is defined as: ['oic.wk.ping']. 9041


{ 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


} 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


"readOnly": true, 9176 "type": "array" 9177 } 9178 }, 9179 "required": [ 9180 "in" 9181 ], 9182 "type": "object" 9183 } 9184 9185 } 9186 } 9187 9188








in integer yes Read Write Indicates the interval for which connection shall be kept alive




/oic/ping get post

E.10 Resource directory resource 9191


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


/oic/rd 9200


The resource type (rt) is defined as: ['oic.wk.rd']. 9202


{ 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


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


"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


"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


"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


"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


"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


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


"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





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


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






di string A unique identifier for the publishing Device, i.e., its device ID


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








/oic/rd get post delete

E.11 Discoverable Resources 9739


Retrieve the discoverable resource set. 9741

9742


/oic/res 9744



{ 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


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


"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


}, 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


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


"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


"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


{ 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




yes

mpro string Read Only Supported messaging protocols






n string Read Only Human friendly name








yes Resource Type








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.





/oic-res-llInterfaceURI

get

E.12 Scenes 10243


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


/SceneListResURI 10251


The resource types (rt) are defined as: 10253

['oic.wk.scenelist',’oic.wk.scenemember’,’oic.wk.scenecollection’]. 10254


{ 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


"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


"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


"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


"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


}, 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


{ 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


"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


"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


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


} 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


"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


"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


"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


"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


"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


"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


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



lastScene string yes Last selected Scene, shall be


part of sceneValues

sceneValues string Read Only All available scene values



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





id string A unique string that could be a hash or similarly unique



lastScene string yes Last selected Scene, shall be part of sceneValues

sceneValues string yes Read Only All available scene values



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





id string yes A unique string that could be a hash or similarly unique










yes Resource Type


drel string When specified this is the default relationship to use when an OIC Link does not specify an explicit relationship with *rel* parameter





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.




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




All forms of links in a collection




SceneMappings array: see schema

array of mappings per scene, can be 1


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






/SceneListResURI get


11489

OCF Core Specifiation - Open Connectivity Foundation … D.2.7 Referenced JSON schemas ..... 140 167...

Documents

Transcript of OCF Core Specifiation - Open Connectivity Foundation … D.2.7 Referenced JSON schemas ..... 140 167...