OCF Core specification v1.3...1) 3) 7)

Copyright Open Connectivity Foundation, Inc. © 2016-2017. All rights Reserved 1

1

OCF CORE SPECIFICATION V1.3.0

Part 1

Open Connectivity Foundation (OCF) [email protected]


Legal Disclaimer 2 3

THIS IS A DRAFT SPECIFICATION ONLY AND HAS NOT BEEN ADOPTED BY THE OPEN 4 CONNECTIVITY FOUNDATION. THIS DRAFT SPECIFICATION MAY NOT BE RELIED UPON 5 FOR ANY PURPOSE OTHER THAN REVIEW OF THE CURRENT STATE OF THE 6 DEVELOPMENT OF THIS DRAFT SPECIFICATION. THE OPEN CONNECTIVITY FOUNDATION 7 AND ITS MEMBERS RESERVE THE RIGHT WITHOUT NOTICE TO YOU TO CHANGE ANY OR 8 ALL PORTIONS HEREOF, DELETE PORTIONS HEREOF, MAKE ADDITIONS HERETO, 9 DISCARD THIS DRAFT SPECIFICATION IN ITS ENTIRETY OR OTHERWISE MODIFY THIS 10 DRAFT SPECIFICATION AT ANY TIME. YOU SHOULD NOT AND MAY NOT RELY UPON THIS 11 DRAFT SPECIFICATION IN ANY WAY, INCLUDING BUT NOT LIMITED TO THE DEVELOPMENT 12 OF ANY PRODUCTS OR SERVICES. IMPLEMENTATION OF THIS DRAFT SPECIFICATION IS 13 DONE AT YOUR OWN RISK AMEND AND IT IS NOT SUBJECT TO ANY LICENSING GRANTS 14 OR COMMITMENTS UNDER THE OPEN CONNECTIVITY FOUNDATION INTELLECTUAL 15 PROPERTY RIGHTS POLICY OR OTHERWISE. IN CONSIDERATION OF THE OPEN 16 CONNECTIVITY FOUNDATION GRANTING YOU ACCESS TO THIS DRAFT SPECIFICATION, 17 YOU DO HEREBY WAIVE ANY AND ALL CLAIMS ASSOCIATED HEREWITH INCLUDING BUT 18 NOT LIMITED TO THOSE CLAIMS DISCUSSED BELOW, AS WELL AS CLAIMS OF 19 DETRIMENTAL RELIANCE. 20

The OCF logo is a trademark of Open Connectivity Foundation, Inc. in the United States or other 21 countries. *Other names and brands may be claimed as the property of others. 22

Copyright © 2016-17 Open Connectivity Foundation, Inc. All rights reserved. 23

Copying or other form of reproduction and/or distribution of these works are strictly prohibited 24

25


CONTENTS 26

27

1 Scope ........................................................................................................................... 16 28

2 Normative references .................................................................................................... 16 29

3 Terms, definitions, symbols and abbreviations .............................................................. 19 30

3.1 Terms and definitions ........................................................................................... 19 31

3.2 Symbols and abbreviations ................................................................................... 22 32

3.3 Conventions ......................................................................................................... 23 33

3.4 Data types ............................................................................................................ 23 34

4 Document conventions and organization ....................................................................... 24 35

5 Architecture................................................................................................................... 25 36

5.1 Overview .............................................................................................................. 25 37

5.2 Principle ............................................................................................................... 26 38

5.3 Functional block diagram ...................................................................................... 28 39

5.4 Framework ........................................................................................................... 29 40

5.5 Example Scenario with roles ................................................................................. 29 41

5.6 Example Scenario: Bridging to Non- OCF ecosystem............................................ 30 42

5.7 OCF Cloud architecture ........................................................................................ 31 43

6 Identification and addressing ......................................................................................... 33 44

6.1 Introduction .......................................................................................................... 33 45

6.2 Identification ......................................................................................................... 33 46

6.2.1 Resource identification and addressing ......................................................... 33 47

6.3 Namespace: ......................................................................................................... 35 48

6.4 Network addressing .............................................................................................. 35 49

7 Resource model ............................................................................................................ 35 50

7.1 Introduction .......................................................................................................... 35 51

7.2 Resource .............................................................................................................. 36 52

7.3 Property ............................................................................................................... 36 53

7.3.1 Introduction ................................................................................................... 36 54

7.3.2 Common Properties ....................................................................................... 37 55

7.4 Resource Type ..................................................................................................... 39 56

7.4.1 Introduction ................................................................................................... 39 57

7.4.2 Resource Type Property ................................................................................ 39 58

7.4.3 Resource Type definition ............................................................................... 40 59

7.4.4 Multi-value "rt" Resource ............................................................................... 41 60

7.5 Device Type ......................................................................................................... 41 61

7.6 Interface ............................................................................................................... 42 62

7.6.1 Introduction ................................................................................................... 42 63

7.6.2 Interface Property ......................................................................................... 42 64

7.6.3 Interface methods ......................................................................................... 43 65

7.7 Resource representation ...................................................................................... 57 66

7.8 Structure .............................................................................................................. 57 67

7.8.1 Introduction ................................................................................................... 57 68


7.8.2 Resource Relationships ................................................................................. 57 69

7.8.3 Collections .................................................................................................... 62 70

7.9 Third (3rd) party specified extensions .................................................................... 64 71

7.10 Query Parameters ................................................................................................ 65 72

7.10.1 Introduction ................................................................................................... 65 73

7.10.2 Use of multiple parameters within a query ..................................................... 65 74

7.10.3 Application to multi-value “rt” Resources ....................................................... 66 75

7.10.4 Interface specific considerations for queries .................................................. 66 76

8 CRUDN ......................................................................................................................... 67 77

8.1 Overview .............................................................................................................. 67 78

8.2 CREATE ............................................................................................................... 67 79

8.2.1 CREATE request ........................................................................................... 68 80

8.2.2 Processing by the Server .............................................................................. 68 81

8.2.3 CREATE response ........................................................................................ 68 82

8.3 RETRIEVE ........................................................................................................... 68 83

8.3.1 RETRIEVE request ........................................................................................ 69 84


8.3.3 RETRIEVE response ..................................................................................... 69 86

8.4 UPDATE ............................................................................................................... 69 87

8.4.1 UPDATE request ........................................................................................... 70 88


8.4.3 UPDATE response ........................................................................................ 70 90

8.5 DELETE ............................................................................................................... 70 91

8.5.1 DELETE request ........................................................................................... 71 92


8.5.3 DELETE response ......................................................................................... 71 94

8.6 NOTIFY ................................................................................................................ 71 95

9 Network and connectivity .............................................................................................. 72 96

9.1 Introduction .......................................................................................................... 72 97

9.2 Architecture .......................................................................................................... 72 98

9.3 IPv6 network layer requirements ........................................................................... 73 99

9.3.1 Introduction ................................................................................................... 73 100

9.3.2 IPv6 node requirements ................................................................................ 74 101

10 Endpoint ....................................................................................................................... 74 102

10.1 Endpoint definition ................................................................................................ 74 103

10.2 Endpoint information ............................................................................................. 75 104

10.2.1 Introduction ................................................................................................... 75 105

10.2.2 “ep” ............................................................................................................... 75 106

10.2.3 “pri” ............................................................................................................... 75 107

10.2.4 Endpoint information in "eps" Parameter ....................................................... 76 108

10.3 Endpoint discovery ............................................................................................... 76 109

10.3.1 Introduction ................................................................................................... 76 110

10.3.2 Implicit discovery ........................................................................................... 76 111

10.3.3 Explicit discovery with “/oic/res” response ..................................................... 76 112


10.4 CoAP based Endpoint discovery ........................................................................... 80 113

11 Functional interactions .................................................................................................. 81 114

11.1 Introduction .......................................................................................................... 81 115

11.2 Onboarding, Provisioning and Configuration ......................................................... 81 116

11.3 Resource discovery .............................................................................................. 83 117

11.3.1 Introduction ................................................................................................... 83 118

11.3.2 Resource based discovery: mechanisms ....................................................... 83 119

11.3.3 Resource based discovery: Information publication process .......................... 85 120

11.3.4 Resource based discovery: Finding information ............................................. 86 121

11.3.5 Resource discovery using “/oic/res” ............................................................... 92 122

11.3.6 Resource directory (RD) based discovery ...................................................... 95 123

11.4 Notification ......................................................................................................... 107 124

11.4.1 Overview ..................................................................................................... 107 125

11.4.2 Observe ...................................................................................................... 107 126

11.5 Device management ........................................................................................... 109 127

11.5.1 Overview ..................................................................................................... 109 128

11.5.2 Diagnostics and maintenance ...................................................................... 109 129

11.6 Scenes ............................................................................................................... 110 130

11.6.1 Introduction ................................................................................................. 110 131

11.6.2 Scenes ........................................................................................................ 110 132

11.6.3 Security considerations ............................................................................... 114 133

11.7 Icons .................................................................................................................. 115 134

11.7.1 Overview ..................................................................................................... 115 135

11.7.2 Resource..................................................................................................... 115 136

11.8 Introspection....................................................................................................... 115 137

11.8.1 Overview ..................................................................................................... 115 138

11.8.2 Usage of introspection................................................................................. 118 139

12 Messaging................................................................................................................... 119 140

12.1 Introduction ........................................................................................................ 119 141

12.2 Mapping of CRUDN to CoAP .............................................................................. 119 142

12.2.1 Overview ..................................................................................................... 119 143

12.2.2 URIs ............................................................................................................ 119 144

12.2.3 CoAP method with request and response .................................................... 119 145

12.2.4 Content-Format negotiation ......................................................................... 121 146

12.2.5 OCF-Content-Format-Version information ................................................... 122 147

12.2.6 Content-Format policy ................................................................................. 123 148

12.2.7 CRUDN to CoAP response codes ................................................................ 123 149

12.2.8 CoAP block transfer .................................................................................... 123 150

12.3 CoAP serialization over TCP .............................................................................. 124 151

12.3.1 Introduction ................................................................................................. 124 152

12.3.2 Indication of support .................................................................................... 124 153

12.3.3 Message type and header ........................................................................... 124 154

12.3.4 URI scheme ................................................................................................ 124 155

12.3.5 KeepAlive .................................................................................................... 124 156


12.3.6 CoAP native Cloud ...................................................................................... 125 157

12.4 Payload Encoding in CBOR ................................................................................ 126 158

13 Security ....................................................................................................................... 127 159

Annex A (informative) Operation Examples ........................................................................ 128 160

A.1 Introduction ........................................................................................................ 128 161

A.2 When at home: From smartphone turn on a single light ...................................... 128 162

A.3 GroupAction execution ....................................................................................... 129 163

A.4 When garage door opens, turn on lights in hall; also notify smartphone .............. 129 164

A.5 Device management ........................................................................................... 129 165

Annex B (informative) OCF interaction scenarios and deployment models ......................... 131 166

B.1 OCF interaction scenarios .................................................................................. 131 167

B.2 Deployment model .............................................................................................. 132 168

Annex C (informative) Other Resource Models and OCF Mapping ..................................... 134 169

C.1 Multiple resource models .................................................................................... 134 170

C.2 OCF approach for support of multiple resource models....................................... 134 171

C.3 Resource model indication.................................................................................. 135 172

C.4 An Example Profile (IPSO profile) ....................................................................... 135 173

C.4.1 Conceptual equivalence .............................................................................. 135 174

Annex D (normative) Resource Type definitions ................................................................ 138 175

D.1 List of Resource Type definitions ........................................................................ 138 176

D.2 OCF Collection ................................................................................................... 139 177

D.2.1 Introduction ................................................................................................. 139 178

D.2.2 Example URI ............................................................................................... 139 179

D.2.3 Resource Type ............................................................................................ 139 180

D.2.4 RAML Definition .......................................................................................... 139 181

D.2.5 Property Definition ...................................................................................... 142 182

D.2.6 CRUDN behavior ......................................................................................... 143 183

D.2.7 Referenced JSON schemas ......................................................................... 144 184

D.2.8 oic.oic-link-schema.json .............................................................................. 144 185

D.3 Device Configuration .......................................................................................... 146 186

D.3.1 Introduction ................................................................................................. 146 187

D.3.2 Example URI ............................................................................................... 146 188

D.3.3 Resource Type ............................................................................................ 146 189



D.3.6 CRUDN behavior ......................................................................................... 151 192

D.4 Platform Configuration ........................................................................................ 151 193

D.4.1 Introduction ................................................................................................. 151 194

D.4.2 Example URI ............................................................................................... 151 195

D.4.3 Resource Type ............................................................................................ 151 196



D.4.6 CRUDN behavior ......................................................................................... 154 199

D.5 Device ................................................................................................................ 155 200


D.5.1 Introduction ................................................................................................. 155 201

D.5.2 Wellknown URI ............................................................................................ 155 202

D.5.3 Resource Type ............................................................................................ 155 203



D.5.6 CRUDN behavior ......................................................................................... 158 206

D.6 Maintenance ....................................................................................................... 158 207

D.6.1 Introduction ................................................................................................. 158 208

D.6.2 Wellknown URI ............................................................................................ 158 209

D.6.3 Resource Type ............................................................................................ 158 210



D.6.6 CRUDN behavior ......................................................................................... 161 213

D.7 Platform .............................................................................................................. 161 214

D.7.1 Introduction ................................................................................................. 161 215

D.7.2 Wellknown URI ............................................................................................ 161 216

D.7.3 Resource Type ............................................................................................ 161 217



D.7.6 CRUDN behavior ......................................................................................... 164 220

D.8 Discoverable Resources Baseline Interface ........................................................ 164 221

D.8.1 Introduction ................................................................................................. 164 222

D.8.2 Wellknown URI ............................................................................................ 164 223

D.8.3 Resource Type ............................................................................................ 164 224



D.8.6 CRUDN behavior ......................................................................................... 166 227

D.9 Discoverable Resources Link List interface ......................................................... 166 228

D.9.1 Introduction ................................................................................................. 166 229

D.9.2 Wellknown URI ............................................................................................ 166 230

D.9.3 Resource Type ............................................................................................ 166 231



D.9.6 CRUDN behavior ......................................................................................... 169 234

D.9.7 Referenced JSON schemas ......................................................................... 169 235

D.9.8 oic.oic-link-schema.json .............................................................................. 169 236

D.10 Scenes (Top level) ............................................................................................. 171 237

D.10.1 Introduction ................................................................................................. 171 238

D.10.2 Example URI ............................................................................................... 171 239

D.10.3 Resource Type ............................................................................................ 171 240



D.10.6 CRUDN behavior ......................................................................................... 173 243

D.11 Scene Collections ............................................................................................... 173 244


D.11.1 Introduction ................................................................................................. 173 245

D.11.2 Example URI ............................................................................................... 173 246

D.11.3 Resource Type ............................................................................................ 173 247



D.11.6 CRUDN behavior ......................................................................................... 176 250

D.12 Scene Member ................................................................................................... 176 251

D.12.1 Introduction ................................................................................................. 176 252

D.12.2 Example URI ............................................................................................... 176 253

D.12.3 Resource Type ............................................................................................ 176 254



D.12.6 CRUDN behavior ......................................................................................... 178 257

D.13 Resource directory resource ............................................................................... 178 258

D.13.1 Introduction ................................................................................................. 178 259

D.13.2 Wellknown URI ............................................................................................ 178 260

D.13.3 Resource Type ............................................................................................ 178 261



D.13.6 CRUDN behavior ......................................................................................... 183 264

D.14 Icon .................................................................................................................... 183 265

D.14.1 Introduction ................................................................................................. 183 266

D.14.2 Example URI ............................................................................................... 183 267

D.14.3 Resource Type ............................................................................................ 183 268



D.14.6 CRUDN behavior ......................................................................................... 185 271

D.15 Introspection Resource ....................................................................................... 185 272

D.15.1 Introduction ................................................................................................. 185 273

D.15.2 Example URI ............................................................................................... 185 274

D.15.3 Resource Type ............................................................................................ 185 275



D.15.6 CRUDN behavior ......................................................................................... 187 278

Annex E (normative) OIC 1.1 Resource Type definitions.................................................... 188 279

E.1 List of Resource Type Definitions ....................................................................... 188 280

E.2 Collection, baseline interface .............................................................................. 188 281

E.2.1 Introduction ................................................................................................. 188 282

E.2.2 Example URI ............................................................................................... 188 283

E.2.3 Resource Type ............................................................................................ 188 284

E.2.4 RAML Definition .......................................................................................... 188 285

E.2.5 Property Definition ...................................................................................... 193 286

E.2.6 CRUDN behavior ......................................................................................... 194 287

E.2.7 Referenced JSON schemas ......................................................................... 194 288


E.2.8 oic.oic-link-schema.json .............................................................................. 194 289

E.3 Collection, link list interface ................................................................................ 196 290

E.3.1 Introduction ................................................................................................. 196 291

E.3.2 Example URI ............................................................................................... 197 292

E.3.3 Resource Type ............................................................................................ 197 293



E.3.6 CRUDN behavior ......................................................................................... 199 296



E.4 Discoverable Resources, baseline interface ....................................................... 201 299

E.4.1 Introduction ................................................................................................. 201 300

E.4.2 Wellknown URI ............................................................................................ 201 301

E.4.3 Resource Type ............................................................................................ 201 302



E.4.6 CRUDN behavior ......................................................................................... 203 305

E.5 Discoverable Resources, link list interface .......................................................... 204 306

E.5.1 Introduction ................................................................................................. 204 307

E.5.2 Wellknown URI ............................................................................................ 204 308

E.5.3 Resource Type ............................................................................................ 204 309



E.5.6 CRUDN behavior ......................................................................................... 206 312



Annex F (informative) Swagger2.0 definitions ................................................................... 210 315

F.1 Icon .................................................................................................................... 210 316

F.1.1 Introduction ................................................................................................. 210 317

F.1.2 Wellknown URI ............................................................................................ 210 318

F.1.3 Resource Type ............................................................................................ 210 319

F.1.4 Swagger2.0 Definition ................................................................................. 210 320

F.1.5 Property Definition ...................................................................................... 212 321

F.1.6 CRUDN behavior ......................................................................................... 213 322

F.2 Introspection Resource ....................................................................................... 213 323

F.2.1 Introduction ................................................................................................. 213 324

F.2.2 Wellknown URI ............................................................................................ 213 325

F.2.3 Resource Type ............................................................................................ 213 326



F.2.6 CRUDN behavior ......................................................................................... 216 329

F.3 OCF Collection ................................................................................................... 216 330

F.3.1 Introduction ................................................................................................. 216 331

F.3.2 Wellknown URI ............................................................................................ 216 332


F.3.3 Resource Type ............................................................................................ 216 333



F.3.6 CRUDN behavior ......................................................................................... 232 336

F.4 Platform Configuration ........................................................................................ 232 337

F.4.1 Introduction ................................................................................................. 232 338

F.4.2 Wellknown URI ............................................................................................ 232 339

F.4.3 Resource Type ............................................................................................ 232 340



F.4.6 CRUDN behavior ......................................................................................... 236 343

F.5 Device Configuration .......................................................................................... 237 344

F.5.1 Introduction ................................................................................................. 237 345

F.5.2 Wellknown URI ............................................................................................ 237 346

F.5.3 Resource Type ............................................................................................ 237 347



F.5.6 CRUDN behavior ......................................................................................... 243 350

F.6 Device ................................................................................................................ 243 351

F.6.1 Introduction ................................................................................................. 243 352

F.6.2 Wellknown URI ............................................................................................ 243 353

F.6.3 Resource Type ............................................................................................ 243 354



F.6.6 CRUDN behavior ......................................................................................... 247 357

F.7 Maintenance ....................................................................................................... 247 358

F.7.1 Introduction ................................................................................................. 247 359

F.7.2 Wellknown URI ............................................................................................ 247 360

F.7.3 Resource Type ............................................................................................ 247 361



F.7.6 CRUDN behavior ......................................................................................... 250 364

F.8 Platform .............................................................................................................. 251 365

F.8.1 Introduction ................................................................................................. 251 366

F.8.2 Wellknown URI ............................................................................................ 251 367

F.8.3 Resource Type ............................................................................................ 251 368



F.8.6 CRUDN behavior ......................................................................................... 255 371

F.9 Resource directory resource ............................................................................... 255 372

F.9.1 Introduction ................................................................................................. 255 373

F.9.2 Wellknown URI ............................................................................................ 255 374

F.9.3 Resource Type ............................................................................................ 255 375




F.9.6 CRUDN behavior ......................................................................................... 263 378

F.10 Discoverable Resources ..................................................................................... 263 379

F.10.1 Introduction ................................................................................................. 263 380

F.10.2 Wellknown URI ............................................................................................ 263 381

F.10.3 Resource Type ............................................................................................ 263 382



F.10.6 CRUDN behavior ......................................................................................... 272 385

F.11 Scenes ............................................................................................................... 272 386

F.11.1 Introduction ................................................................................................. 272 387

F.11.2 Wellknown URI ............................................................................................ 272 388

F.11.3 Resource Type ............................................................................................ 272 389



F.11.6 CRUDN behavior ......................................................................................... 294 392

393

394


395

Figures 396 397

Figure 1: Architecture - concepts .......................................................................................... 27 398

Figure 2: Functional block diagram ....................................................................................... 28 399

Figure 3: Communication layering model .............................................................................. 29 400

Figure 4: Example illustrating the Roles ............................................................................... 30 401

Figure 5: Framework - Architecture Detail ............................................................................. 31 402

Figure 6: Server bridging to Non- OCF device ...................................................................... 31 403

Figure 7: OCF Cloud deployment architecture ...................................................................... 32 404

Figure 8: Endpoint routing .................................................................................................... 33 405

Figure 9. CREATE operation ................................................................................................ 68 406

Figure 10. RETRIEVE operation ........................................................................................... 69 407

Figure 11. UPDATE operation .............................................................................................. 70 408

Figure 12. DELETE operation ............................................................................................... 71 409

Figure 13. High Level Network & Connectivity Architecture ................................................... 73 410

Figure 14. Resource based discovery: Information publication process................................. 86 411

Figure 15. Resource based discovery: Finding information .................................................. 86 412

Figure 16. Indirect discovery of Resources by via an RD ...................................................... 95 413

Figure 17. RD discovery and RD supported query of Resources support .............................. 97 414

Figure 18. Resource Direction Deployment Scenarios .......................................................... 98 415

............................................................ 108 416

Figure 19. Observe Mechanism .......................................................................................... 108 417

Figure 20 Generic scene resource structure ....................................................................... 111 418

Figure 21 Interactions to check Scene support and setup of specific scenes ...................... 112 419

Figure 22 Client interactions on a specific scene ................................................................ 113 420

Figure 23 Interaction overview due to a Scene change ....................................................... 114 421


Figure 24 Interactions to check Introspection support and download the Introspection 422 Device Data. ....................................................................................................................... 118 423

Figure 25 Content-Format Policy ........................................................................................ 123 424

Figure 26 Resource discovery through OCF Cloud ............................................................. 125 425

Figure 27 Endpoint routing through OCF Cloud .................................................................. 126 426

Figure 28. When at home: from smartphone turn on a single light ....................................... 129 427

Figure 29. Device management (maintenance) ................................................................... 130 428

Figure 30. Direct interaction between Server and Client ..................................................... 131 429

Figure 31. Interaction between Client and Server using another Server .............................. 131 430

Figure 32. Interaction between Client and Server using Intermediary .................................. 131 431

Figure 33. Interaction between Client and Server using support from multiple Servers and 432 Intermediary ....................................................................................................................... 132 433

Figure 34. Example of Devices ........................................................................................... 132 434

435

436

437


Tables 438 439

Table 1. Additional OCF Types ............................................................................................. 24 440

Table 2. Name Property Definition ........................................................................................ 38 441

Table 3. Resource Identity Property Definition ...................................................................... 39 442

Table 4. Resource Type Common Property definition ........................................................... 39 443

Table 5. Example foobar Resource Type .............................................................................. 40 444

Table 6. Example foobar properties ...................................................................................... 40 445

Table 7. Resource Interface Property definition .................................................................... 42 446

Table 8. OCF standard Interfaces ......................................................................................... 43 447

Table 9. Common Properties for Collections (in addition to Common Properties defined in 448 section 7.3.2) ....................................................................................................................... 64 449

Table 10. 3rd party defined Resource elements ................................................................... 65 450

Table 11. Parameters of CRUDN messages ......................................................................... 67 451

Table 12. “ep” value for Transport Protocol Suite .................................................................. 75 452

Table 13. List of Core Resources ......................................................................................... 81 453

Table 14. Configuration Resource ........................................................................................ 81 454

Table 15. “oic.wk.con” Resource Type definition ................................................................... 82 455

Table 16. “oic.wk.con.p” Resource Type definition ................................................................ 83 456

Table 17. Mandatory discovery Core Resources ................................................................... 87 457

Table 18. “oic.wk.res” Resource Type definition ................................................................... 88 458

Table 19. Protocol scheme registry ....................................................................................... 89 459

Table 20. "oic.wk.d" Resource Type definition ...................................................................... 89 460

Table 21. "oic.wk.p" Resource Type definition ...................................................................... 91 461

Table 22. "oic.wk.rd" Resource Type definition ..................................................................... 96 462

Table 23. "oic.wk.rd" Properties ............................................................................................ 96 463

Table 24. Optional diagnostics and maintenance device management Core Resources ...... 109 464

Table 25. “oic.wk.mnt” Resource Type definition ................................................................. 109 465

Table 26 list of Resource Types for Scenes ........................................................................ 114 466

Table 27. Optional Icon Core Resource .............................................................................. 115 467

Table 28. “oic.r.icon” Resource Type definition ................................................................... 115 468

Table 29. Introspection Resource ....................................................................................... 117 469

Table 30. “oic.wk.introspection” Resource Type definition .................................................. 117 470

Table 31. CoAP request and response ............................................................................... 119 471

Table 32. OCF Content-Formats ......................................................................................... 122 472

Table 33. OCF-Content-Format-Version and OCF-Accept-Content-Format-Version Option 473 Numbers ............................................................................................................................. 122 474

Table 34. OCF-Accept-Content-Format-Version and OCF-Content-Format-Version 475 Representation ................................................................................................................... 122 476


Table 35. Examples of OCF-Content-Format-Version and OCF-Accept-Content-Format-477 Version Representation ...................................................................................................... 122 478

Table 36. oic.example.light Resource Type definition ......................................................... 128 479

Table 37. oic.example.garagedoor Resource Type definition .............................................. 128 480

Table 38. Light control Resource Type definition ................................................................ 136 481

Table 39. Light control Resource Type definition ................................................................ 136 482

Table 40. Alphabetized list of core resources ..................................................................... 138 483

Table 44. Alphabetized list of referenced OIC 1.1 core resources ....................................... 188 484

485 486


1 Scope 487

The OCF specifications are divided into two sets of documents: 488

• Core Specification documents: The Core Specification documents specify the Framework, i.e., 489 the OCF core architecture, interfaces, protocols and services to enable OCF profiles 490 implementation for Internet of Things (IoT) usages and ecosystems. 491

• Vertical Profiles Specification documents: The Vertical Profiles Specification documents 492 specify the OCF profiles to enable IoT usages for different market segments such as smart 493 home, industrial, healthcare, and automotive. The Application Profiles Specification is built 494 upon the interfaces and network security of the OCF core architecture defined in the Core 495 Specification. 496

This document is the OCF Core specification which specifies the Framework and core architecture. 497

498

2 Normative references 499

The following documents, in whole or in part, are normatively referenced in this document and are 500 indispensable for its application. For dated references, only the edition cited applies. For undated 501 references, the latest edition of the referenced document (including any amendments) applies. 502

ISO 8601, Data elements and interchange formats – Information interchange –Representation of 503 dates and times, International Standards Organization, December 3, 2004 504

IEEE 754, IEEE Standard for Floating-Point Arithmetic, August 2008 505

IETF RFC 1981, Path MTU Discovery for IP version 6, August 1996 506 https://tools.ietf.org/rfc/rfc1981.txt 507

IETF RFC 2460, Internet Protocol, version 6 (IPv6), December, 1998 508 https://tools.ietf.org/rfc/rfc2460.txt 509

IETF RFC 2616, Hypertext Transfer Protocol – HTTP/1.1, June 1999. 510 http://www.ietf.org/rfc/rfc2616.txt 511

IETF RFC 3810, Multicast Listener Discovery Version 2 (MLDv2) for IPv6, June 2004 512 http://www.ietf.org/rfc/rfc3810.txt 513

IETF RFC 3986, Uniform Resource Identifier (URI): General Syntax, January 2005. 514 http://www.ietf.org/rfc/rfc3986.txt 515

IETF RFC 4122, A Universally Unique IDentifier (UUID) URN Namespace, July 2005 516 http://www.ietf.org/rfc/rfc4122.txt 517

IETF RFC 4287, The Atom Syndication Format, December 2005, 518 http://www.ietf.org/rfc/rfc4287.txt 519

IETF RFC 4193, Unique Local IPv6 Unicast Addresses, October 2005 520 http://www.ietf.org/rfc/rfc4193.txt 521

IETF RFC 4291, IP Version 6 Addressing Architecture, February 2006 522 http://www.ietf.org/rfc/rfc4291.txt 523

IETF RFC 4443, Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 524 (IPv6) Specification, March 2006 525 http://www.ietf.org/rfc/rfc4443.txt 526

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 527 http://www.ietf.org/rfc/rfc4861.txt 528

IETF RFC 4862, IPv6 Stateless Address Autoconfiguration, September 2007 529 http://www.ietf.org/rfc/rfc4862.txt 530

IETF RFC 4941, Privacy Extensions for Stateless Address Autoconfiguration in IPv6, September 531 2007 532 http://www.ietf.org/rfc/rfc4941.txt 533

IETF RFC 4944, Transmission of IPv6 Packets over IEEE 802.15.4 Networks, September 2007 534 http://www.ietf.org/rfc/rfc4944.txt 535

IETF RFC 5646, Tags for Identifying Languages, September 2009 536 http://www.ietf.org/rfc/rfc5646.txt 537

IETF RFC 5988, Web Linking: General Syntax, October 2010 538 http://www.ietf.org/rfc/rfc5988.txt 539

IETF RFC 6434, IPv6 Node Requirements, December 2011 540 http://www.ietf.org/rfc/rfc6434.txt 541

IETF RFC 6455, The WebSocket Protocol, December 2011 542 https://www/ietf.org/rfc/rfc6455.txt 543

IETF RFC 6573, The Item and Collection Link Relations, April 2012 544 http://www.ietf.org/rfc/rfc6573.txt 545

IETF RFC 6690, Constrained RESTful Environments (CoRE) Link Format, August 2012 546 http://www.ietf.org/rfc/rfc6690.txt 547

IETF RFC 6762, Multicast DNS February 2013 548 http://www.ietf.org/rfc/rfc6762.txt 549

IETF RFC 6763, DNS-Based Service Discovery, February 2013 550 http://www.ietf.org/rfc/rfc6763.txt 551

IETF RFC 6775, Neighbor Discovery Optimization for IPv6 over Low-Power Wireless Personal 552 Area Networks (6LoWPANs), November 2012 553 http://www.ietf.org/rfc/rfc6775.txt 554

IETF RFC 7049, Concise Binary Object Representation (CBOR), October 2013 555 http://www.ietf.org/rfc/rfc7049.txt 556

IETF RFC 7084, Basic Requirements for IPv6 Customer Edge Routers, November 2013 557 http://www.ietf.org/rfc/rfc7084.txt 558

IETF RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format, March 2014 559 http://tools.ietf.org/rfc/rfc7159.txt 560

IETF RFC 7252, The Constrained Application Protocol (CoAP), June 2014 561 http://tools.ietf.org/rfc/rfc7252.txt 562

IETF RFC 7301, Transport Layer Security (TLS) Application-Layer Protocol Negotiation 563 Extension, July 2014 564 https://tools.ietf.org/html/rfc7301 565







http://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 566 http://www.ietf.org/rfc/rfc7428.txt 567

IETF RFC 7641, Observing Resources in the Constrained Application Protocol 568 (CoAP), September 2015 569 https://tools.ietf.org/html/rfc7641 570

IETF RFC 7668, IPv6 over BLUETOOTH(r) Low Energy, October 2015 571 https://tools.ietf.org/html/rfc7668 572

IETF RFC 7721, Security and Privacy Considerations for IPv6 Address Generation Mechanisms, 573 March 20016 574 https://tools.ietf.org/html/rfc7721 575

IETF RFC 7959, Block-Wise Transfers in the Constrained Application Protocol (CoAP), August 576 2016 577 https://tools.ietf.org/html/rfc7959 578

IETF draft-ietf-core-coap-tcp-tls-07, CoAP over TCP, TLS, and WebSockets, June 10 2015 579 https://datatracker.ietf.org/doc/draft-ietf-core-coap-tcp-tls/ 580

ECMA-4-4, The JSON Data Interchange Format, October 2013. 581 http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf 582

OCF Security, Open Connectivity Foundation Security Capabilities, Version 1.0 583

OCF Smart Home Device, Open Connectivity Foundation Smart Home Device, Version 1.0 584

IANA IPv6 Multicast Address Space Registry 585 http://www.iana.org/assignments/ipv6-multicast-addresses/ipv6-multicast-addresses.xhtml 586

IANA Media Types Assignment, March 2017 587 http://www.iana.org/assignments/media-types/media-types.xhtml 588

JSON Schema Validation, JSON Schema: interactive and non-interactive validation, January 2013 589 http://json-schema.org/latest/json-schema-validation.html 590

591






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

http://json-schema.org/latest/json-schema-validation.html


OpenAPI specification, fka Swagger RESTful API Documentation Specification, Version 2.0 592 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md 593

W3C XML character escaping, Extensible Markup Language (XML) 1.0, November 2008 594 http://www.w3.org/TR/2008/REC-xml-20081126/#syntax 595

3 Terms, definitions, symbols and abbreviations 596

3.1 Terms and definitions 597

598 Client 599 a logical entity that accesses a Resource on a Server 600

601 Collection 602 a Resource that contains zero or more Links 603

604 Common Properties 605 Resource Properties specified for all Resources 606

607 Configuration Source 608 a cloud or service network or a local read-only file which contains and provides configuration 609 related information to the Devices 610

611 Core Resources 612 those Resources that are defined in this specification 613

614 Default Interface 615 an Interface used to generate the response when an Interface is omitted in a request 616

617 Device 618 a logical entity that assumes one or more Roles (e.g., Client, Server) 619

Note 1 to entry: More than one Device can exist on a physical platform. 620

621 Device Type 622 a uniquely named definition indicating a minimum set of Resource Types that a Device supports 623

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 624 Resource discovery. 625

626 Endpoint 627 the source or destination of a request and response messages for a given Transport Protocol Suite 628

Note 1 to entry: Example of a Transport Protocol Suite would be CoAP over UDP over IPv6. 629

630 Entity 631 an aspect of the physical world that is exposed through a Device 632

Note 1 to entry: Example of an entity is an LED. 633

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

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


634 Framework 635 a set of related functionalities and interactions defined in this specification, which enable 636 interoperability across a wide range of networked devices, including IoT 637

638 Interface 639 provides a view and permissible responses on a Resource 640

3.1.13 641 Introspection 642 mechanism to determine the capabilities of the hosted Resources of a Device 643

3.1.14 644 Introspection Device Data 645 data that describes the payloads per implemented method of the Resources that makes up the 646 Device 647

Note 1 to entry: See section 11.8 for all requirements and exceptions 648

649 Links 650 extends typed web links according to IETF RFC 5988 651

652 Non-OCF Device 653 A device which does not comply with the OCF Device requirements 654

655 Notification 656 the mechanism to make a Client aware of resource state changes in a Resource 657

658 Observe 659 the act of monitoring a Resource by sending a RETRIEVE request which is cached by the Server 660 hosting the Resource and reprocessed on every change to that Resource 661

662 Parameter 663 an element that provides metadata about a Resource referenced by the target URI of a Link 664

665 Partial UPDATE 666 an UPDATE request to a Resource that includes a subset of the Properties that are visible via the 667 Interface being applied for the Resource Type 668

669 Platform 670 a physical device containing one or more Devices 671

672 Remote Access Endpoint (RAE) Client 673 a Client which supports XMPP functionality in order to access a Server from a remote location 674

675 Remote Access Endpoint (RAE) Server 676 a Server which supports XMPP and can publish its resource(s) to an XMPP server in the cloud, 677 thus becoming remotely addressable and accessible 678


Note 1 to entry: An RAE Server also supports ICE/STUN/TURN. 679

680 Resource 681 represents an Entity modelled and exposed by the Framework 682

683 Resource Directory 684 a set of descriptions of Resources where the actual Resources are held on Servers external to the 685 Device hosting the Resource Directory, allowing lookups to be performed for those resources 686

Note 1 to entry: This functionality can be used by sleeping Servers or Servers that choose not to listen/respond to 687 multicast requests directly. 688

689 Resource Interface 690 a qualification of the permitted requests on a Resource 691

692 Resource Property 693 a significant aspect or parameter of a resource, including metadata, that is exposed through the 694 Resource 695

696 Resource Type 697 a uniquely named definition of a class of Resource Properties and the interactions that are 698 supported by that class 699

Note 1 to entry: Each Resource has a Property “rt” whose value is the unique name of the Resource Type. 700

701 Scene 702 a static entity that stores a set of defined Resource property values for a collection of Resources 703

Note 1 to entry: A Scene is a prescribed setting of a set of resources with each having a predetermined value for the 704 property that has to change. 705

706 Scene Collection 707 a collection Resource that contains an enumeration of possible Scene Values and the current 708 Scene Value 709

Note 1 to entry: The member values of the Scene collection Resource are Scene Members. 710

711 Scene Member 712 a Resource that contains mappings of Scene Values to values of a property in the resource 713

714 Scene Value 715 a Scene enumerator representing the state in which a Resource can be 716

717 Server 718 a Device with the role of providing resource state information and facilitating remote interaction 719 with its resources 720

Note 1 to entry: A Server can be implemented to expose non-OCF Device resources to Clients (section 5.6) 721

722 Vertical Resource Type 723 a Resource Type in a vertical domain specification 724


Note 1 to entry: An example of a Vertical Resource Type would be “oic.r.switch.binary”. 725

3.2 Symbols and abbreviations 726

727 ACL 728 Access Control List 729

Note 1 to entry: The details are defined in OCF Security. 730

731 CBOR 732 Concise Binary Object Representation 733

734 CoAP 735 Constrained Application Protocol 736

737 EXI 738 Efficient XML Interchange 739

740 IRI 741 Internationalized Resource Identifiers 742

743 ISP 744 Internet Service Provider 745

746 JSON 747 JavaScript Object Notation 748

749 mDNS 750 Multicast Domain Name Service 751

752 MTU 753 Maximum Transmission Unit 754

755 NAT 756 Network Address Translation 757

758 OCF 759 Open Connectivity Foundation 760

the organization that created this specification 761

762 RAML 763 RESTful API Modeling Language 764

765 REST 766 Representational State Transfer 767


768 RESTfull 769 REST-compliant Web services 770

771 URI 772 Uniform Resource Identifier 773

774 URN 775 Uniform Resource Name 776

777 UTC 778 Coordinated Universal Time 779

780 UUID 781 Universal Unique Identifier 782

783 XML 784 Extensible Markup Language 785

3.3 Conventions 786

In this specification a number of terms, conditions, mechanisms, sequences, parameters, events, 787 states, or similar terms are printed with the first letter of each word in uppercase and the rest 788 lowercase (e.g., Network Architecture). Any lowercase uses of these words have the normal 789 technical English meaning. 790

3.4 Data types 791

Resources are defined using data types derived from JSON values as defined in ECMA-4-4. 792 However, a Resource can overload a JSON defined value to specify a particular subset of the 793 JSON value, using validation keywords defined in JSON Schema Validation. 794

795

Among other validation keywords, section 7 in JSON Schema Validation defines a “format” keyword 796 with a number of format attributes such as “uri” and “date-time”, and a “pattern” keyword with a 797 regular expression that can be used to validate a string. This section defines patterns that are 798 available for use in describing OCF Resources. The pattern names can be used in specification 799 text where JSON format names can occur. The actual JSON schemas shall use the JSON type 800 and pattern instead. 801

802

For all rows defined in Table 1 below, the JSON type is string. 803


Table 1. Additional OCF Types 804

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

duration ^(P(?!$)([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?((T(?=[0-

9]+[HMS])([0-9]+H)?([0-9]+M)?([0-9]+S)?)?))$|^(P[0-9]+W)$|^(P[0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|2[0-

9]|1[0-9]|0[1-9])T(2[0-3]|1[0-9]|0[1-9]):([0-5][0-9]):([0-5][0-9])$|^(P[0-

9]{4})(1[0-2]|0[1-9])(3[0-1]|2[0-9]|1[0-9]|0[1-9])T(2[0-3]|1[0-9]|0[1-

9])([0-5][0-9])([0-5][0-9])$

A string representing duration formatted as defined in ISO 8601. Allowable formats are:

P[n]Y[n]M[n]DT[n]H[n]M[n]S, P[n]W, P[n]Y[n]-M[n]-DT[0-23]H[0-59]:M[0-59]:S, and P[n]W, P[n]Y[n]M[n]DT[0-

23]H[0-59]M[0-59]S. P is mandatory, all other elements are optional, time elements must follow a T.

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.

805

Strings shall be encoded as UTF-8 unless otherwise specified. 806

807

In a JSON schema, “maxLength” for a string indicates the maximum number of characters not 808 octets. However, “maxLength” shall also indicate the maximum number of octets. If no “maxLength” 809 is defined for a string, then the maximum length shall be 64 octets. 810

4 Document conventions and organization 811

In this document, features are described as required, recommended, allowed or DEPRECATED as 812 follows: 813

Required (or shall or mandatory)(M). 814


• These basic features shall be implemented to comply with Core Architecture. The phrases 815 “shall not”, and “PROHIBITED” indicate behaviour that is prohibited, i.e. that if performed 816 means the implementation is not in compliance. 817

Recommended (or should)(S). 818

• These features add functionality supported by Core Architecture and should be implemented. 819 Recommended features take advantage of the capabilities Core Architecture, usually without 820 imposing major increase of complexity. Notice that for compliance testing, if a recommended 821 feature is implemented, it shall meet the specified requirements to be in compliance with these 822 guidelines. Some recommended features could become requirements in the future. The phrase 823 “should not” indicates behaviour that is permitted but not recommended. 824

Allowed (may or allowed)(O). 825

• These features are neither required nor recommended by Core Architecture, but if the feature 826 is implemented, it shall meet the specified requirements to be in compliance with these 827 guidelines. 828

DEPRECATED. 829

• Although these features are still described in this specification, they should not be implemented 830 except for backward compatibility. The occurrence of a deprecated feature during operation of 831 an implementation compliant with the current specification has no effect on the 832 implementation’s operation and does not produce any error conditions. Backward compatibility 833 may require that a feature is implemented and functions as specified but it shall never be used 834 by implementations compliant with this specification. 835

Conditionally allowed (CA) 836

• The definition or behaviour depends on a condition. If the specified condition is met, then the 837 definition or behaviour is allowed, otherwise it is not allowed. 838

Conditionally required (CR) 839

• The definition or behaviour depends on a condition. If the specified condition is met, then the 840 definition or behaviour is required. Otherwise the definition or behaviour is allowed as default 841 unless specifically defined as not allowed. 842

843

Strings that are to be taken literally are enclosed in “double quotes”. 844

Words that are emphasized are printed in italic. 845

5 Architecture 846

5.1 Overview 847

The architecture enables resource based interactions among IoT artefacts, i.e. physical devices 848 or applications. The architecture leverages existing industry standards and technologies and 849 provides solutions for establishing connections (either wireless or wired) and managing the flow of 850 information among devices, regardless of their form factors, operating systems or service providers. 851

Specifically, the architecture provides: 852

• A communication and interoperability framework for multiple market segments (Consumer, 853 Enterprise, Industrial, Automotive, Health, etc.), OSs, platforms, modes of communication, 854 transports and use cases 855


• A common and consistent model for describing the environment and enabling information 856 and semantic interoperability 857

• Common communication protocols for discovery and connectivity 858

• Common security and identification mechanisms 859

• Opportunity for innovation and product differentiation 860

• A scalable solution addressing different device capabilities, applicable to smart devices as 861 well as the smallest connected things and wearable devices 862

The architecture is based on the Resource Oriented Architecture design principles and described 863 in the sections 5.2 through 5.6 respectively. section 5.2 presents the guiding principles for OCF 864 operations. section 5.3 defines the functional block diagram and Framework. section 5.5 provides 865 an example scenario with roles. section 5.6 provides an example scenario of bridging to non- OCF 866 ecosystem. 867

5.2 Principle 868

In the architecture, Entities in the physical world (e.g., temperature sensor, an electric light or a 869 home appliance) are represented as resources. Interactions with an Entity are achieved through 870 its resource representations (section 7.7) using operations that adhere to Representational State 871 Transfer (REST) architectural style, i.e., RESTful interactions. 872

The architecture defines the overall structure of the Framework as an information system and the 873 interrelationships of the Entities that make up OCF. Entities are exposed as Resources, with their 874 unique identifiers (URIs) and support interfaces that enable RESTful operations on the Resources. 875 Every RESTful operation has an initiator of the operation (the client) and a responder to the 876 operation (the server). In the Framework, the notion of the client and server is realized through 877 roles (section 5.5). Any Device can act as a Client and initiate a RESTful operation on any Device 878 acting as a Server. Likewise, any Device that exposes Entities as Resources acts as a Server. 879 Conformant to the REST architectural style, each RESTful operation contains all the information 880 necessary to understand the context of the interaction and is driven using a small set of generic 881 operations, i.e., CREATE, RETRIEVE, UPDATE, DELETE and NOTIFY (CRUDN) defined in 882 section 8, which include representations of Resources. 883

Figure 1 depicts the architecture. 884


OCF Device

Client

Protocol specificImplementation ofCRUDN Operations

(e.g. CoAP, HTTP, XMPP)

OCF Device

Server

Protocol specific implementation of

Server

Resource

CRUDN OperationsOCF RESTfulResource Model

Layer

Specific Implementation of

Data Protocol/Messaging

OCF Roles

Prot

ocol

Map

ping

Entity(e.g. light bulb,

Heart rate monitor)

Resource Mapping

OCFAbstractions

COAP RequestE.g. GET /s/data

{ “bulb”: “on” }COAP Response

885 886

Figure 1: Architecture - concepts 887

888

The architecture is organized conceptually into three major aspects that provide overall separation 889 of concern: resource model, RESTful operations and abstractions. 890

• Resource model: The resource model provides the abstractions and concepts required to 891 logically model, and logically operate on the application and its environment. The core resource 892 model is common and agnostic to any specific application domain such as smart home, 893 industrial or automotive. For example, the resource model defines a Resource which abstracts 894 an Entity and the representation of a Resource maps the Entity’s state. Other resource model 895 concepts can be used to model other aspects, for example behaviour. 896

• RESTful operations: The generic CRUDN operations are defined using the RESTful paradigm 897 to model the interactions with a Resource in a protocol and technology agnostic way. The 898 specific communication or messaging protocols are part of the protocol abstraction and 899 mapping of Resources to specific protocols is provided in section 11.8. 900

• Abstraction: The abstractions in the resource model and the RESTful operations are mapped 901 to concrete elements using abstraction primitives. An entity handler is used to map an Entity 902 to a Resource and connectivity abstraction primitives are used to map logical RESTful 903 operations to data connectivity protocols or technologies. Entity handlers may also be used to 904 map Resources to Entities that are reached over protocols that are not natively supported by 905 OCF. 906

907


5.3 Functional block diagram 908

The functional block diagram encompasses all the functionalities required for operation. These 909 functionalities are categorized as L2 connectivity, networking, transport, Framework, and 910 application profiles. The functional blocks are depicted in Figure 2 and listed below. 911

Application profiles

Framework

Transport

Networking

L2 Connectivity

ID & Addressing

Discovery

Resource model

Device management

CRUDN

Security

Messaging

Smart Home ConnectedHealth Retail Automotive

912

Figure 2: Functional block diagram 913

• L2 connectivity: Provides the functionalities required for establishing physical and data 914 link layer connections (e.g., Wi-FiTM or Bluetooth® connection) to the network. 915

• Networking: Provides functionalities required for Devices to exchange data among 916 themselves over the network (e.g., Internet). 917

• Transport: Provides end-to-end flow transport with specific QoS constraints. Examples of 918 a transport protocol include TCP and UDP or new Transport protocols under development 919 in the IETF, e.g., Delay Tolerant Networking (DTN). 920

• Framework: Provides the core functionalities as defined in this specification. The 921 functional block is the source of requests and responses that are the content of the 922 communication between two Devices. 923

• Application profile: Provides market segment specific data model and functionalities, e.g., 924 smart home data model and functions for the smart home market segment. 925

When two Devices communicate with each other, each functional block in a Device interacts with 926 its counterpart in the peer Device as shown in Figure 3. 927



Transport

Networking

L2 Connectivity

Framework

Application

Resource

Transport

Network

Physical


Transport

Networking

L2 Connectivity

Framework

Device 1 Device 2

928

Figure 3: Communication layering model 929

5.4 Framework 930

Framework consists of functions which provide core functionalities for operation. 931

1) Identification and addressing. Defines the identifier and addressing capability. The 932 Identification and addressing function is defined in section 6. 933

2) Discovery. Defines the process for discovering available 934

a) Devices (Endpoint Discovery in section 10) and 935

b) Resources (Resource discovery in section 11.3) 936

3) Resource model. Specifies the capability for representation of Entities in terms of resources 937 and defines mechanisms for manipulating the resources. The resource model function is 938 defined in section 7. 939

4) CRUDN. Provides a generic scheme for the interactions between a Client and Server as 940 defined in section 8. 941

5) Messaging. Provides specific message protocols for RESTful operation, i.e. CRUDN. For 942 example, CoAP is a primary messaging protocol. The messaging function is defined in section 943 11.8. 944

6) Device management. Specifies the discipline of managing the capabilities of a Device, and 945 includes device provisioning and initial setup as well as device monitoring and diagnostics. 946 The device management function is defined in section 11.5. 947

7) Security. Includes authentication, authorization, and access control mechanisms required for 948 secure access to Entities. The security function is defined in section 13. 949

5.5 Example Scenario with roles 950

Interactions are defined between logical entities known as Roles. Three roles are defined: Client, 951 Server and Intermediary. 952

Figure 4 illustrates an example of the Roles in a scenario where a smart phone sends a request 953 message to a thermostat; the original request is sent over HTTP, but is translated into a CoAP 954 request message by a gateway in between, and then delivered to the thermostat. In this example, 955 the smart phone takes the role of a Client, the gateway takes the role of an Intermediary and the 956 thermostat takes the role of a Server. 957


958

959

Figure 4: Example illustrating the Roles 960

5.6 Example Scenario: Bridging to Non- OCF ecosystem 961

The use case for this scenario is a display (like a wrist watch) that is used to monitor a heart rate 962 sensor that implements a protocol that is not OCF supported. 963

Figure 5 provides a detailed logical view of the concepts described in Figure 1. 964


OCF Roles

OCF Device

OCF DeviceData Protocol

Abstraction

Resource Type

Resource Interface

Entity (e.g. HW Sensor)

Entity HandlerBinding

Resource

Resource Address

Non-OCFprotocol

965

Figure 5: Framework - Architecture Detail 966

967

The details may be implemented in many ways, for example, by using a Server with an entity 968 handler to interface directly to a non- OCF device as shown in Figure 6. 969

Device (as Client)

Device(as Server)

Heart Rate SensorDevice

Framework Framework Non-OCF ecosystem

OCFNon-OCFProtocol

970 971

Figure 6: Server bridging to Non- OCF device 972

On start-up the Server runs the entity handlers which discover the non- OCF systems (e.g., Heart 973 Rate Sensor Device) and create resources for each device or functionality discovered. The entity 974 handler creates a Resource for each discovered device or functionality and binds itself to that 975 Resource. These resources are made discoverable by the Server. 976

Once the resources are created and made discoverable, then the Display Device can discover 977 these resources and operate on them using the mechanisms described in this specification. The 978 requests to a resource on the Server are then interpreted by the entity handler and forwarded to 979 the non- OCF device using the protocol supported by the non-OCF device. The returned 980 information from the non- OCF device is then mapped to the appropriate response for that resource. 981

5.7 OCF Cloud architecture 982

This section describes the architecture of OCF Cloud in Figure 7: 983


Resource Directory Account ServerCloud

Interface

Resource Server Resource Client

984

Figure 7: OCF Cloud deployment architecture 985

The Cloud architecture comprises of following three network entities: 986

• Cloud Interface Server – A logical entity to which an OCF Device primarily. It encapsulates 987 Account Server and Resource Directory features. The Cloud Interface routes the packet 988 between OCF Devices based on the request URI in the packet header. The Client needs to 989 keep the persistent connection alive to the Server 990

• Account Server – A logical entity that handles Device registration, Auth Token validation and 991 handles sign-in and token-refresh requests from the Device. 992

• Resource Directory – A logical entity holding resource information published by Servers. A 993 Client when looking for a Resource receives a response from the Resource Directory on behalf 994 of the Server. Then with information included in the response form the Resource Directory, the 995 Client directly connects to the Server. 996

When a Client try to access a Server, the Client connects to Cloud Interface Server then Cloud 997 Interface routes the received message to the indicated Server after checking the privilege. 998

999

1000

1001


Figure 8: Endpoint routing 1002

6 Identification and addressing 1003

6.1 Introduction 1004

Facilitating proper and efficient interactions between elements in the Framework, requires a means 1005 to identify, name and address these elements. 1006

The identifier unambiguously identifies an element in a context or domain. The context or domain 1007 may be determined by the use or the application. The identifier is expected to be immutable over 1008 the lifecycle of that element and is unambiguous within a context or domain. 1009

The address is used to define a place, way or means of reaching or accessing the element in order 1010 to interact with it. An address may be mutable based on the context. 1011

The name is a handle that distinguishes the element from other elements in the framework. The 1012 name may be changed over the lifecycle of that element. 1013

There may be methods or resolution schemes that allow determining any of these based on the 1014 knowledge of one or more of others (e.g., determine name from address or address from name). 1015

Each of these aspects may be defined separately for multiple contexts (e.g., a context could be a 1016 layer in a stack). So an address may be a URL for addressing resource and an IP address for 1017 addressing at the connectivity layer. In some situations, both these addresses would be required. 1018 For example, to do RETRIEVE (section 8.3) operation on a particular resource representation, the 1019 client needs to know the address of the target resource and the address of the server through 1020 which the resource is exposed. 1021

In a context or domain of use, a name or address could be used as identifier or vice versa. For 1022 example, a URL could be used as an identifier for a resource and designated as a URI. 1023

The remainder of this section discusses the identifier, address and naming from the point of view 1024 of the resource model and the interactions to be supported by the resource model. Examples of 1025 interactions are the RESTful interactions, i.e. CRUDN operation (section 8) on a resource. Also 1026 the mapping of these to transport protocols, e.g., CoAP is described. 1027

6.2 Identification 1028

An identifier is unambiguous within the context or domain of use. There are many schemes that 1029 may be used to generate an identifier that has the required properties. The identifier may be 1030 context-specific in that the identifier is expected to be and guaranteed to be unambiguous only 1031 within that context or domain. Identifier may also be context- independent where these identifiers 1032 are guaranteed to be unambiguous across all contexts and domains both spatially and temporally. 1033 The context-specific identifiers could be defined by simple schemes like monotonic enumeration 1034 or may be defined by overloading an address or name, for example an IP address may be an 1035 identifier within the private domain behind a gateway in a smart home. On the other hand, context-1036 independent identifiers require a stronger scheme that derives universally unique identities, for 1037 example any one of the versions of Universally Unique Identifiers (UUIDs). Context independent 1038 identifier may also be generated using hierarchy of domains where the root of the hierarchy is 1039 identified with a UUID and sub-domains may generate context independent identifier by 1040 concatenating context-specific identifiers for that domain to the context-independent identifier of 1041 their parent. 1042

Resource identification and addressing 1043

A resource may be identified using a URI and addressed by the same URI if the URI is a URL. In 1044 some cases a resource may need an identifier that is different from a URI; in this case, the resource 1045


may have a property whose value is the identifier. When the URI is in the form of a URL, then the 1046 URI may be used to address the resource. 1047

An OCF URI is based on the general form of a URI as defined in IETF RFC 3986 as follows: 1048

<scheme>://<authority>/<path>?<query> 1049

Specifically the OCF URI is specified in the following form: 1050

ocf://<authority>/<path>?<query> 1051

A description of values that each component takes is given below. 1052

The scheme for the URI is ‘ocf’. The ‘ocf’ scheme represents the semantics, definitions and use 1053 as defined in this document. If a URI has the portion preceding the ‘//’ (double slash) omitted, then 1054 the ‘ocf’ scheme shall be assumed. 1055

Each transport binding is responsible for specifying how an OCF URI is converted to a transport 1056 protocol URI before sending over the network by the requestor. Similarly on the receiver side, each 1057 transport binding is responsible for specifying how an OCF URI is converted from a transport 1058 protocol URI before handing over to the resource model layer on the receiver. 1059

The authority of an OCF URI shall be the Device ID ("di") value, as defined in [OCF Security], of 1060 the Server. 1061

The path is a string that unambiguously identifies or references a resource within the context of 1062 the Server. In this version of the specification, a path shall not include pct-encoded non-ASCII 1063 characters or NUL characters. A path shall be preceded by a ‘/’ (slash). The path may have ‘/’ 1064 (slash) separated segments for human readability reasons. In the OCF context, the ‘/’ (slash) 1065 separated segments are treated as a single string that directly references the resources (i.e. a flat 1066 structure) and not parsed as a hierarchy. On the Server, the path or some substring in the path 1067 may be shortened by using hashing or some other scheme provided the resulting reference is 1068 unique within the context of the host. 1069

Once a path is generated, a Client accessing the resource or recipient of the URI should use that 1070 path as an opaque string and should not parse to infer a structure, organization or semantic. 1071

A query string shall contain a list of <name>=<value> segments (aka “name-value pair”) each 1072 separated by a ‘&’ (ampersand). The query string will be mapped to the appropriate syntax of the 1073 protocol used for messaging. (e.g., CoAP). 1074

A URI may be either 1075

• Fully qualified or 1076

• Relative 1077

Generation of URI: 1078

A URI may be defined by the Client which is the creator of that resource. Such a URI may be 1079 relative or absolute (fully qualified). A relative URI shall be relative to the Device on which it is 1080 hosted. Alternatively, a URI may be generated by the Server of that resource automatically based 1081 on a pre-defined convention or organization of the resources, based on an interface, based on 1082 some rules or with respect to different roots or bases. 1083

Use of URI: 1084


The absolute path reference of a URI is to be treated as an opaque string and a Client should not 1085 infer any explicit or implied structure in the URI – the URI is simply an address. It is also 1086 recommended that Devices hosting a resource treat the URI of each resource as an opaque string 1087 that addresses only that resource. (e.g., URI's /a and /a/b are considered as distinct addresses 1088 and resource b cannot be construed as a child of resource a). 1089

6.3 Namespace: 1090

The relative URI prefix “/oic/” is reserved as a namespace for URIs defined in OCF specifications 1091 and shall not be used for URIs that are not defined in OCF specifications. 1092

6.4 Network addressing 1093

The following are the addresses used in this specification: 1094

• IP address 1095

An IP address is used when the device is using an IP configured interface. 1096

When a Device only has the identity information of its peer, a resolution mechanism is needed to 1097 map the identifier to the corresponding address. 1098

7 Resource model 1099


The Resource Model defines concepts and mechanisms that provide consistency and core 1101 interoperability between devices in the OCF ecosystems. The Resource Model concepts and 1102 mechanisms are then mapped to the transport protocols to enable communication between the 1103 devices – each transport provides the communication protocol interoperability. The Resource 1104 Model, therefore, allows for interoperability to be defined independent of the transports. 1105

In addition, the concepts in the Resource Model support modelling of the primary artefacts and 1106 their relationships to one and another and capture the semantic information required for 1107 interoperability in a context. In this way, OCF goes beyond simple protocol interoperability to 1108 capture the rich semantics required for true interoperability in Wearable and Internet of Things 1109 ecosystems. 1110

The primary concepts in the Resource Model are: Entity, Resources, Uniform Resource Identifiers 1111 (URI), Resource Types, Properties, Representations, Interfaces, Collections and Links. In addition, 1112 the general mechanisms are CREATE, RETRIEVE, UPDATE, DELETE and NOTIFY. These 1113 concepts and mechanisms may be composed in various ways to define the rich semantics and 1114 interoperability needed for a diverse set of use cases that the OCF framework is applied to. 1115

In the OCF Resource Model framework, an Entity needs to be visible, interacted with or 1116 manipulated, it is represented by an abstraction called a Resource. A Resource encapsulates and 1117 represents the state of an Entity. A Resource is identified, addressed and named using URIs. 1118

Properties are "key=value" pairs and represent state of the Resource. A snapshot of these 1119 Properties is the Representation of the Resource. A specific view of the Representation and the 1120 mechanisms applicable in that view are specified as Interfaces. Interactions with a Resource are 1121 done as Requests and Responses containing Representations. 1122

A resource instance is derived from a Resource Type. The uni-directional relationship between 1123 one Resource and another Resource is defined as a Link. A Resource that has Properties and 1124 Links is a Collection. 1125


A set of Properties can be used to define a state of a Resource. This state may be retrieved or 1126 updated using appropriate Representations respectively in the response from and request to that 1127 Resource. 1128

A Resource (and Resource Type) could represent and be used to expose a capability. Interactions 1129 with that Resource can be used to exercise or use that capability. Such capabilities can be used 1130 to define processes like discovery, management, advertisement etc. For example: “discovery of 1131 resources on a device” can be defined as the retrieval of a representation of a specific resource 1132 where a property or properties have values that describe or reference the resources on the device. 1133

The information for Request or Response with the Representation may be communicated “on the 1134 wire” by serializing using a transfer protocol or encapsulated in the payload of the transport 1135 protocol – the specific method is determined by the normative mapping of the Request or Response 1136 to the transport protocol. See section 11.8 for transport protocols supported. 1137

The RAML definitions used in this document are normative. This also includes that all defined 1138 JSON payloads shall comply with the indicated JSON schema. See Annex D for Resource Types 1139 defined in this specification. 1140

7.2 Resource 1141

A Resource shall be defined by one or more Resource Type(s) – see Annex D for Resource Type. 1142 A request to CREATE a Resource shall specify one or more Resource Types that define that 1143 Resource. 1144

A Resource is hosted in a Device. A Resource shall have a URI as defined in section 6. The URI 1145 may be assigned by the Authority at the creation of the Resource or may be pre-defined by the 1146 specification of the Resource Type. 1147

1148

Core Resources are the Resources defined in this specification to enable functional interactions 1149 as defined in section 10 (e.g., Discovery, Device Management, etc). Among the Core Resources, 1150 “/oic/res”, “/oic/p”, and “/oic/d” shall be supported on all Devices. Devices may support other Core 1151 Resources depending on the functional interactions they support. 1152

7.3 Property 1153

Introduction 1154

A Property describes an aspect that is exposed through a Resource including meta-information 1155 related to that resource. 1156

A Property shall have a name i.e. Property Name and a value i.e. Property Value. The Property is 1157 expressed as a key-value pair where key is the Property Name and value the Property Value like 1158 <Property Name> = <Property Value>. For example if the “temperature” Property has a Property 1159 Name “temp” and a Property Value “30F”, then the Property is expressed as “temp=30F”. The 1160 specific format of the Property depends on the encoding scheme. For example, in JSON, Property 1161 is represented as "key": value (e.g., "temp": 30). 1162

/my/resource/example { "rt": ["oic.r.foobar"], "if": ["oic.if.a"], "value": "foo value" }

Properties

URI


In addition, the Property definition shall have a 1163

• Value Type – the Value Type defines the values that a Property Value may take. The Value 1164 Type may be a simple data type (e.g. string, Boolean) as defined in section 3.4 or may be a 1165 complex data type defined with a schema. The Value Type may define 1166

o Value Rules define the rules for the set of values that the Property Value may take. 1167 Such rules may define the range of values, the min-max, formulas, set of 1168 enumerated values, patterns, conditional values and even dependencies on values 1169 of other Properties. The rules may be used to validate the specific values in a 1170 Property Value and flag errors. 1171

• Mandatory – specifies if the Property is mandatory or not for a given Resource Type. 1172

• Access modes – specifies whether the Property may be read, written or both. Updates are 1173 equivalent to a write. “r” is used for read and “w” is used for write – both may be specified. 1174 Write does not automatically imply read. 1175

The definition of a Property may include the following additional information – these items are 1176 informative: 1177

• Property Title - a human-friendly name to designate the Property; usually not sent over the 1178 wire 1179

• Description – descriptive text defining the purpose and expected use of this Property. 1180

In general, a Property is meaningful only within the Resource to which it is associated. However a 1181 base set of Properties that may be supported by all Resources, known as Common Properties, 1182 keep their semantics intact across Resources i.e. their “key=value” pair means the same in any 1183 Resource. Detailed tables with the above fields for all Common Properties are defined in section 1184 7.3.2. 1185

Common Properties 1186

7.3.2.1 Introduction 1187

The Common Properties defined in this section may be specified for all Resources. The following 1188 Properties are defined as Common Properties: “Resource Type”, “Resource Interface”, “Name”, 1189 and “Resource Identity”. 1190

The name of a Common Property shall be unique and shall not be used by other properties. When 1191 defining a new Resource Type, its non-common properties shall not use the name of existing 1192 Common Properties (e.g., "rt", "if", "n", “id”). When defining a new "Common Property", it should 1193 be ensured that its name has not been used by any other properties. The uniqueness of a new 1194 Common Property name can be verified by checking all the Properties of all the existing OCF 1195 defined Resource Types. However, this may become cumbersome as the number of Resource 1196 Types grow. To prevent such name conflicts in the future, OCF may reserve a certain name space 1197 for common property. Potential approaches are (1) a specific prefix (e.g. "oic") may be designated 1198 and the name preceded by the prefix (e.g. "oic.psize") is only for Common Property; (2) the names 1199 consisting of one or two letters are reserved for Common Property and all other Properties shall 1200 have the name with the length larger than the 2 letters; (3) Common Properties may be nested 1201 under specific object to distinguish themselves. 1202

The ability to UPDATE a Common Property (that supports write as an access mode) is restricted 1203 to the “oic.if.rw” (read-write) Interface; thus a Common Property shall be updatable using the read-1204 write Interface if and only if the Property supports write access as defined by the Property definition 1205 and the associated schema for the read-write Interface. 1206

The following Common Properties for all Resources are specified in section 7.3.2.2 through section 1207 7.3.2.6 and summarized as follows: 1208


• Resource Type ("rt") – this Property is used to declare the Resource Type of that Resource. 1209 Since a Resource could be define by more than one Resource Type the Property Value of the 1210 Resource Type Property can be used to declare more than one Resource type. For example: 1211 “rt”: [“oic.wk.d”, “oic.d.airconditioner”] declares that the Resource containing this Property is 1212 defined by either the “oic.wk.d” Resource Type or the “oic.d.airconditioner” Resource Type. 1213 See section 7.3.2.3 for details. 1214

• Interface ("if") – this Property declares the Interfaces supported by the Resource. The Property 1215 Value of the Interface Property can be multi-valued and lists all the Interfaces supported. See 1216 section 7.3.2.4 for details. 1217

• Name ("n") – the Property declares “human-readable” name assigned to the Resource. See 1218 section 7.3.2.5. 1219

• Resource Identity ("id"): its Property Value shall be a unique (across the scope of the host 1220 Server) instance identifier for a specific instance of the Resource. The encoding of this identifier 1221 is device and implementation dependent. See section 7.3.2.6 for details. 1222

7.3.2.2 Property Name and Property Value definitions 1223

The Property Name and Property Value as used in this specification: 1224

• Property Name– the key in "key=value” pair. Property Name is case sensitive and its data type 1225 is “string”. Property names shall contain only letters A to Z, a to z, digits 0 to 9, hyphen, and 1226 dot, and shall not begin with a digit. 1227

• Property Value – the value in "key=value” pair. Property Value is case sensitive when its data 1228 type is “string”. Any enum values shall contain only letters A to Z, a to z, digits 0-9 and 1229 underscores, and shall not begin with a digit. 1230

7.3.2.3 Resource Type 1231

Resource Type Property is specified in section 7.4. 1232

7.3.2.4 Interface 1233

Interface Property is specified in section 7.5. 1234

7.3.2.5 Name 1235

A human friendly name for the Resource, i.e. a specific resource instance name (e.g., 1236 MyLivingRoomLight), The Name Property is as defined in Table 2 1237

Table 2. Name Property Definition 1238

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 1239 Resource Type does not support UPDATE or does not support UPDATE using read-write). 1240

7.3.2.6 Resource Identity 1241

The Resource Identity Property shall be a unique (across the scope of the host Server) instance 1242 identifier for a specific instance of the Resource. The encoding of this identifier is device and 1243 implementation dependent as long as the uniqueness constraint is met, noting that an 1244 implementation may use a uuid as defined in section 3.4. The Resource Identity Property is as 1245 defined in Table 3. 1246


Table 3. Resource Identity Property Definition 1247

1248


Value type

Value rule Unit Access mode


Resource Identity

id string or uuid

Implementation Dependent

R No Unique identifier of the Resource (over all Resources in the Device)

1249

7.4 Resource Type 1250

Introduction 1251

Resource Type is a class or category of Resources and a Resource is an instance of one or more 1252 Resource Types. 1253

The Resource Types of a Resource is declared using the Resource Type Common Property as 1254 described in section 7.3.2.3 or in a Link using the Resource Type Parameter. 1255

A Resource Type may either be pre-defined (Core Resource Types in this specification and Vertical 1256 Resource Types in vertical domain specifications) or in custom definitions by manufacturers, end 1257 users, or developers of Devices (vendor-defined Resource Types). Resource Types and their 1258 definition details may be communicated out of band (i.e. in documentation) or be defined explicitly 1259 using a meta-language which may be downloaded and used by APIs or applications. OCF has 1260 adopted RAML and JSON Schema as the specification method for OCF’s RESTful interfaces and 1261 Resource definitions. 1262

Every Resource Type shall be identified with a Resource Type ID which shall be represented using 1263 the requirements and ABNF governing the Resource Type attribute in IETF RFC 6690(section 2 1264 for ABNF and section 3.1 for requirements) with the caveat that segments are separated by a "." 1265 (period). The entire string represents the Resource Type ID. When defining the ID each segment 1266 may represent any semantics that are appropriate to the Resource Type. For example, each 1267 segment could represent a namespace. Once the ID has been defined, the ID should be used 1268 opaquely and an implementations should not infer any information from the individual segments. 1269 The string "oic", when used as the first segment in the definition of the Resource Type ID, is 1270 reserved for OCF-defined Resource Types. All OCF defined Resource Types are to be registered 1271 with the IANA Core Parameters registry as described also in IETF RFC 6690. 1272

Resource Type Property 1273

A Resource when instantiated or created shall have one or more Resource Types that are the 1274 template for that Resource. The Resource Types that the Resource conforms to shall be declared 1275 using the “rt” Common Property for the Resource. The Property Value for the “rt” Common Property 1276 shall be the list of Resource Type IDs for the Resource Types used as templates (i.e., “rt”=<list of 1277 Resource Type IDs>). 1278

Table 4. Resource Type Common Property definition 1279


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 1280 the host (i.e. Server) of the Resource. 1281

Resource Type definition 1282

Resource Type is specified as follows: 1283

• Pre-defined URI (optional) – a pre-defined URI may be specified for a specific Resource Type 1284 in an OCF specification. When a Resource Type has a pre-defined URI, all instances of that 1285 Resource Type shall use only the pre-defined URI. An instance of a different Resource Type 1286 shall not use the pre-defined URI. 1287

• Resource Type Title (optional) – a human friendly name to designate the Resource Type. 1288

• Resource Type ID – the value of "rt" property which identifies the Resource Type, (e.g., 1289 “oic.wk.p”). 1290

• Resource Interfaces – list of the interfaces that may be supported by the Resource Type. 1291

• Resource Properties – definition of all the properties that apply to the Resource Type. The 1292 Resource Type definition shall define whether a property is mandatory, conditional mandatory, 1293 or optional. 1294

• Related Resource Types (optional) – the specification of other Resource Types that may be 1295 referenced as part of the Resource Type, applicable to collections. 1296

• Mime Types (optional) – mime types supported by the resource including serializations (e.g., 1297 application/cbor, application/json, application/xml). 1298

Table 5 and Table 6 provide an example description of an illustrative foobar Resource Type and 1299 its associated Properties. 1300

Table 5. Example foobar Resource Type 1301

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 1302


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

1303

An instance of the foobar Resource Type is as shown below 1304

1305

{ "rt": ["oic.r.foobar"], "if": ["oic.if.a"], "value": "foo value" }


An example schema for the foobar Resource Type is shown below 1306

1307

Multi-value "rt" Resource 1308

Multi-value "rt" Resource means a Resource with multiple Resource Types. Such a Resource is 1309 associated with multiple Resource Types and so has an "rt" Property Value of multiple Resource 1310 Type IDs (e.g. "rt": ["oic.r.switch.binary", "oic.r.light.brightness"]). The order of the Resource Type 1311 IDs in the “rt” Property Value is meaningless. For example, "rt": ["oic.r.switch.binary", 1312 "oic.r.light.brightness"] and "rt": ["oic.r.light.brightness", "oic.r.switch.binary"] have the same 1313 meaning. 1314

Resource Types for multi-value “rt” Resources shall satisfy the following conditions. 1315

• Property Name – Property Names for each Resource Type shall be unique (within the scope 1316 of the multi-value “rt” Resource) with the exception of Common Properties, otherwise there will 1317 be conflicting Property semantics. If two Resource Types have a Property with the same 1318 Property Name, a multi-value “rt” Resource shall not be composed of these Resource Types. 1319

A multi-value "rt" Resource satisfies all the requirements for each Resource Type and conforms to 1320 the RAML/JSON definitions for each component Resource Type. Thus the mandatory Properties 1321 of a multi-value "rt" Resource shall be the union of all the mandatory Properties of each Resource 1322 Type. For example, mandatory Properties of a Resource with "rt": ["oic.r.switch.binary", 1323 "oic.r.light.brightness"] are "value" and "brightness", where the former is mandatory for 1324 "oic.r.switch.binary" and the latter for "oic.r.light.brightness". 1325

The multi-value “rt” Resource Interface set shall be the union of the sets of interfaces from the 1326 component Resource Types. The Resource Representation in response to a CRUDN action on an 1327 Interface shall be the union of the schemas that are defined for that Interface. The Default Interface 1328 for a multi-value “rt” Resource shall be the baseline Interface (“oic.if.baseline”) as that is the only 1329 guaranteed common Interface between the Resource Types. 1330

For clarity if each Resource Type supports the same set of Interfaces, then the resultant multi-1331 value "rt" Resource has that same set of Interfaces with a Default Interface of baseline 1332 (“oic.if.baseline”). 1333

See section 7.10.3 for the handling of query parameters as applied to a multi-value “rt” Resource. 1334

7.5 Device Type 1335

A Device Type is a class of Device. Each Device Type defined will include a list of minimum 1336 Resource Types that a device shall implement for that Device Type. A device may expose 1337 additional standard and vendor defined Resource Types beyond the minimum list. The Device 1338 Type is used in Resource discovery as specified in section 11.3.4. 1339

Like a Resource Type, a Device Type can be used in the Resource Type Common Property or in 1340 a Link using the Resource Type Parameter. 1341

{ "$schema": "http://json-schema.org/draft-04/schema", "type": "object", "properties": { "rt": {"type": "string"}, "if": {"type": "string"}, "value": {"type": "string"} }, "required": ["rt", "if", "value"] }


A Device Type may either be pre-defined (in vertical domain specifications) or in custom definitions 1342 by manufacturers, end users, or developers of Devices (vendor-defined Device Types). Device 1343 Types and their definition details may be communicated out of band (like in documentation). 1344

Every Device Type shall be identified with a Resource Type ID using the same syntax constraints 1345 as a Resource Type. 1346

7.6 Interface 1347

Introduction 1348

An Interface provides first a view into the Resource and then defines the requests and responses 1349 permissible on that view of the Resource. So this view provided by an Interface defines the context 1350 for requests and responses on a Resource. Therefore, the same request to a Resource when 1351 targeted to different Interfaces may result in different responses. 1352

An Interface may be defined by either this specification (a Core Interface), the OCF vertical domain 1353 specifications (a “vertical Interface) or manufacturers, end users or developers of Devices (a 1354 “vendor-defined Interface”). 1355

The Interface Property lists all the Interfaces the Resource support. All resources shall have at 1356 least one Interface. The Default Interface shall be defined by an OCF specification and inherited 1357 from the Resource Type definition. The Default Interface associated with all Resource Types 1358 defined in this specification shall be the supported Interface listed first within the applicable 1359 enumeration in the definition of the Resource Type (see Annex D). All Default Interfaces specified 1360 in an OCF specification shall be mandatory. 1361

In addition to any OCF specification defined interface, all Resources shall support the Baseline 1362 Interface (“oic.if.baseline”) as defined in section 7.6.3.2. 1363

See section 7.10.4 for the use of queries to enable selection of a specific interface in a request. 1364

An Interface may accept more than one media type. An Interface may respond with more than one 1365 media type. The accepted media types may be different from the response media types. The media 1366 types are specified with the appropriate header parameters in the transfer protocol. (NOTE: This 1367 feature has to be used judiciously and is allowed to optimize representations on the wire) Each 1368 Interface shall have at least one media type. 1369

1370

Interface Property 1371

Table 7. Resource Interface Property definition 1372


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 1373 (Table 7) as "if=<array of Interfaces>". The Property Value of an Interface Property shall be a 1374 lower case string with segments separated by a "." (dot). The string "oic", when used as the first 1375 segment in the Interface Property Value, is reserved for OCF-defined Interfaces. The Interface 1376 Property Value may also be a reference to an authority similar to IANA that may be used to find 1377 the definition of an Interface. A Resource Type shall support one or more of the Interfaces defined 1378 in section 7.6.3. 1379


Interface methods 1380

7.6.3.1 Overview 1381

The OCF -defined Interfaces are listed in the table below: 1382

Table 8. OCF standard Interfaces 1383

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.

1384

7.6.3.2 Baseline Interface 1385

7.6.3.2.1 Overview 1386

The Representation that is visible using the “baseline” Interface includes all the Properties of the 1387 Resource including the Common Properties. The “baseline” Interface shall be defined for all 1388 Resource Types. All Resources shall support the “baseline” Interface. 1389

7.6.3.2.2 Use of RETRIEVE 1390

The “baseline” Interface is used when a Client wants to retrieve all Properties of a Resource; that 1391 is the Server shall respond with a Resource representation that includes all of the implemented 1392 Properties of the Resource. When the Server is unable to send back the whole Resource 1393 representation, it shall reply with an error message. The Server shall not return a partial Resource 1394 representation. 1395

An example response to a RETRIEVE request using the baseline Interface is shown below: 1396


{ "rt": ["oic.r.temperature"], "if": ["oic.if.a","oic.if.baseline"], "temperature": 20, "units": "C", "range": [0,100] }

1397

7.6.3.2.3 Use of UPDATE 1398

Using the baseline Interface, all Properties of a Resource with the exception of Common Properties 1399 may be modified using an UPDATE request with a list of Properties and their desired values if a 1400 Resource Type has an associated schema for UPDATE using baseline. 1401

7.6.3.3 Link List Interface 1402

7.6.3.3.1 Overview 1403

The links list Interface provides a view into the list of Links in a Collection (Resource). The 1404 Representation visible through this Interface has only the Links defined in the Property Value of 1405 the “links” Property – so this Interface is used to manipulate or interact with the list of Links in a 1406 Collection. The Links list may be RETRIEVEd using this Interface. 1407

The Interface definition and semantics are given as follows: 1408

• The links list Interface name shall be “oic.if.ll”. 1409

• If specified in a request (usually in the request header), the serialization in the response shall 1410 be in the format expected in the request. 1411

• In response to a RETRIEVE request on the “links list” Interface, the URIs of the referenced 1412 Resources shall be returned as a URI reference. 1413

• If there are no links present in a Resource, then an empty list shall be returned. 1414

• The Representation determined by this Interface depends on the requesting Client. For a Client 1415 that includes an OCF-Accept-Content-Format-Version option as defined in section 12.2.5 in 1416 the request the response only includes the Property Value of the “links” Property, hence a 1417 Collection or /oic/res response with oic.if.ll is an array of OCF Links. For a Client that does not 1418 include an OCF-Accept-Content-Format-Version option the response is as defined in E.5. 1419

7.6.3.3.2 Example: “links list” Interface 1420

Example: Request to a Collection 1421

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

}

]

1422

7.6.3.4 Batch Interface 1423

7.6.3.4.1 Overview 1424

The batch Interface is used to interact with a collection of Resources using a single/same Request. 1425 The batch Interface can be used to RETRIEVE or UPDATE the Properties of the "linked" 1426 Resources with a single request. 1427

The batch Interface is defined as follows: 1428

• The batch Interface name is "oic.if.b" 1429


• A Collection Resource has linked Resources that are represented as URIs. In the "href" 1430 Property of the batch payload the URI shall be fully qualified for remote Resources and a 1431 relative referenceor local Resources. 1432

• The original request is modified to create new requests targeting each of the linked Resources 1433 in the Collection by substituting the URI in the original request with the URI of the linked 1434 Resource. The payload in the original request is replicated in the payload of the new requests. 1435

• The requests shall be forwarded assuming use of the Default Interface of the linked Resources 1436 unless otherwise stated. 1437

• Requests shall only be forwarded to linked Resources that are identified by relation types "item" 1438 or "hosts" ("hosts" is the default relation type should the "rel" Link Parameter not be present). 1439 Requests shall not be forwarded to linked Resources that do not contain the "item" or "hosts" 1440 relation type values. 1441

• The Collection itself may be included in the batch response by exposing a single Link with the 1442 link relation "self" along with "item" within the Collection (i.e. "rel": ["self","item"], see also the 1443 example in section 7.6.3.4.2) and ensuring that the "if" Link Parameter of the "self" Link 1444 contains an Interface(s) that do(-es) not expose the "links" Property, i.e. "oic.if.b" and not 1445 "oic.if.baseline" or "oic.if.ll", otherwise Link resolution becomes an infinite loop. 1446

• Any request forwarded to a linked Resource that is also a Collection (including a "self" Link) 1447 shall also have the batch Interface applied. 1448

• All the tesponses from the linked Resources shall be aggregated into a single Response to the 1449 Client. The Server may timeout the response to a time window, the Server may choose any 1450 appropriate window based on conditions. 1451

• If a linked Resource cannot process the request, an empty response, i.e. a JSON object with 1452 no content ("{}") as the representation for the "rep" Property, or error response should the 1453 linked Resource Type provide an error schema or diagnostic payload, shall be returned by the 1454 linked Resource. These empty or error responses for all linked Resources that exhibit an error 1455 shall be included in the aggregated response to the original Client request. See the example 1456 in section 7.6.3.4.2. 1457

• If any of the linked Resources returns an error response, the aggregated response sent to the 1458 Client shall also indicate an error (e.g. 4.xx in CoAP). If any of the other linked Resources 1459 returns a successful response, the aggregated response payload shall include that success 1460 response payload. 1461

• The aggregated response shall be an array of objects representing the responses from each 1462 linked Resource. Each object in the response shall include at least two items: (1) the URI of 1463 the linked Resource (fully qualified for remote Resources, or a relative reference for local 1464 Resources) as "href": <URI> and (2) the individual response object or array of objects if the 1465 linked Resource is itself a Collection using "rep" as the key, e.g. "rep": { < representation of 1466 individual response> }. 1467

• Linked Resources referenced in the Collection may be observed using the batch Interface. The 1468 observe mechanism shall work as defined in 11.4.2 with the observe request forwarded to each 1469 of the linked Resources. All responses to the request shall be aggregated into a single 1470 response to the Client using the same representations and status codes as for RETRIEVE 1471 operations using the batch Interface. 1472

• Should any one of the linked Resources fail to honour the observe request the response to the 1473 batch observe request shall also indicate that the entire request was not honoured using the 1474 mechanism described in section 11.4.2.3; in this error case the individual successful observe 1475 requests shall be cancelled as described in section 11.4.2.6. 1476

• All notifications to the Client that initiated an observe request using the batch Interface shall 1477 use the batch representation for the Collection. This is the aggregation of any individual 1478


observe notifications received by the Device hosting the Collection from the individual observe 1479 requests that were forwarded to the linked Resources. 1480

• The Collection itself may be observed by using the links list or baseline Interfaces. 1481

• The Client may choose to restrict the linked Resources to which the request is forwarded by 1482 including additional query parameters in the request. The Server should process any additional 1483 query parameters in a request that includes "oic.if.b" as selectors for linked Resources that are 1484 to be processed by the request. 1485

• A Client shall perform UPDATE operations using the batch Interface by creating a payload that 1486 is similar to a RETRIEVE response payload from a batch Interface request. The Server shall 1487 send a separate UPDATE request to each of the linked Resources according to each "href" 1488 Property and the corresponding value of the "rep" Property. 1489

• If the "href" value is empty, denoted by a zero length string or "" in JSON, the "rep" Property 1490 shall be applied to linked Resources in the Collection. 1491

• Items with the empty "href" and link-specific "href" shall not be mixed in the same UPDATE 1492 request. 1493

• All of the Properties in the UPDATE request may not be supported by the linked Resource. In 1494 such cases, writable Properties in the UPDATE request that are supported by the linked 1495 Resource shall be modified and Properties that are not supported shall be silently ignored. 1496

• The UPDATE response shall contain the updated values using the same payload schema as 1497 RETRIEVE operations if provided by the linked Resource, along with the appropriate status 1498 code. The aggregated response payload shall reflect the known state of the updated Resource 1499 Properties after the batch update was completed. If no payload is provided by the updated 1500 Resource then an empty response (i.e. "rep": {}) shall be provided for that Resource. 1501

7.6.3.4.2 Examples: Batch Interface 1502

Note that the examples provided are illustrative and do not include all mandatory schema elements 1503 in all cases. 1504

Resources /a/room/1

{

"rt": ["oic.wk.col","x.org.example.rt.room"],

"if": ["oic.if.baseline","oic.if.b","oic.if.ll"],

"x.org.example.colour": "blue",

"x.org.example.dimension": "15bx15wx10h",

"links": [

{"href": "/a/room/1", "rel": ["self", "item"], "rt": ["oic.wk.col", "x.org.example.rt.room"], "if": ["oic.if.b"],"p": {"bm": 2} },

{"href": "/the/light/1", "rel": ["item"], "rt": ["oic.r.switch.binary"], "if": ["oic.if.a","oic.if.baseline"], "ins": "light-1", "p": {"bm": 2} },


{"href": "/the/light/2", "rel": ["item"], "rt": ["oic.r.switch.binary"], "if": ["oic.if.a" ,"oic.if.baseline"], "ins": "light-2", "p": {"bm": 2} },

{"href": "/my/fan/1", "rel": ["item"], "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "ins": "fan-1", "p": {"bm": 2} },

{"href": "/his/fan/2", "rel": ["item"], "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "ins": "fan-2", "p": {"bm": 2} },

{"href": "/the/switches/1", "rel": ["item"], "rt": ["oic.wk.col"], "if":["oic.if.ll", "oic.if.b", "oic.if.baseline"], "ins": "switches-1", "p": {"bm": 2} }

]

}

/the/light/1

{



"value": false

}

/the/light/2

{



"value": true

}

/my/fan/1

{



"value": true


}

/his/fan/2

{



"value": false

}

/the/switches/1

{

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

"if":["oic.if.ll", "oic.if.b", "oic.if.baseline"],

"links": [

{

"href": "/switch-1a",


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

"p": {"bm": 2}

}

{

"href": "/switch-1b",


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

"p": {"bm": 2 }

}

]

}

Use of batch, successful response

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 batch Interface as specified for batch requests sent to Collections)

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 /my/fan/1 (NOTE: Uses the Default Interface as specified for this resource)

GET /his/fan/2 (NOTE: Uses the Default Interface as specified for this resource)

GET /the/switches/1?rt=oic.if.b (NOTE: Uses the batch Interface for the Collection that is within the Collection)

Response:

[

{

"href": "/a/room/1",

"rep": {"x.org.example.colour": "blue","x.org.example.dimension": "15bx15wx10h"}

},

{


"rep": {"value": false}

},

{


"rep": {"value": true}

},

{



},

{




},

{

"href": "/the/switches/1",

"rep": [

{"href": "/switch-1a",

"rep": {"value": "true"}},

{"href": "/switch-1b",

"rep": {"value": "false"}}

]

}

]

Use of batch, error response

Should any of the RETRIEVE requests in the previous example fail then the response includes an empty payload for that Resource instance and an error code is sent. The example below assumes errors from "/my/fan/1" and "/the/switches/1"

Error Response:

[

{


"rep": {"x.org.example.colour": "blue","x.org.example.dimension": "15bx15wx10h"}

},

{



},

{



},

{



"rep": {}

},

{



},

{

"href": "/the/switches/1",

"rep": {}

}

]

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 UPDATE request is empty, the request is forwarded to all Resources in the Collection 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 } UPDATE /the/switches/1?if=oic.if.b { "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 has POST semantics)

UPDATE /a/room/1?if=oic.if.b [ { "href": "/the/light/1", "rep": { "value": false } },


{ "href": "/the/light/2", "rep": { "value": true } }, { "href": "/a/room/1", "rep": { "x.org.example.colour": "red" } } ] This turns /the/light/1 off, turns /the/light/2 on, and sets the colour of /a/room/1 to "red". The response will be same as response for GET /a/room/1?if=oic.if.b with the updated Property values as shown below. [

{


"rep":{"x.org.example.colour": "red",

"x.org.example.dimension": "15bx15wx10h"}

},

{



},

{



}

] Example use of additional query parameters to select items by matching Link Parameters. Turn on light 1 based on the "ins" Link Parameters 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 UPDATE request to allof the Resources in the Collection. 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 TRsource 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": "/the/light/1", "rep": { "value": false } } ]

1505

7.6.3.5 Actuator Interface 1506

The actuator Interface is the Interface for viewing Resources that may be actuated i.e. changes 1507 some value within or the state of the entity abstracted by the Resource: 1508

• The actuator Interface name shall be “oic.if.a” 1509

• The actuator Interface shall expose in the Resource Representation all mandatory Properties 1510 as defined by the applicable JSON; the actuator interface may also expose in the Resource 1511 Representation optional Properties as defined by the applicable JSON schema that are 1512 implemented by the target Device. 1513

"Heater" Resource (for illustration only): 1514

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 }

1515 "Actuator" interface in respect to "Heater" Resource (for illustration only): 1516 1517

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 }

1518

• A RETRIEVE request using this Interface shall return the Representation for this Resource 1519 subject to any query and filter parameters that may also exist 1520

• An UPDATE request using this Interface shall provide a payload or body that contains the 1521 Properties that will be updated on the target Resource. 1522

7.6.3.6 Sensor Interface 1523

The sensor Interface is the Interface for retrieving measured, sensed or capability specific 1524 information from a Resource that senses: 1525

• The sensor Interface name shall be “oic.if.s” 1526

• The sensor Interface shall expose in the Resource Representation all mandatory Properties as 1527 defined by the applicable JSON; the sensor interface may also expose in the Resource 1528 Representation optional Properties as defined by the applicable JSON schema that are 1529 implemented by the target Device. 1530

• A RETRIEVE request using this Interface shall return this Representation for the Resource 1531 subject to any query and filter parameters that may also exist 1532

• 1533


NOTE: The example here is with respect to

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 }

1534

7.6.3.7 Read-only Interface 1535

The read-only Interface exposes only the Properties that may be “read”. This includes Properties 1536 that may be “read-only”, “read-write” but not Properties that are “write-only” or “set-only”. The 1537 applicable methods that can be applied to a Resource is RETRIEVE only. An attempt by a Client 1538 to apply a method other than RETRIEVE to a Resource shall be rejected with an error response 1539 code. 1540

7.6.3.8 Read-write Interface 1541

The read-write Interface exposes only the Properties that may be “read” and “written”. The “read-1542 only” Properties shall not be included in Representation for the “read-write” Interface. This is a 1543 generic Interface to support “reading” and “setting” Properties in a Resource. The applicable 1544 methods that can be applied to a Resource are RETRIEVE and UPDATE only. An attempt by a 1545 Client to apply a method other than RETRIEVE or UPDATE to a Resource shall be rejected with 1546 an error response code. 1547


7.7 Resource representation 1548

Resource representation captures the state of a Resource at a particular time. The resource 1549 representation is exchanged in the request and response interactions with a Resource. A Resource 1550 representation may be used to retrieve or update the state of a resource. 1551

The resource representation shall not be manipulated by the data connectivity protocols and 1552 technologies (e.g., CoAP, UDP/IP or BLE). 1553

7.8 Structure 1554

Introduction 1555

In many scenarios and contexts, the Resources may have either an implicit or explicit structure 1556 between them. A structure can, for example, be a tree, a mesh, a fan-out or a fan-in. The 1557 Framework provides the means to model and map these structures and the relationships among 1558 Resources. The primary building block for resource structures in Framework is the collection. A 1559 collection represents a container, which is extensible to model complex structures. 1560

Resource Relationships 1561

Resource relationships are expressed as Links. A Link embraces and extends typed web links 1562 concept as a means of expressing relationships between Resources. A Link consists of a set of 1563 Parameters that define: 1564

• a context URI, 1565

• a target URI, 1566

• a relation from the context URI to the target URI 1567

• elements that provide metadata about the target URI, the relationship or the context of the Link. 1568

The target URI is mandatory and the other items in a Link are optional. Additional items in the Link 1569 may be made mandatory based on the use of the links in different contexts (e.g. in collections, in 1570 discovery, in bridging etc.). Schema for the Link payload is provided in Annex D. 1571

An example of a Link is shown in: 1572

{"href": "/switch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", /room2"oic.if.baseline"], "p": {"bm": 3}, "rel": "item"}

Two Links are distinct from each other when at least one parameter is different. For example the 1573 two Links shown below are distinct and can appear in the same list of Links. 1574

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

The specification may mandate Parameters and Parameter values as required for certain 1575 capabilities. For all Links returned in a response to a RETRIEVE on “/oic/res”, if a Link does not 1576 explicitly include the “rel” Parameter, a value of “rel”=”hosts” shall be assumed. The relation value 1577 of “hosts” is defined by IETF RFC 6690, the value of "item" by IETF RFC 6573, and the value of 1578 "self" by IETF RFC 4287 and all are registered in the IANA Registry for Link Relations at 1579 [http://www.iana.org/assignments/link-relations/link-relations.xhtml] 1580

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


As shown in D.2.8 the relation between the context URI and target URI in a Link is specified using 1581 the “rel” JSON element and the value of this element specifies the particular relation. 1582

The context URI of the Link shall implicitly be the URI of the Resource (or specifically a Collection) 1583 that contains the Link unless the Link specifies the anchor parameter. The anchor parameter is 1584 used to change the context URI of a Link – the relationship with the target URI is based off the 1585 anchor URI when the anchor is specified. Anchor parameter uses transfer protocol URI for OIC 1.1 1586 Link (e.g. "anchor": "coaps://[fe80::b1d6]:44444") and OCF URI defined in Sec 6 for OCF 1.0 Links 1587 (e.g. "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989"). 1588

An example of using anchors in the context of Collections – a floor has rooms and rooms have 1589 lights – the lights may be defined in floor as Links but the Links will have the anchor set to the URI 1590 of the rooms that contain the lights (the relation is contains). This allows all lights in a floor to be 1591 turned on or off together while still having the lights defined with respect to the rooms that contain 1592 them (lights may also be turned on by using the room URI too). See example use of anchor in 1593 Link: 1594

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

1595

7.8.2.1 Parameters 1596

7.8.2.1.1 “ins” or Link Instance Parameter 1597

The “ins” parameter identifies a particular Link instance in a list of Links. The "ins" parameter may 1598 be used to modify or delete a specific Link in a list of Links. The value of the “ins” parameter is set 1599 at instantiation of the Link by the OCF Device (Server) that is hosting the list of Links – once it has 1600 been set, the “ins” parameter shall not be modified for as long as the Link is a member of that list. 1601

7.8.2.1.2 “p” or Policy Parameter 1602

The Policy Parameter defines various rules for correctly accessing a Resource referenced by a 1603 target URI. The Policy rules are configured by a set of key-value pairs as defined below. 1604

The policy Parameter "p" is defined by: 1605

• “bm” key: The “bm” key corresponds to an integer value that is interpreted as an 8-bit bitmask. 1606 Each bit in the bitmask corresponds to a specific Policy rule. The following rules are specified 1607


for “bm”: 1608 1609

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.

1610

Note that if all the bits in “bm” are defined to value 0, then the “bm” key may be omitted entirely 1611 from “p” as an efficiency measure. However, if any bit is set to value 1, then “bm” shall be 1612 included in “p” and all the bits shall be defined appropriately. 1613

• "sec" and "port" in the remaining bullets shall be used only in a response payload when the 1614 request does not include an OCF-Accept-Content-Format-Version option as defined in section 1615 12.2.5. In a payload sent in response to a request that includes an OCF-Accept-Content-1616 Format-Version option "sec" and "port" shall not be used and instead the "eps" Parameter shall 1617 provide the information for an encrypted connection. See E.2.8 for the schema for the "p" 1618 Parameter that includes "sec" and "port". 1619

• "sec" key: The “sec” key corresponds to a Boolean value that indicates whether the Resource 1620 referenced by the target URI is accessed via an encrypted connection. If “sec” is true, the 1621 resource is accessed via an encrypted connection, using the “port” specified (see below). If 1622


“sec” is false, the resource is accessed via an unencrypted connection, or via an encrypted 1623 connection (if such a connection is made using the “port” settings for another Resource, for 1624 which “sec” is true). 1625

• "port" key: The “port” key corresponds to an integer value that is used to indicate the port 1626 number where the Resource referenced by the target URI may be accessed via an encrypted 1627 connection. 1628

• If the Resource is only available via an encrypted connection (i.e. DTLS over IP), then 1629

o "p" shall include the "sec" key and its value shall be true. 1630

o "p" shall include the "port" key and its value shall be the port number where the 1631 encrypted connection may be established. 1632

• If the Resource is only available via an unencrypted connection, then 1633

o "p" shall include the "sec" key and its value shall be false or "p" shall omit the "sec" 1634 key; the default value of "sec" is false. 1635

o "p" shall omit the "port" key. 1636

• • If the Resource is available via both an encrypted and unencrypted connection, then 1637

o "p" shall include the "sec" key and its value shall be false or "p" shall omit the "sec" 1638 key; the default value of "sec" is false. 1639

o “p” may omit the “port” key. If the “port” key is omitted, the Resource shall be 1640 available using the same “port” information as another Resource on the Device for 1641 which "sec" is true. 1642

• Access to the Resource on the port specified by the “port” key shall be made by an encrypted 1643 connection (e.g. coaps://). (Note that unencrypted connection to the Resource may be possible 1644 on a separate port discovered thru multicast discovery). 1645

• Note that access to the Resource is controlled by the ACL for the Resource. A successful 1646 encrypted connection does not ensure that the requested action will succeed. See 1647 OCF Security – Access Control section for more information. 1648

Example 1: below shows the Policy Parameter for a Resource that is discoverable but not 1649 observable, and for which authenticated accesses shall be done via CoAPS port 33275: 1650

1651

1652

Example 2: below shows a self-link, i.e. the “/oic/res” Link in itself that is discoverable and 1653 observable. 1654

1655

1656

1657 1658 1659 1660

1661

7.8.2.1.3 “type” or Media Type Parameter 1662

The “type” Parameter may be used to specify the various media types that are supported by a 1663 specific target Resource. The default type of "application/cbor" shall be used when the “type” 1664

"p": { "bm": 1}

{ "href": "/oic/res", "rel": "self", "rt": ["oic.wk.res"], "if": ["oic.if.ll", "oic.if.baseline"], "p": {"bm": 3} }


element is omitted. Once a Client discovers this information for each Resource, it may use one of 1665 the available representations in the appropriate header field of the Request or Response. 1666

7.8.2.1.4 “di” or Device ID parameter 1667

The “di” Parameter specifies the device ID of the Device that hosts the target Resource defined in 1668 the in the “href” Parameter. 1669

The device ID may be used to qualify a relative reference used in the “href” or to lookup endpoint 1670 information for the relative reference. 1671

7.8.2.1.5 “eps” Parmeter 1672

The "eps" Parameter indicates the Endpoint information of the target Resource. 1673

"eps" shall have as its value an array of items and each item represents Endpoint information with 1674 "ep" and "pri" as specified in 10.2. "ep" is mandatory but "pri" is optional. 1675

Example of "eps" with multiple Endpoints: 1676

"eps": [ {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, {"ep": "coaps://[fe80::b1d6]:1122"}, {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} ]

1677

When "eps" is present in a link, the Endpoint information in "eps" can be used to access the target 1678 Resource referred by the "href" Parameter. 1679

When present, max-age information (e.g. Max-Age option for CoAP defined in IETF RFC 7252) 1680 determines the maximum time "eps" values may be cached before they are considered stale. 1681

7.8.2.2 Formatting 1682

When formatting in JSON, the list of Links shall be an array. 1683

7.8.2.3 List of Links in a Collection 1684

A list of Links in a Resource shall be included in that Resource as the value of the “links” Property 1685 of that Resource. A Resource that contains Links is a Collection. 1686

A Resource with a list of Links: 1687

/Room1 { "rt": ["my.room"], "if": ["oic.if.ll", "oic.if.baseline" ], "color": "blue", "links": [ { "href": "/oic/d", "rt": ["oic.d.light", "oic.wk.d"], "if": [ "oic.if.r", "oic.if.baseline" ], "p": {"bm": 1} }, {


"href": "/oic/p", "rt": ["oic.wk.p"], "if": [ "oic.if.r", "oic.if.baseline" ], "p": {"bm": 1} }, { "href": "/switch", "rt": ["oic.r.switch.binary"], "if": [ "oic.if.a", "oic.if.baseline" ], "p": {"bm": 3}, "mt": [ "application/cbor", "application/exi+xml" ] }, { "href": "/brightness", "rt": ["oic.r.light.brightness"], "if": [ "oic.if.a", "oic.if.baseline" ], "p": {"bm": 3} }

]

}

1688

Collections 1689

7.8.3.1 Overview 1690

A Resource that contains one or more references (specified as Links) to other resources is a 1691 Collection. These reference may be related to each other or just be a list; the Collection provides 1692 a means to refer to this set of references with a single handle (i.e. the URI). A simple resource is 1693 kept distinct from a collection. Any Resource may be turned into a Collection by binding resource 1694 references as Links. Collections may be used for creating, defining or specifying hierarchies, 1695 indexes, groups, and so on. 1696

A Collection shall have at least one Resource Type and at least one Interface bound at all times 1697 during its lifetime. During creation time of a collection the Resource Type and interfaces are 1698 specified. The initial defined Resource Types and interfaces may be updated during its life time. 1699 These initial values may be overridden using mechanism used for overriding in the case of a 1700 Resource. Additional Resource Types and Interfaces may be bound to the Collection at creation 1701 or later during the lifecycle of the Collection. 1702

A Collection shall define the “links” Property. The value of the “links” Property is an array with zero 1703 or more Links. The target URIs in the Links may reference another Collection or another Resource. 1704 The referenced Collection or Resource may reside on the same Device as the Collection that 1705 includes that Link (called a local reference) or may reside on another Device (called a remote 1706 reference). The context URI of the Links in the “links” array shall (implicitly) be the Collection that 1707 contains that “links” property. The (implicit) context URI may be overridden with explicit 1708 specification of the “anchor” parameter in the Link where the value of “anchor” is the new base of 1709 the Link. 1710

A Resource may be referenced in more than one Collection, therefore, a unique parent-child 1711 relationship is not guaranteed. There is no pre-defined relationship between a Collection and the 1712 Resource referenced in the Collection, i.e., the application may use Collections to represent a 1713 relationship but none is automatically implied or defined. The lifecycles of the Collection and the 1714 referenced Resource are also independent of one another. 1715


If the “drel” property is defined for the Collection then all Links that don’t explicitly specify a 1716 relationship shall inherit this default relationship in the context of that Collection. The default 1717 relationship defines the implicit relationship between the Collection and the target URI in the Link. 1718

A Property "links" represents the list of Links in a Collection. "links" Property has, as its value, an 1719 array of items and each item is an OCF Link as shown: 1720

1721

1722

A Collection may be: 1723

• A pre-defined Collection where the Collection has been defined a priori and the Collection is 1724 static over its lifetime. Such Collections may be used to model, for example, an appliance that 1725 is composed of other devices or fixed set of resource representing fixed functions. 1726

• A Device local Collection where the Collection is used only on the Device that hosts the 1727 Collection. Such collections may be used as a short-hand on a client for referring to many 1728 Servers as one. 1729

• A centralized Collection where the Collection is hosted on an Device but other Devices may 1730 access or update the Collection 1731

• A hosted Collection where the collection is centralized but is managed by an authorized agent 1732 or party. 1733

7.8.3.2 Collection Properties 1734

A Collection shall define the “links” Property. In addition, other Properties may be defined for the 1735 Collection by the Resource Type. The mandatory and recommended Common Properties for a 1736

/my/house { "rt": ["my.r.house"], "color": "blue", "n": "myhouse", "links": [ { "href": "/door", "rt": ["oic.r.door"], "if": ["oic.if.b", "oic.if.ll", "oic.if.baseline"] }, { "href": "/door/lock", "rt": ["oic.r.lock"], "if": ["oic.if.b", "oic.if.baseline"], "type": ["application/cbor", "application/exi+xml"] }, { "href": "/light", "rt": ["oic.r.light"], "if": ["oic.if.s", "oic.if.baseline"] }, { "href": "/binarySwitch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "type": ["application/cbor"] } ] }

IRI/URI (resource)

Properties (resource)

Parameters (link)


Collection are shown in Table 9. This list of Common Properties is in addition to those defined for 1737 Resources in section 7.3.2. 1738

Table 9. Common Properties for Collections (in addition to Common Properties defined in 1739 section 7.3.2) 1740

Property Description Property name Value Type Mandatory

Links The set of links in the collection “links” json Array of Links

Yes

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

1741

The Properties of a Collection may not be modified. 1742

7.8.3.3 Default Resource Type 1743

A default Resource Type, “oic.wk.col”, shall be available for Collections. This Resource Type shall 1744 be used only when another type has not been defined on the Collection or when no Resource Type 1745 has been specified at the creation of the Collection. 1746

The default Resource Type provides support for the Common Properties including the “links” 1747 Property. For the default Resource Type, the value of “links” shall be a simple array of Links. 1748

The default Resource Type shall support the ‘baseline’ and ‘links list’ Interfaces. The default 1749 Interface shall be the ‘links list’ Interface. 1750

1751

7.9 Third (3rd) party specified extensions 1752

This section describes how a 3rd party may add Device Types, Resource Types, 3rd party defined 1753 Properties to an existing or 3rd party defined Resource Type, 3rd party defined enumeration values 1754 to an existing enumeration and 3rd party defined parameters to an existing defined Property. 1755

A 3rd party may specify additional (non-OCF) Resources within an OCF Device. A 3rd party may 1756 also specify additional Properties within an existing OCF defined Resource Type. Further a 3rd 1757 party may extend an OCF defined enumeration with 3rd party defined values. 1758

A 3rd party defined Device Type may expose both 3rd party and OCF defined Resource Types. A 1759 3rd party defined Device Type must expose the mandatory Resources for all OCF Devices defined 1760 within this specification. 1761

A 3rd party defined Resource Type shall include any mandatory Properties defined in this 1762 specification and also any vertical specified mandatory Properties. All Properties defined within a 1763 3rd party defined Resource Type that are part of the OCF namespace that are not Common 1764 Properties as defined in this specification shall follow the 3rd party defined Property rules in Table 1765 10. 1766


The following table defines the syntax rules for 3rd party defined Resource Type elements. Within 1767 the table the term “Domain_Name” refers to a domain name that is owned by the 3rd party that is 1768 defining the new element. 1769

Table 10. 3rd party defined Resource elements 1770

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 3rd party defined values in an OCF specified enumeration

Enumeration Property Value

x.<Domain_Name>.<enum value>

Additional 3rd party defined parameter in an OCF specified Property

Parameter key word x.<Domain_Name>.<parameter keyword>

1771

With respect to the use of the Domain_Name in this scheme the labels are reversed from how they 1772 appear in DNS or other resolution mechanisms. The 3rd party defined Device Type and Resource 1773 Type otherwise follow the rules defined in section 7.4.2 Resource Type Property. 3rd party defined 1774 Resource Types should be registered in the IANA Constrained RESTful Environments (CoRE) 1775 Parameters registry. 1776

For example: 1777

x.com.samsung.galaxyphone.accelerator 1778

x.com.cisco.ciscorouterport 1779

x.com.hp.printerhead 1780

x.org.allseen.newinterface.newproperty 1781

7.10 Query Parameters 1782

Introduction 1783

Properties and Parameters (including those that are part of a Link) may be used in the query part 1784 of a URI (see section 6.2.1) as one criterion for selection of a particular Resource. This is done by 1785 declaring the Property (i.e. <Property Name> = <desired Property Value>) as one of the segments 1786 of the query. Only ASCII strings are permitted in query filters, and NULL characters are disallowed 1787 in query filters. This means that only Property Values with ASCII characters may be matched in a 1788 query filter. 1789

The Resource is selected when all the declared Properties or Link Parameters in the query match 1790 the corresponding Properties or Link Parameters in the target. 1791

Use of multiple parameters within a query 1792

When a query contains multiple separate query parameters these are delimited by an "&" as 1793 described in section 6.2.1. 1794

A Client may apply multiple separate query parameters, for 1795 example "?ins=light&rt=oic.r.switch.binary". If such queries are supported by the Server this shall 1796 be accomplished by matching "all of" the different query parameter types (“rt”, “ins”, “if”, etc) 1797 against the target of the query. In the example, this resolves to an instance of oic.r.switch.binary 1798


that also has an “ins” populated as “light". There is no significance applied to the order of the query 1799 parameters. 1800 1801 A Client may select more than one Resource Type using repeated query parameters, for example 1802 "?rt=oic.r.switch.binary&rt=oic.r.ramptime". If such queries are supported by the Server this shall 1803 be accomplished by matching "any of" the repeated query parameters against the target of the 1804 query. In the example, any instances of "oic.r.switch.binary" and/or "oic.r.ramptime" that may exist 1805 are selected. 1806 1807 A Client my combine both multiple repeated parameters and multiple separate parameters in a 1808 single query, for example "?if=oic.if.b&ins=light&rt=oic.r.switch.binary&rt=oic.r.ramptime". If such 1809 queries are supported by the Server this shall be accomplished by matching "any of" the repeated 1810 query parameters and then matching “all of” the different query parameter types. In the example 1811 any instances of "oic.r.switch.binary" and/or "oic.r.ramptime" that also have an "ins" of "light" that 1812 may exist are selected in a batch response. 1813 1814

Note that the parameters within a query string are represented within the actual messaging 1815 protocol as defined in section 12. 1816

Application to multi-value “rt” Resources 1817

An "rt" query for a multi-value "rt" Resource with the Default Interface of "oic.if.a", "oic.if.s", "oic.if.r", 1818 "oic.if.rw" or "oic.if.baseline" is an extension of a generic "rt" query. When a Server receives a 1819 RETRIEVE request for a multi-value "rt" Resource with an "rt" query, (i.e. GET 1820 /ResExample?rt=oic.r.foo), the Server should respond only when the query value is an item of the 1821 "rt" Property Value of the target Resource and should send back only the Properties associated 1822 with the query value(s). For example, upon receiving GET /ResExample?rt=oic.r.switch.binary 1823 targeting a Resource with "rt": ["oic.r.switch.binary", "oic.r.light.brightness"], the Server responds 1824 with only the Properties of oic.r.switch.binary. 1825

Interface specific considerations for queries 1826

7.10.4.1 Interface selection 1827

When an Interface is to be selected for a request, it shall be specified as a query parameter in the 1828 URI of the Resource in the request message. If no query parameter is specified, then the Default 1829 Interface shall be used. If the selected Interface is not one of the permitted Interfaces on the 1830 Resource then selecting that Interface is an error and the Server shall respond with an error 1831 response code. 1832

For example, the baseline Interface may be selected by adding “if=oic.if.baseline” to the list of 1833 query parameters in the URI of the target Resource. For example: “GET /oic/res?if=oic.if.baseline”. 1834

7.10.4.2 Batch Interface 1835

See section 7.6.3.4 for details on the batch Interface itself. Query parameters may be used with 1836 the batch Interface in order to select particular Resources in a Collection for retrieval or update; 1837 these parameters are used to select items in the Collection by matching Link Parameter Values. 1838

When Link selection query parameters are used with RETRIEVE operations applied using the 1839 batch Interface, only the Resources in the Collection with matching Link Parameters should be 1840 returned. 1841

When Link selection query parameters are used with UPDATE operations applied using the batch 1842 Interface, only the Resources having matching Link Parameters should be updated. 1843

See 7.6.3.4.2 for examples of RETRIEVE and UPDATE operations that use Link selection query 1844 parameters. 1845


8 CRUDN 1846

8.1 Overview 1847

CREATE, RETRIEVE, UPDATE, DELETE, and NOTIFY (CRUDN) are operations defined for 1848 manipulating Resources. These operations are performed by a Client on the resources contained 1849 in n Server. 1850

On reception of a valid CRUDN operation n Server hosting the Resource that is the target of the 1851 request shall generate a response depending on the Interface included in the request; or based 1852 on the Default Interface for the Resource Type if no Interface is included. 1853

CRUDN operations utilize a set of parameters that are carried in the messages and are defined in 1854 Table 11. A Device shall use CBOR as the default payload (content) encoding scheme for resource 1855 representations included in CRUDN operations and operation responses; a Device may negotiate 1856 a different payload encoding scheme (e.g, see in section 12.2.4 for CoAP messaging). The 1857 following subsections specify the CRUDN operations and use of the parameters. The type 1858 definitions for these terms will be mapped in the messaging section for each protocol. 1859

Table 11. Parameters of CRUDN messages 1860

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 1861

The CREATE operation is used to request the creation of new Resources on the Server. The 1862 CREATE operation is initiated by the Client and consists of three steps, as depicted in Figure 9 1863 and described below. 1864

1865


1866

Figure 9. CREATE operation 1867

CREATE request 1868

The CREATE request message is transmitted by the Client to the Server to create a new Resource 1869 by the Server. The CREATE request message will carry the following parameters: 1870

• fr: Unique identifier of the Client 1871

• to: URI of the target resource responsible for creation of the new resource. 1872

• ri: Identifier of the CREATE request 1873

• cn: Information of the resource to be created by the Server 1874

i) cn will include the URI and Resource Type property of the resource to be created. 1875

ii) cn may include additional properties of the resource to be created. 1876

• op: CREATE 1877

Processing by the Server 1878

Following the receipt of a CREATE request, the Server may validate if the Client has the 1879 appropriate rights for creating the requested resource. If the validation is successful, the Server 1880 creates the requested resource. The Server caches the value of ri parameter in the CREATE 1881 request for inclusion in the CREATE response message. 1882

CREATE response 1883

The Server shall transmit a CREATE response message in response to a CREATE request 1884 message from a Client. The CREATE response message will include the following parameters. 1885

• fr: Unique identifier of the Server 1886

• to: Unique identifier of the Client 1887

• ri: Identifier included in the CREATE request 1888

• cn: Information of the resource as created by the Server. 1889

i) cn will include the URI of the created resource. 1890

ii) cn will include the resource representation of the created resource. 1891

• rs: The result of the CREATE operation 1892

8.3 RETRIEVE 1893

The RETRIEVE operation is used to request the current state or representation of a Resource. 1894 The RETRIEVE operation is initiated by the Client and consists of three steps, as depicted in 1895 Figure 10 and described below. 1896

1897


1898

Figure 10. RETRIEVE operation 1899

RETRIEVE request 1900

RETRIEVE request message is transmitted by the Client to the Server to request the 1901 representation of a Resource from a Server. The RETRIEVE request message will carry the 1902 following parameters. 1903


• to: URI of the resource the Client is targeting 1905

• ri: Identifier of the RETRIEVE request 1906

• op: RETRIEVE 1907


Following the receipt of a RETRIEVE request, the Server may validate if the Client has the 1909 appropriate rights for retrieving the requested data and the properties are readable. The Server 1910 caches the value of ri parameter in the RETRIEVE request for use in the response. 1911

RETRIEVE response 1912

The Server shall transmit a RETRIEVE response message in response to a RETRIEVE request 1913 message from a Client. The RETRIEVE response message will include the following parameters. 1914



• ri: Identifier included in the RETRIEVE request 1917

• cn: Information of the resource as requested by the Client 1918

i) cn should include the URI of the resource targeted in the RETRIEVE request 1919

1920

• rs: The result of the RETRIEVE operation 1921

8.4 UPDATE 1922

The UPDATE operation is either a Partial UPDATE or a complete replacement of the information 1923 in a Resource in conjunction with the interface that is also applied to the operation. The UPDATE 1924 operation is initiated by the Client and consists of three steps, as depicted in Figure 11 and 1925 described below. 1926

1927


1928

Figure 11. UPDATE operation 1929

UPDATE request 1930

The UPDATE request message is transmitted by the Client to the Server to request the update of 1931 information of a Resource on the Server. The UPDATE request message will carry the following 1932 parameters. 1933


• to: URI of the resource targeted for the information update 1935

• ri: Identifier of the UPDATE request 1936

• op: UPDATE 1937

• cn: Information, including properties, of the resource to be updated at the target resource 1938


Following the receipt of an UPDATE request, the Server may validate if the Client has the 1940 appropriate rights for updating the requested data. If the validation is successful the Server 1941 updates the target Resource information according to the information carried in cn parameter of 1942 the UPDATE request message. The Server caches the value of ri parameter in the UPDATE 1943 request for use in the response. 1944

An UPDATE request that includes Properties that are read-only shall be rejected by the Server 1945 with an rs indicating a bad request. 1946

An UPDATE request shall be applied only to the Properties in the target resource visible via the 1947 applied interface that support the operation. An UPDATE of non-existent Properties is ignored. 1948

UPDATE response 1949

The UPDATE response message will include the following parameters: 1950



• ri: Identifier included in the UPDATE request 1953

• rs: The result of the UPDATE request 1954

The UPDATE response message may also include the following parameters: 1955

• cn: The Resource representation following processing of the UPDATE request 1956

8.5 DELETE 1957

The DELETE operation is used to request the removal of a Resource. The DELETE operation is 1958 initiated by the Client and consists of three steps, as depicted in Figure 12 and described below. 1959

1960


1961

Figure 12. DELETE operation 1962

DELETE request 1963

DELETE request message is transmitted by the Client to the Server to delete a Resource on the 1964 Server. The DELETE request message will carry the following parameters: 1965


• to: URI of the target resource which is the target of deletion 1967

• ri: Identifier of the DELETE request 1968

• op: DELETE 1969


Following the receipt of a DELETE request, the Server may validate if the Client has the 1971 appropriate rights for deleting the identified resource, and whether the identified resource exists. 1972 If the validation is successful, the Server removes the requested resource and deletes all the 1973 associated information. The Server caches the value of ri parameter in the DELETE request for 1974 use in the response. 1975

DELETE response 1976

The Server shall transmit a DELETE response message in response to a DELETE request 1977 message from a Client. The DELETE response message will include the following parameters. 1978



• ri: Identifier included in the DELETE request 1981

• rs: The result of the DELETE operation 1982

8.6 NOTIFY 1983

The NOTIFY operation is used to request asynchronous notification of state changes. Complete 1984 description of the NOTIFY operation is provided in section 11.4. The NOTIFY operation uses the 1985 NOTIFICATION response message which is defined here. 1986

8.6.1.1 NOTIFICATION response 1987

The NOTIFICATION response message is sent by a Server to notify the URLs identified by the 1988 Client of a state change. The NOTIFICATION response message carries the following parameters. 1989


• to: URI of the Resource target of the NOTIFICATION message 1991

• ri: Identifier included in the CREATE request 1992

• op: NOTIFY 1993


• cn: The updated state of the resource 1994

9 Network and connectivity 1995


The Internet of Things is comprised of a wide range of applications which sense and actuate the 1997 physical world with a broad spectrum of device and network capabilities: from battery powered 1998 nodes transmitting 100 bytes per day and able to last 10 years on a coin cell battery, to mains 1999 powered nodes able to maintain MBit video streams. It is estimated that many 10s of billions of 2000 IoT devices will be deployed over the coming years. 2001

It is desirable that the connectivity options be adapted to the IP layer. To that end, IETF has 2002 completed considerable work to adapt Bluetooth®, Wi-Fi, 802.15.4, LPWAN, etc. to IPv6. These 2003 adaptations, plus the larger address space and improved address management capabilities, make 2004 IPv6 the clear choice for the OCF network layer technology. 2005

9.2 Architecture 2006

While the aging IPv4 centric network has evolved to support complex topologies, its deployment 2007 was primarily provisioned by a single Internet Service Provider (ISP) as a single network. More 2008 complex network topologies, often seen in residential home, are mostly introduced through the 2009 acquisition of additional home network devices, which rely on technologies like private Network 2010 Address Translation (NAT). These technologies require expert assistance to set up correctly and 2011 should be avoided in a home network as they most often result in breakage of constructs like 2012 routing, naming and discovery services. 2013

The multi-segment ecosystem OCF addresses will not only cause a proliferation of new devices 2014 and associated routers, but also new services introducing additional edge routers. All these new 2015 requirements require advance architectural constructs to address complex network topologies like 2016 the one shown in Figure 13. 2017


2018

Figure 13. High Level Network & Connectivity Architecture 2019

In terms of IETF RFC 6434, IPv6 nodes assume either a router or host role. Nodes may further 2020 implement various specializations of those roles: 2021

• A Router may implement Customer Edge Router capabilities as defined in IETF RFC 7084. 2022

• Nodes limited in processing power, memory, non-volatile storage or transmission capacity 2023 requires special IP adaptation layers (6LoWPAN) and/or dedicated routing protocols (RPL). 2024 Examples include devices transmitting over low power physical layer like IEEE 802.14.5, ITU 2025 G9959, Bluetooth Low Energy, DECT Ultra Low Energy, Near Field Communication (NFC). 2026

• A node may translate and route messaging between IPv6 and non-IPv6 networks. 2027

9.3 IPv6 network layer requirements 2028

Introduction 2029

Projections indicate that many 10s of billions of new IoT endpoints and related services will be 2030 brought online in the next few years. These endpoint’s capabilities will span from battery powered 2031 nodes with limited compute, storage, and bandwidth to more richly resourced devices operating 2032 over Ethernet and WiFi links. 2033

Internet Protocol version 4 (IPv4), deployed some 30 years ago, has matured to support a wide 2034 variety of applications such as Web browsing, email, voice, video, and critical system monitoring 2035 and control. However, the capabilities of IPv4 are at the point of exhaustion, not the least of which 2036 is that available address space has been consumed. 2037

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 2038 recommends IPv6 at the network layer. Amongst the reasons for IPv6 recommendations are: 2039

• Larger address space. Side-effect: greatly reduce the need for NATs. 2040

• More flexible addressing architecture. Multiple addresses and types per interface: Link-local, 2041 ULA, GUA, variously scoped Multicast addresses, etc. Better ability to support multi-homed 2042 networks, better re-numbering capability, etc. 2043

• More capable auto configuration capabilities: DHCPv6, SLAAC, Router Discovery, etc. 2044

• Technologies enabling IP connectivity on constrained nodes are based upon IPv6. 2045

• All major consumer operating systems (IoS, Android, Windows, Linux) are already IPv6 enabled. 2046

• Major Service Providers around the globe are deploying IPv6. 2047

IPv6 node requirements 2048


In order to ensure network layer services interoperability from node to node, mandating a common 2050 network layer across all nodes is vital. The protocol should enable the network to be: secure, 2051 manageable, scalable and to include constrained and self-organizing meshed nodes. OCF 2052 mandates IPv6 as the common network layer protocol to ensure interoperability across all Devices. 2053 More capable devices may also include additional protocols creating multiple-stack devices. The 2054 remainder of this section will focus on interoperability requirements for IPv6 hosts, IPv6 2055 constrained hosts and IPv6 routers. The various protocol translation permutations included in 2056 multi-stack gateway devices may be addresses in subsequent addendums of this specification. 2057

9.3.2.2 IP Layer 2058

An IPv6 node shall support IPv6 and it shall conform to the requirements as specified in 2059 IETF RFC 6434. 2060

2061

10 Endpoint 2062

10.1 Endpoint definition 2063

The specific definition of an Endpoint depends on the Transport Protocol Suite being used. For the 2064 example of CoAP over UDP over IPv6, the endpoint is identified by an IPv6 address and UDP port 2065 number. 2066

Each OCF Device shall associate with at least one Endpoint with which it can exchange request 2067 and response messages. When a message is sent to an Endpoint, it shall be delivered to the OCF 2068 Device which is associated with the Endpoint. When a request message is delivered to an Endpoint, 2069 path component is enough to locate the target Resource. 2070

OCF Device can be associated with multiple Endpoints. For example, an OCF Device can have 2071 several IP addresses or port numbers or support both CoAP and HTTP transfer protocol. 2072

On the other hand, an Endpoint can be shared among multiple OCF Devices, only when there is a 2073 way to clearly designate the target Resource with request URI. For example, when multiple CoAP 2074 servers use uniquely different URI paths for all their hosted Resources, and the CoAP 2075 implementation demuxes by path, they can share the same CoAP Endpoint. However, this is not 2076 possible for OIC 1.1 and OCF 1.0 because pre-determined URI (e.g. “/oic/d”) is mandatory for 2077 some mandatory Resources (e.g. "oic.wk.d"). 2078


10.2 Endpoint information 2079

Introduction 2080

Endpoint is represented by Endpoint information which consists of two items of key-value pair, 2081 "ep" and "pri". 2082

“ep” 2083

"ep" represents Transport Protocol Suite and Endpoint Locator specified as follows: 2084

• Transport Protocol Suite - a combination of protocols (e.g. CoAP + UDP + IPv6) with which 2085 request and response messages can be exchanged for RESTful transaction (i.e. CRUDN). 2086 Transport Protocol Suites shall be indicated by IANA registered schemes (e.g. "coap" or 2087 "coaps" in Table 12). Vendor or OCF defined schemes are also allowed (e.g. "org.ocf.foo" or 2088 "com.samsung.bar"). 2089

• Endpoint Locator – an address (e.g. IPv6 address + Port number) through which a message 2090 can be sent to the Endpoint and in turn associated OCF Device. The Endpoint Locator for 2091 "coap", "coaps", "coap+tcp", "coaps+tcp", "http", and "https" shall be specified as "IP address: 2092 port number". Temporary addresses should not be used because Endpoint Locators are for the 2093 purpose of accepting incoming sessions, whereas temporary addresses are for initiating 2094 outgoing sessions (IETF RFC 4941). Moreover its inclusion in “/oic/res” can cause a privacy 2095 concern (IETF RFC 7721). 2096

"ep" shall have as its value a URI (as specified in IETF RFC 3986) with the scheme component 2097 indicating Transport Protocol Suite and the authority component indicating the Endpoint Locator: 2098

"ep": "coap://[fe80::b1d6]:1111"

2099

The current list of "ep" with corresponding Transport Protocol Suite is shown in Table 12: 2100

Table 12. “ep” value for Transport Protocol Suite 2101

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” 2102

When there are multiple Endpoints, "pri" indicates the priority among them. 2103

"pri" shall be represented as a positive integer (e.g. "pri": 1) and the lower the value, the higher 2104 the priority. 2105

The default "pri" value is 1, i.e. when "pri" is not present, it shall be equivalent to "pri": 1. 2106


Endpoint information in "eps" Parameter 2107

To carry Endpoint information, a new Link Parameter "eps" is defined in 7.8.2.1.5. "eps" has an 2108 array of items as its value and each item represents Endpoint information with two key-value pairs, 2109 "ep" and "pri", of which "ep" is mandatory and "pri" is optional. A link with "eps": 2110

{ "anchor": "ocf://light_device_id", "href": "/myLightSwitch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, {"ep": "coaps://[fe80::b1d6]:1122"}] }

2111

In the previous example, "anchor" represents the hosting OCF Device, "href", target Resource and 2112 "eps" the two Endpoints for the target Resource. 2113

If the target Resource of a Link requires a secure connection (e.g. CoAPS), "eps" Parameter shall 2114 be used to indicate the necessary information (e.g. port number) in OCF 1.0 payload, because 2115 "sec" and "port" shall be used only in OIC 1.1 payload. 2116

10.3 Endpoint discovery 2117

Introduction 2118

"Endpoint discovery" is defined as the process for a Client to acquire the Endpoint information for 2119 OCF Device or Resource. 2120

Implicit discovery 2121

If a Device is the source of a CoAP message (e.g. “/oic/res” response), the source IP address and 2122 port number can be combined to form the Endpoint Locator for the Device. Along with a "coap" 2123 scheme and default “pri” value, Endpoint information for the Device can be constructed. 2124

In other words, an “/oic/res” response message with CoAP can implicitly carry the Endpoint 2125 information of the responding Device and in turn all the hosted Resources, which can be accessed 2126 with the same transfer protocol of CoAP. 2127

Explicit discovery with “/oic/res” response 2128

Endpoint information can be explicitly indicated with the "eps" Parameter of the Links in “/oic/res”. 2129

As in 10.3.2, an “/oic/res” response can implicitly indicate the Endpoint information for the target 2130 Resources hosted by the responding Device. However “/oic/res” may expose a target Resource 2131 which belongs to another Device. When the Endpoint for a target Resource of a Link cannot be 2132 implicitly inferred, the "eps" Parameter shall be included to provide explicit Endpoint information 2133 with which a Client can access the target Resource. 2134

This applies to the case of “/oic/res” for a Resource Directory or Bridge Device which usually 2135 carries the Links for Resources which another Device hosts. 2136

An “/oic/res” response with the "eps" Parameter in Links: 2137

[ {


"anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/oic/res", "rel": "self", "rt": ["oic.wk.res"], "if": ["oic.if.ll", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:55555"}, {"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/oic/d", "rt": ["oic.wk.d", "oic.d.bridge"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:55555"}, {"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/oic/p", "rt": ["oic.wk.p"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/mySecureMode", "rt": ["oic.r.securemode"], "if": ["oic.if.rw", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/oic/sec/doxm", "rt": ["oic.r.doxm"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:55555"}, {"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/oic/sec/pstat", "rt": ["oic.r.pstat"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/oic/sec/cred", "rt": ["oic.r.cred"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/oic/sec/acl2", "rt": ["oic.r.acl2"],


"if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/myIntrospection", "rt": ["oic.wk.introspection"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:11111"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/oic/res", "rt": ["oic.wk.res"], "if": ["oic.if.ll", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"}, {"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/oic/d", "rt": ["oic.wk.d", "oic.d.light", "oic.d.virtual"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"}, {"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/oic/p", "rt": ["oic.wk.p"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/myLight", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/oic/sec/doxm", "rt": ["oic.r.doxm"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:66666"}, {"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/oic/sec/pstat", "rt": ["oic.r.pstat"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}]


}, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/oic/sec/cred", "rt": ["oic.r.cred"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/oic/sec/acl2", "rt": ["oic.r.acl2"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", "href": "/myLightIntrospection", "rt": ["oic.wk.introspection"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:22222"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/oic/res", "rt": ["oic.wk.res"], "if": ["oic.if.ll", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, {"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/oic/d", "rt": ["oic.wk.d", "oic.d.fan", "oic.d.virtual"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, {"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/oic/p", "rt": ["oic.wk.p"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/myFan", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/oic/sec/doxm", "rt": ["oic.r.doxm"],


"if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, {"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/oic/sec/pstat", "rt": ["oic.r.pstat"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/oic/sec/cred", "rt": ["oic.r.cred"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/oic/sec/acl2", "rt": ["oic.r.acl2"], "if": ["oic.if.baseline"], "p": {"bm": 1}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] }, { "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", "href": "/myFanIntrospection", "rt": ["oic.wk.introspection"], "if": ["oic.if.r", "oic.if.baseline"], "p": {"bm": 3}, "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] } ]

2138

The exact format of the “/oic/res” response and a way for a Client to acquire a “/oic/res” response 2139 message is specified in D.9 and 11.3.5 respectively. 2140

10.4 CoAP based Endpoint discovery 2141

The following describes CoAP based Endpoint discovery: 2142

a) Advertising or publishing Devices shall join the ‘All OCF Nodes’ multicast groups (as defined 2143 in [IANA IPv6 Multicast Address Space Registry]) with scopes 2, 3, and 5 (i.e., ff02::158, 2144 ff03::158 and ff05::158) and shall listen on the port 5683. For compliance to IETF RFC 7252 a 2145 Device may additionally join the ‘All CoAP Nodes’ multicast groups. 2146

b) Clients intending to discover resources shall join the multicast groups as defined in a). 2147

c) Clients shall send discovery requests (GET request) to the 'All OCF Nodes’ multicast group 2148 address with scope 2 (ff02::158) at port 5683. The requested URI shall be “/oic/res”. For 2149 compliance to IETF RFC 7252 a Client may additionally send to the ‘All CoAP Nodes’ multicast 2150 groups. 2151


d) If the discovery request is intended for a specific Resource Type, the Query parameter "rt" shall 2152 be included in the request (section 6.2.1) with its value set to the desired Resource Type. Only 2153 Devices hosting the Resource Type shall respond to the discovery request. 2154

e) When the “rt” Query parameter is omitted, all Devices shall respond to the discovery request. 2155

f) Handling of multicast requests shall be as described in section 8 of IETF RFC 7252 and section 2156 4.1 in IETF RFC 6690. 2157

g) Devices which receive the request shall respond using CBOR payload encoding. A Device shall 2158 indicate support for CBOR payload encoding for multicast discovery as described in section 2159 12.3.6. Later versions of the specification may support alternate payload encodings (JSON, 2160 XML/EXI, etc.). 2161

Note: Unsecured endpoint is used for multicast discovery. 2162

11 Functional interactions 2163


The functional interactions between a Client and n Server are described in section 11.2 through 2165 section 11.6 respectively. The functional interactions use CRUDN messages (section 8) and 2166 include Discovery, Notification, and Device management. These functions require support of core 2167 defined resources as defined in Table 13. More details about these resources are provided later 2168 in this section. 2169

Table 13. List of Core Resources 2170

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

2171

11.2 Onboarding, Provisioning and Configuration 2172

Onboarding and Provisioning are fully defined by the OCF Security Specification. 2173 2174 Should a Device support Client update of configurable information it shall do so via exposing the 2175 Core Resource “/example/oic/con” (Table 14) in “/oic/res”; 2176

2177

Table 14. Configuration Resource 2178

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. The resource properties exposed in “oic.wk.con” are listed in Table 15.

Configuration


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

2179

Table 15 defines the “oic.wk.con” resource type. 2180 2181

Table 15. “oic.wk.con” Resource Type definition 2182

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.

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.

2183

Table 16 defines the “oic.wk.con.p” resource type. 2184

Table 16. “oic.wk.con.p” Resource Type definition 2185


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

2186

2187

11.3 Resource discovery 2188

Introduction 2189

Discovery is a function which enables endpoint discovery as well as resource based discovery. 2190 Endpoint discovery is described in detail in section 10. This section mainly describes the resource 2191 based discovery. 2192

Resource based discovery: mechanisms 2193

11.3.2.1 Overview 2194

As part of discovery, a Client may find appropriate information about other OCF peers. This 2195 information could be instances of Resources, Resource Types or any other information 2196 represented in the resource model that an OCF peer would want another OCF peer to discover. 2197

At the minimum, Resource based discovery uses the following: 2198

1) A resource to enable discovery shall be defined. The representation of that resource shall 2199 contain the information that can be discovered. 2200

2) The resource to enable discovery shall be specified and commonly known a-priori.A Device for 2201 hosting the resource to enable discovery shall be identified. 2202


3) A mechanism and process to publish the information that needs to be discovered with the 2203 resource to enable discovery. 2204

4) A mechanism and process to access and obtain the information from the resource to enable 2205 discovery. A query may be used in the request to limit the returned information. 2206

5) A scope for the publication 2207

6) A scope for the access. 2208

7) A policy for visibility of the information. 2209

2210

Depending on the choice of the base aspects defined above, the Framework defines three resource 2211 based discovery mechanisms: 2212

• Direct discovery, where the Resources are published locally at the Device hosting the 2213 resources and are discovered through peer inquiry. 2214

• Indirect discovery, where Resources are published at a third party assisting with the 2215 discovery and peers publish and perform discovery against the resource to enable 2216 discovery on the assisting 3rd party. 2217

• Advertisement discovery, where the resource to enable discovery is hosted local to the 2218 initiator of the discovery inquiry but remote to the Devices that are publishing discovery 2219 information. 2220

A Device shall support direct discovery. 2221

11.3.2.2 Direct discovery 2222

In direct discovery, 2223 1) The Device that is providing the information shall host the resource to enable discovery. 2224 2) The Device publishes the information available for discovery with the local resource to 2225

enable discovery (i.e. local scope). 2226 3) Clients interested in discovering information about this Device shall issue RETRIEVE 2227

requests directly to the resource. The request may be made as a unicast or multicast. 2228 The request may be generic or may be qualified or limited by using appropriate queries in 2229 the request. 2230

4) The “server” Device that receives the request shall send a response with the discovered 2231 information directly back to the requesting “client” Device. 2232

5) The information that is included in the request is determined by the policies set for the 2233 resource to be discovered locally on the responding Device. 2234

2235

11.3.2.3 Indirect discovery of Resources (resource directory based discovery) 2236

In indirect discovery the information about the resource to be discovered is hosted on a Server 2237 that is not hosting the resource. See section 11.3.6 for details on resource directory based 2238 discovery. 2239

In indirect discovery: 2240

a) The resource to be discovered is hosted on a Device that is neither the client initiating 2241 the discovery nor the Device that is providing or publishing the information to be 2242 discovered. This Device may use the same resource to provide discovery for multiple 2243 agents looking to discover and for multiple agents with information to be discovered. 2244

b) The Device to be discovered or with information to discover, publishes that information 2245 with resource to be discovered on a different Device. The policies on the information 2246


shared including the lifetime/validity are specified by the publishing Device. The 2247 publishing Device may modify these policies as required. 2248

c) The client doing the discovery may send a unicast discovery request to the Device 2249 hosting the discovery information or send a multicast request that shall be monitored and 2250 responded to by the Device. In both cases, the Device hosting the discovery information 2251 is acting on behalf of the publishing Device. 2252

d) The discovery policies may be set by the Device hosting the discovery information or by 2253 the party that is publishing the information to be discovered. The discovery information 2254 that is returned in the discovery response shall adhere to the policies that are in effect at 2255 the time of the request. 2256

2257

11.3.2.4 Advertisement Discovery 2258

In advertisement discovery: 2259

a) The resource to enable discovery is hosted local to the Device that is initiating the discovery 2260 request (client). The resource to enable discovery may be a Core Resource or discovered 2261 as part of a bootstrap. 2262

b) The request could be an implementation dependent lookup or be a local RETRIEVE request 2263 against the resource that enables discovery. 2264

c) The Device with information to be discovered shall publish the appropriate information to 2265 the resource that enables discovery. 2266

d) The publishing Device is responsible for the published information. The publishing Device 2267 may UPDATE the information at the resource to enable discovery based on its needs by 2268 sending additional publication requests. The policies on the information that is discovered 2269 including lifetime is determined by the publishing Device. 2270

2271

Resource based discovery: Information publication process 2272

The mechanism to publish information with the resource to enable discovery can be done either 2273 locally or remotely. The publication process is depicted in Figure 14. The Device which has 2274 discovery information to publish shall a) either update the resource that enables discovery if 2275 hosted locally or b) issue an UPDATE request with the information to the Device which hosts the 2276 resource that enables discovery. The Device hosting the resource to enable discovery 2277 adds/updates the resource to enable discovery with the provided information and then responds 2278 to the Device which has requested the publication of the resource with an UPDATE response. 2279

2280

2281


2282

Figure 14. Resource based discovery: Information publication process 2283

Resource based discovery: Finding information 2284

The discovery process (Figure 15) is initiated as a RETRIEVE request to the resource to enable 2285 discovery. The request may be sent to a single Device (as in a Unicast) or to multiple Devices (as 2286 in Multicast). The specific mechanisms used to do Unicast or Multicast are determined by the 2287 support in the data connectivity layer. The response to the request has the information to be 2288 discovered based on the policies for that information. The policies can determine which information 2289 is shared, when and to which requesting agent. The information that can be discovered can be 2290 resources, types, configuration and many other standards or custom aspects depending on the 2291 request to appropriate resource and the form of request. Optionally the requester may narrow the 2292 information to be returned in the request using query parameters in the URI query. 2293

2294

2295

Figure 15. Resource based discovery: Finding information 2296

2297

Discovery Resources 2298

Some of the Core Resources shall be implemented on all Devices to support discovery. The Core 2299 Resources that shall be implemented to support discovery are: 2300

“/oic/res” for discovery of resources 2301

“/oic/p” for discovery of platform 2302

“/oic/d” for discovery of device information 2303

Details for these mandatory Core Resources are described in Table 17 2304


Platform resource – 2305 The OCF recognizes that more than one instance of Device may be hosted on a single platform. 2306 Clients need a way to discover and access the information on the platform. The core resource, 2307 “/oic/p” exposes platform specific properties. All instances of Device on the same Platform shall 2308 have the same values of any properties exposed (i.e. a Device may choose to expose optional 2309 properties within “/oic/p” but when exposed the value of that property should be the same as the 2310 value of that property on all other Devices on that Platform) 2311 2312 Device resource 2313 The device resource shall have the pre-defined URI “/oic/d”. The resource “/oic/d” exposes the 2314 properties pertaining to a Device as defined in Table 17. The properties exposed are determined 2315 by the specific instance of Device and defined by the Resource Type(s) of “/oic/d” on that Device. 2316 Since all the Resource Types of “/oic/d” are not known a priori, the Resource Type(s) of “/oic/d” 2317 shall be determined by discovery through the core resource “/oic/res”. The device resource “/oic/d” 2318 shall have a default Resource Type that helps in bootstrapping the interactions with this device 2319 (the default type is described in Table 17.) 2320 2321 Protocol indication 2322 A Device may need to support different messaging protocols depending on requirements for 2323 different application profiles. For example, the Smart Home profile may use CoAP and the 2324 Industrial profile may use DDS. To enable interoperability, a Device uses the protocol indication 2325 to indicate the transport protocols they support and can communicate over. 2326

2327

Table 17. Mandatory discovery Core Resources 2328

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

Discovery


conditioner, smoke alarm); applicable values are defined by the vertical specifications.

2329

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

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


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 ‘mpro’ 2332 in response to a request on “/oic/res”. A Device shall support CoAP based discovery as the 2333 baseline discovery mechanism (see section 10.4). A Client which sees this property in a discovery 2334 response can choose any of the supported messaging protocols for communicating with the Server 2335 for further messages. For example, if a Device supporting multiple protocols indicates it supports 2336 a value of “1 3” for the ‘mpro’ property in the discovery response, then it cannot be assumed that 2337 there is an implied ordering or priority. But a vertical service specification may choose to specify 2338 an implied ordering or priority. If the ‘mpro’ property is not present in the response, A Client shall 2339 use the default messaging protocol as specified in the vertical specification for further 2340 communication. 2341

The “/oic/res” shall list all Resources that are indicated as discoverable (see section 11.3). Also 2342 the following architecture Resource Types shall be listed: 2343

• Introspection resource indicated with an “rt” value of “oic.wk.introspection” 2344

• “/oic/p” indicated with an “rt” value of “oic.wk.p” 2345

• “/oic/d” indicated with an “rt” value of “oic.wk.d” 2346

• “/oic/sec/doxm” indicated with an “rt” value of “oic.r.doxm” as defined in the OCF Security 2347 Specification 2348

• “/oic/sec/pstat” indicated with an “rt” value of “oic.r.pstat” as defined in the OCF Security 2349 Specification 2350

• “/oic/sec/acl2” indicated with an “rt” value of “oic.r.acl2” as defined in the OCF Security 2351 Specification 2352

• “/oic/sec/cred” indicated with an “rt” value of “oic.r.cred” as defined in the OCF Security 2353 Specification 2354

Conditionally required: 2355

• “/oic/res” with an "rt" value of "oic.wk.res" as self-reference, on the condition that “oic/res” has 2356 to signal that it is observable by a Client. 2357


The Introspection Resource is only applicable for Devices that host Vertical Resource Types (e.g. 2358 “oic.r.switch.binary”) or vendor-defined Resource Types. Devices that only host Resources 2359 required to onboard the Device as a Client do not have to implement the Introspection Resource. 2360

Table 19 provides an OCF registry for protocol schemes. 2361

Table 19. Protocol scheme registry 2362

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 2363 requests in a different messaging protocol other than discovery is out of scope. 2364

2365

The following applies to the use of "/oic/d" as defined above: 2366

• A Device may choose to expose its Device Type (e.g., refrigerator or A/C) by adding the Device 2367 Type to the list of Resource Types associated with "/oic/d". 2368

o For example; "rt" of "/oic/d" becomes ["oic.wk.d", "oic.d.<thing>"]; where 2369 "oic.d.<thing>" is defined in another spec such as the Smart Home vertical. 2370

o This implies that the properties exposed by "/oic/d" are by default the mandatory 2371 properties in Table 20. 2372

• A vertical may choose to extend the list of properties defined by the Resource Type "oic.wk.d". 2373 In that case, the vertical shall assign a new Device Type specific Resource Type ID. The 2374 mandatory properties defined in Table 20 shall always be present. 2375

• A Device may choose to expose a separate, discoverable Resource with its Resource Type ID 2376 set to an OCF defined Device Type. In this case the Resource is equivalent to an instance of 2377 "oic.wk.d" and adheres to the definition thereof. As such the Resource shall at a minimum 2378 expose the mandatory Resource Properties of “oic.wk.d”. In the case where the Resource 2379 tagged in this manner is defined to be an instance of a Collection (i.e. it also includes the "rt" 2380 value of "oic.wk.col") then the Resources that are part of that Collection shall at a minimum 2381 include the Resource Types mandated for the Device Type. For example, if a Resource has an 2382 "rt" value of ["oic.d.light", "oic.wk.col"], that Resource follows the definitions of both "oic.wk.d" 2383 and "oic.wk.col". In this example, the collection includes an instance of "oic.r.switch.binary" 2384 which is mandatory for an "oic.d.light" as per the OCF Smart Home Device specification. 2385

Table 20 "oic.wk.d" Resource Type definition defines the base Resource Type for the "/oic/d" 2386 resource. 2387 2388

Table 20. "oic.wk.d" Resource Type definition 2389


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. One entry in the csv string shall be the applicable version of the Resource Type Specification for the Device (e.g “ocf.res.1.0.0”). If applicable, additional entry(-ies) in the csv shall be the vertical(s) being realized (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.

2390

The additional Resource Type(s) of the "/oic/d" resource are defined by the vertical specification. 2391

2392

Table 21 defines "oic.wk.p" Resource Type. 2393 2394

Table 21. "oic.wk.p" Resource Type definition 2395


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.

2396

Composite Device 2397

A physical device may be modelled as a single device or as a composition of other devices. For 2398 example a refrigerator may be modelled as a composition, as such part of its definition of may 2399 include a sub-tending thermostat device which itself may be composed of a sub-tending 2400 thermometer device. 2401

There may be more than one way to model a server as a composition. One example method would 2402 be to have Platform which represents the composite device to have more than one instance of a 2403 Device on the Platform. Each Device instance represents one of the distinct devices in the 2404 composition. Each instance of Device may itself have or host multiple instances of other resources. 2405

An implementation irrespective of how it is composed shall only expose a single instance of “/oic/d” 2406 with an ‘rt’ of choice for each logical Server. 2407

Thus, for the above refrigerator example if modeled as a single Server; “/oic/res” would expose 2408 “/oic/d” with a Resource Type name appropriate to a refrigerator. The sub-tending thermostat and 2409 thermometer devices would be exposed simply as instances of a resource with a device 2410 appropriate Resource Type with an associated URI assigned by the implementation; e.g., 2411 /MyHost/MyRefrigerator/Thermostat and /MyHost/MyRefrigerator/Thermostat/Thermometer. 2412

2413

Resource discovery using “/oic/res” 2414

Discovery using “/oic/res” is the default discovery mechanism that shall be supported by all Devices 2415 as follows: 2416


a) Every Device updates its local “/oic/res” with the resources that are discoverable (see section 2417 7.3.2.2). Every time a new resource is instantiated on the Device and if that resource is 2418 discoverable by a remote Device then that resource is published with the “/oic/res” resource 2419 that is local to the Device (as the instantiated resource). 2420

b) A Device wanting to discover resources or Resource Types on one or more remote Devices 2421 makes a RETRIEVE request to the “/oic/res” on the remote Devices. This request may be sent 2422 multicast (default) or unicast if only a specific host is to be probed. The RETRIEVE request 2423 may optionally be restricted using appropriate clauses in the query portion of the request. 2424 Queries may select based on Resource Types, interfaces, or properties. 2425

c) The query applies to the representation of the resources. “/oic/res” is the only resource whose 2426 representation has “rt”. So “/oic/res” is the only resource that can be used for Multicast 2427 discovery at the transport protocol layer. 2428

d) The Device receiving the RETRIEVE request responds with a list of resources, the Resource 2429 Type of each of the resources and the interfaces that each resource supports. Additionally, 2430 information on the policies active on the resource can also be sent. The policy supported 2431 includes observability and discoverability. (More details below) 2432

e) The receiving Device may do a deeper discovery based on the resources returned in the 2433 request to “/oic/res”. 2434

2435

The information that is returned on discovery against “/oic/res” is at the minimum: 2436

• The URI (relative or fully qualified URL) of the resource 2437

• The Resource Type(s) of each resource. More than one Resource Type may be returned if the 2438 resource enables more than one type. To access resources of multiple types, the specific 2439 Resource Type that is targeted shall be specified in the request. 2440

• The Interfaces supported by that Resource. Multiple interfaces may be returned. To access a 2441 specific interface that interface shall be specified in the request. If the interface is not specified, 2442 then the Default Interface is assumed. 2443

Different "/oic/res" responses are returned according to requesting Clients, which indicate their 2444 preference via inclusion or otherwise of an OCF-Accept-Content–Format-Version option. 2445

For Clients that do not include the OCF-Accept-Content-Format-Version option, an "/oic/res" 2446 response shall use "sec" and "port" to provide the information for an encrypted connection. See 2447 E.2.8 for the schema for the Link. 2448

For Clients that do include the OCF-Accept-Content-Format-Version option, an "/oic/res" response 2449 includes an “array of Links” to conform to IETF RFC 6690. Each Link shall use an "eps" Parameter 2450 to provide the information for an encrypted connection and carry "anchor" of the value OCF URI 2451 where the authority component of <deviceID> indicates the Device hosting the target Resource. 2452

The JSON schema for discovery using “/oic/res” is described in D.9; the schema that is applicable 2453 to requesting Clients that do not include an OCF-Accept-Content-Format-Version option is 2454 described in E.4 and E.5. Also refer to section 10 (Endpoint Discovery) for details of Multicast 2455 discovery using “/oic/res” on a CoAP transport. 2456

For example, a Light device might return the following to OIC 1.1 clients: 2457

[ 2458 { 2459 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 2460 "links": [ 2461 { 2462 "href": "coaps://[fe80::b1d6]:44444/oic/res", 2463


"rel": "self", 2464 "rt": ["oic.wk.res"], 2465 "if": ["oic.if.ll", "oic.if.baseline"], 2466 "p": {"bm": 3} 2467 }, 2468 { 2469 "href": "/oic/p", 2470 "rt": ["oic.wk.p"], 2471 "if": ["oic.if.r", "oic.if.baseline"], 2472 "p": {"bm": 3, "sec": true, "port": 11111} 2473 }, 2474 { 2475 "href": "/oic/d", 2476 "rt": ["oic.wk.d", "oic.d.light"], 2477 "if": ["oic.if.r", "oic.if.baseline"], 2478 "p": {"bm": 3, "sec": true, "port": 11111} 2479 }, 2480 { 2481 "href": "/myLight", 2482 "rt": ["oic.r.switch.binary"], 2483 "if": ["oic.if.a", "oic.if.baseline"], 2484 "p": {"bm": 3, "sec": true, "port": 11111} 2485 } 2486 ] 2487 } 2488 ] 2489

The light device might return the following to clients that request with the Content Format of 2490 “application/vnd.ocf+cbor” in Accept Option: 2491

[ 2492 { 2493 "href": "/oic/res", 2494 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989/oic/res", 2495 "rel": "self", 2496 "rt": ["oic.wk.res"], 2497 "if": ["oic.if.ll", "oic.if.baseline"], 2498 "p": {"bm": 3}, 2499 "eps": [{"ep": "coap://[fe80::b1d6]:44444"}] 2500 }, 2501 { 2502 "href": "/oic/p", 2503 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989, 2504 "rt": ["oic.wk.p"], 2505 "if": ["oic.if.r", "oic.if.baseline"], 2506 "p": {"bm": 3}, 2507 "eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2508 {"ep": "coaps://[fe80::b1d6]:11111"} 2509 ] 2510 }, 2511 { 2512 "href": "/oic/d", 2513 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989, 2514 "rt": ["oic.wk.d", "oic.d.light"], 2515 "if": ["oic.if.r", "oic.if.baseline"], 2516 "p": {"bm": 3}, 2517 "eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2518 {"ep": "coaps://[fe80::b1d6]:11111"} 2519 ] 2520 }, 2521 { 2522 "href": "/myLight", 2523


"anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989, 2524 "rt": ["oic.r.switch.binary"], 2525 "if": ["oic.if.a", "oic.if.baseline"], 2526 "p": {"bm": 3}, 2527 "eps": [{"ep": "coap://[fe80::b1d6]:44444"}, 2528 {"ep": "coaps://[fe80::b1d6]:11111"} 2529 ] 2530 } 2531 ] 2532

After performing discovery using “/oic/res”, Clients may discover additional details about Server 2533 by performing discovery using “/oic/p”, /oic/rts etc. If a Client already knows about Server it may 2534 discover using other resources without going through the discovery of “/oic/res”. 2535

Resource directory (RD) based discovery 2536


11.3.6.1.1 Indirect discovery for lookup of the Resources 2538

Direct discovery is the mechanism used currently to find Resources in the network. When needed, 2539 Resources are queried at a particular Device directly or a multicast packet is sent to all Devices. 2540 Each queried Device responds directly with its Resources to the discovering Device. Resources 2541 available locally are registered on the same Device. 2542

In some situations, one of the other mechanisms described in section 11.3.2.3, called indirect 2543 discovery, may be required. Indirect discovery is when a 3rd party Device, other than the 2544 discovering Device and the discovered Device, assists with the discovery process. The 3rd party 2545 Device, called Resource Directory (RD), only provides information on Resources on behalf of 2546 another Device but does not host Resources on part of that Device. 2547

2548

Figure 16. Indirect discovery of Resources by via an RD 2549

In Figure 16, Device B acts as Resource Directory for Device A and Device D. Device A and Device 2550 D publish their Resource information to Device B. Device C may query Deice B to acquire the 2551 Resource information of Device A and Device D. Device A and Device D may not respond to a 2552 multicast query when Device B, as a Resource Directory, responds to the query on their behalf. 2553

OCF Device A

OCF Device B

OCF Device C

/oic/res

/oic/res

OCF Device D

/oic/res Multicast

Multicast Discovery

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)


Indirect discovery is useful for a constrained Device that needs to sleep to manage power and 2554 cannot process every discovery request, or when Devices may not be on the same network and 2555 requires optimization for discovery. Once Resources are discovered using indirect discovery, i.e., 2556 RD query, then the access to the Resource is done by a request sent directly to the Device that 2557 hosts that Resource. 2558

11.3.6.1.2 Resource directory 2559

A Resource Directory (RD) is a Device that assists with indirect discovery. A Device which acts as 2560 an RD will be involved in the following operations. 2561

• RD discovery – the procedure with which publishing Devices discover an RD and acquire the 2562 criteria to select from among multiple detected RDs. 2563

• Resource publish – the procedures with which Devices publish their Resource information, 2564 i.e. Links, subsequently update the published Links or delete the existing ones. 2565

• Resource exposure – the feature with which RDs expose the Links hosted by the 3rd party 2566 Devices via their own "/oic/res". 2567

For the above, RDs make use of Resource Type "oic.wk.rd" defined in Table 22 and Table 23. A 2568 Device that supports the capability to host indirect discovery shall expose an instance of "oic.wk.rd" 2569 in its "/oic/res" to announce that it serves as an RD. The discoverable instance of "oic.wk.rd" shall 2570 allow only secure connections (e.g. endpoint with a scheme of "coaps" or "coaps+tcp"). A 2571 publishing Device may send a RETRIEVE request to "/oic/rd" to acquire the selection criteria 2572 among multiple RDs. Then it may may send an UPDATE request to "/oic/rd" with its Links in the 2573 payload to publish or change the Links in "/oic/res" of the RD. Also the publishing Device may send 2574 a DELETE request to "/oic/rd" to remove the existing Links from "/oic/res" of the RD.A publishing 2575 Device is responsible to insure an RD has the correct published Links to expose via its "/oic/res". 2576 The publishing Device needs to keep the RD updated with any changes (e.g., a new IP address) 2577 and remove the Links with stale information, which it accomplishes with suitable UPDATE or 2578 DELETE request. 2579

Table 22. "oic.wk.rd" Resource Type definition 2580

Pre-defined URI

Resource Type Title



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

Discovery

2581

Table 23. "oic.wk.rd" Properties 2582

Property title Property name Value type

Value rule

Unit Access mode


Selector sel Integer R yes Provides the criteria for RD selection. An integer representing a value calculated by the RD. The value is in the range of 0 to 100. The lower the value, the more preferable the RD is.

2583


An RD may be queried at its "/oic/res" Resource to find Resources hosted on other Devices. These 2584 Devices can be sleepy nodes or any other device that cannot or may not respond to discovery 2585 requests. A publishing Device may publish all or a partial list of Resources they host to an RD. 2586 The RD then responds to queries for Resource discovery on behalf of the publishing Device (for 2587 example: when a Device may go to sleep). For general Resource discovery, the RD behaves like 2588 any other Server in responding to requests to "/oic/res". 2589

The remainder of section 11.3.6 is divided into three parts. The first part covers "RD Discovery" 2590 (section 11.3.6.2), i.e., discovering and selecting of an RD. The second part covers "Resource 2591 publish" (section 11.3.6.3), i.e., publishing, updating and deleting of Resources. The third part 2592 covers "Resource exposure" (section 11.3.6.4) where the RD replies to queries from Devices 2593 looking to discover Resources. 2594

11.3.6.2 RD discovery 2595

11.3.6.2.1 Discovering an RD 2596

An RD shall support RD discovery. 2597

2598

Figure 17. RD discovery and RD supported query of Resources support 2599

As shown in Figure 17, a Device that wishes to publish its Resources first discovers an RD and 2600 then publishes the desired Resource information. Once a set of Resources have been published 2601 to an RD then the publishing Device should not respond to multicast Resource discovery queries 2602 for those published Resources when the RD is on the same multicast domain. In that case, only 2603 the RD should respond to multicast Resource discovery requests on the Resource published to it. 2604

It is allowed for more than one Device to act as an RD. The reason to have multiple RD support is 2605 to make networks scalable, handle network failures and prevent centralized Device failure 2606 bottlenecks. This does not preclude a scenario where a use case or deployment environment may 2607 require a single Device in the environment to be deployed as the only RD (e.g. gateway model). 2608


Discovering an RD may result in responses from more than one RD. If more than one RD responds, 2609 the discovering Device may select on of them based on the weighting parameter(s) provided in the 2610 response from the RD. 2611

A Client that performs Resource discovery uses an RD just like it uses any other Server for 2612 discovery. It may send a unicast request to the RD when it needs only the Resources published 2613 on the RD or do a multicast query when it does not require or have explicit knowledge of an RD. 2614

2615

Figure 18. Resource Direction Deployment Scenarios 2616

RDs may also be discovered in the following ways: 2617

• Pre-configuration: Devices wishing to publish Resource information may be configured a priori 2618 with the information (e.g. IP address, port, transport etc.) of a specific RD. This pre-2619 configuration may be done at onboarding or may be updated on the Device using an out-of-2620 band method. This pre-configuration may be done by the manufacturer. 2621

• Query-oriented: A publishing Device wanting to discover resource directories using query-2622 oriented discovery may issue a multicast Resource discovery request for "/oic/res?rt=oic.wk.rd". 2623 Only and all Devices that can be an RD shall respond to this query. The "/oic/rd" response shall 2624 include information about the RD i.e., the presence of "oic.wk.rd" Link (as defined by the 2625 Resource Type) and a subsequent query to "/oic/rd" would produce weighting parameters to 2626 allow the discovering Device to select between RDs (see details in RD selection section 2627 11.3.6.2.2). The "oic.wk.rd" resource shall be instantiated on the Devices acting as RDs. The 2628 "oic.wk.rd" schema is as defined in D.13. 2629

11.3.6.2.2 RD selection process 2630

The Device that wants to use an RD will find zero or more RDs on the network. There may not be 2631 an RD within the network. When discovering RDs, the Device needs to select an RD of all RDs 2632 found on the network. The Device may send a RETRIEVE request to "/oic/rd" of a specific RD, the 2633 RD shall respond with the representation of "/oic/rd/" containing selection criteria as defined by 2634 the "sel" Property. The lower the "sel" Property value is, the more preferable the responding RD 2635 is. The creation of the "sel" value is vendor defined. 2636

For example an "/oic/rd" response may return the following. 2637

Platform

Device

/oic/res /oic/rd

Platform

Device A

/oic/res

Device B

/oic/res /oic/rd

Device serving as Resource Directory

Platform with dedicated Resource Directory


2638

2639

2640

2641

The selection based on the "sel" Property value will ensure that a Device can judge if the found 2642 RD is suitable for its needs. 2643

The following situations may occur during the selection of an RD: 2644

1) A single or multiple RDs are present in the network 2645

2) No RD is present in the network 2646

3) an additional RD arrives on the network 2647

In the first scenario, the RDs are already present. If a single RD is detected then that RD may be 2648 used. When multiple RDs are detected the Device may use the "sel" Property value to select the 2649 RD. 2650

In the second scenario, the publishing Device may continue looking for an RD until one is found 2651 or give up using an RD altogether. 2652

In the third scenario, the Device has already published its resources to an existing RD, then 2653 discovers a new RD on the network. After judging the "sel" Property value, the Device may choose 2654 to move to the new RD. The Device should delete its Resource information from the currently used 2655 RD and publish the information to the new RD. 2656

11.3.6.3 Resource publish 2657

11.3.6.3.1 Overview 2658

An RD shall provide the facility to allow Devices to publish their Resource information to a RD, to 2659 update Resource information in an RD and to delete Resource information from an RD. The 2660 following sections describe the requirements for each. 2661

11.3.6.3.2 Publish resources 2662

11.3.6.3.2.1 Overview 2663

After the selection process of an RD, a device may push its Resource information to the selected 2664 RD, i.e., publish the Links in its "/oic/res" to the "/oic/res" of the RD. 2665

The publishing Device may decide to publish all Resources or just a few of the Resources on the 2666 RD. The publishing Device should only publish Resources that are otherwise published to its own 2667 "/oic/res"; a publishing Device should not publish non-discoverable Resources or Resources 2668 hosted by some other Device. A publishing Device shall respond to discovery requests on its 2669 "/oic/res" resource unless all its discoverable Resources have been published in an RD. 2670

11.3.6.3.2.2 Publish: Push Resource information 2671

Resource information may be published using an UPDATE request sent to "/oic/rd". 2672

A Device which hosts a Resource may publish the Resource information, i.e. the Link targeting the 2673 Resource, to an RD by sending an UPDATE request with the Link in the payload. The published 2674 Link shall be exposed through the "/oic/res" of the RD. 2675

{ "rt": ["oic.wk.rd"], "if": ["oic.if.baseline"], "sel": 50 }


When a Device first publishes a Link or Links, it shall send an UPDATE request to the "/oic/rd" 2676 Resource of the RD including the following key-value pairs in the payload: 2677

• di –its value shall be the Device ID of the publishing Device, i.e. the "di" value of "/oci/d". 2678

• links –its value shall be the array of Links to be published. Links may omit the "ins" parameter 2679 in which case the RD will assign a value for each Link. The supplied "ins" parameter by the 2680 Client is allowed to be overruled by the RD, e.g. an RD can ignore the supplied "ins" value. 2681

• ttl –its value indicates how long (in seconds) the publishing Device requests the RD to keep 2682 this published Link. 2683

Take notice that the payload shall carry the appropriate Content-Format of 2684 "application/vnd.ocf+cbor": 2685

{ "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "links": [ { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/myLightSwitch",

"rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm": 3}, "eps": [ {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, {"ep": "coaps://[fe80::b1d6]:1122"}, {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} ] }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/myLightBrightness", "rt": ["oic.r.brightness"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm": 3}, "eps": [ {"ep": "coaps://[[2001:db8:a::123]:2222"} ] } ], "ttl": 600 }

2686

When an RD receives this initial UPDATE request, it determines whether to grant the request or 2687 not. Upon granting the request, the RD shall send back an UPDATE response to the publishing 2688


Device. The response shall include a payload with the same information as the original UPDATE 2689 request with the following possible differences: 2690

• For each Link, an "ins" Parameter shall be included in the response. The RD shall assign a 2691 unique "ins" value identifying the Link among all the Links it advertises. If the publishing Device 2692 included an "ins" value in the UPDATE request, the RD may use it as long as it doesn't match 2693 any existing "ins" value in the published Links. The "ins" value needs to be retained to modify 2694 the newly published Link. The publishing Device may use the “ins” value for further UPDATE 2695 or DELETE of the Link. 2696

• The "ttl" Property Value shall be assigned by the RD and it shall be included in the response. 2697 The RD should use the value included in the UPDATE request but may assign a value that is 2698 lower if it is not able to honour the requested "ttl" value. After this time elapses, the RD shall 2699 remove the Links. To keep a Link alive the publishing Device may update the "ttl" using the 2700 UPDATE schema. 2701

The RD shall add the new Links to its “/oic/res” and expose them to a valid discovery query, i.e. 2702 RETRIEVE request: 2703

2704

{ "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "links": [ { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/myLightSwitch", "rt": ["oic.r.switch.binary"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm": 3}, "eps": [ {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, {"ep": "coaps://[fe80::b1d6]:1122"}, {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} ],

"ins": 11235 }, { "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", "href": "/myLightBrightness", "rt": ["oic.r.brightness"], "if": ["oic.if.a", "oic.if.baseline"], "p": {"bm": 3}, "eps": [ {"ep": "coaps://[[2001:db8:a::123]:2222"} ],

"ins": 112358


} ], "ttl": 600 }

2705

Once a publishing Device has published Resources to an RD, it may choose not respond to the 2706 multicast discovery queries for the same Rresources against its own "/oic/res", especially when 2707 on the same multicast domain as the RD. After publishing Resources, primarily it is the RDs 2708 responsibility to reply to the queries for the published Resources. 2709

There is another possibility that the RD and the publishing Device both respond to the multicast 2710 query from the discovering Device. This will create a duplication of the information but is an 2711 alternative that may be used for non-robust networks. It is not a recommended option but for 2712 industrial scenarios, this is one of the possibilities. Either way, discovering Clients need to always 2713 be prepared to process duplicate information in responses to multicast discovery request. The 2714 "/oic/rd" schema is as defined in D.13 to specify publishing to the "/oic/rd" Resrouce. 2715

11.3.6.3.3 UPDATE Resource information 2716

An RD shall hold the published Link until the time specified in the "ttl" field expires. A publishing 2717 Device may send an UPDATE if it seeks the RD to keep holding the Link or modify the published 2718 Link (e.g. changing Endpoint information). In case of a change in published Resource information 2719 (e.g., IP address change), UPDATE is needed to maintain the published Link up-to-date. An 2720 UPDATE request may be used to modify all Resources that are published on an RD or per 2721 Resource published. 2722

Only the publishing Device may change the Links for the Resources published to an RD. If a Client 2723 sends an UPDATE request to modify Links that belong to a different publishing Device, the RD 2724 shall respond with an appropriate error message. The RD may verify whether the UPDATE request 2725 is from the same publishing Device with the "deviceuuid", i.e., "di", associated with the secured 2726 channel through which the request is received. 2727

Changes are done using the same UPDATE request to "oic/rd". An UPDATE request message 2728 shall use the same payload format but each Link to be modified shall include the "ins" Parameter 2729 which the RD previously provided in the UPDATE response message. 2730

Upon granting the request, the RD shall reflect the change to the Link in its "/oic/res" and sends 2731 back the UPDATE response using the same format as the initial publishing. 2732

11.3.6.3.4 Delete Resource information 2733

Resource information held by the RD is only allowed to be removed by the publishing Device. The 2734 removal may occur at any time during the publication of the Links. If a Client sends a DELETE 2735 request to remove Links that belong to a different publishing Device, the RD shall respond with an 2736 appropriate error message. The RD may verify whether the DELETE request is from the same 2737 publishing Device with the "deviceuuid", i.e., "di", associated with the secured channel through 2738 which the request is received. The DELETE request may be either for the whole Device information 2739 or for a particular Resource. 2740

A publishing Device may remove its published Link or Links from an RD by sending a DELETE 2741 request with the query parameter "di " or "ins" indicating the Links to be removed. If the DELETE 2742 request does not contain one of these two query parameters, the RD shall ignore the DELETE 2743 request and send an appropriate error message. Upon granting the request, the RD shall remove 2744 the identified Links and send back a DELETE response. 2745


• di –When present, the entire set of Links corresponding to the Device ID shall be removed, i.e. 2746 the Links published by the publishing Device with the same Device ID are removed. 2747

• ins –When present, the Link with the same instance value shall be removed. 2748

DELETE /oic/rd?di=0685B960-736F-46F7-BEC0-9E6CBD671ADC1

DELETE /oic/rd?ins=112358

2749

11.3.6.3.5 Transfer Resource information from one RD to another 2750

When a publishing Device identifies an RD that is better suited, it may decide to publish to that 2751 RD. The publishing Device may delete previously published information from the currently used 2752 RD before publishing to the newly selected RD. The deletion of the Resource(s) may be done 2753 either by allowing the "ttl" to expire or explicitly sending a DELETE request to remove the 2754 Rresource information. After the publishing Device has removed the Resources from one RD and 2755 before it has added them to another RD, the publishing Device shall respond to any Resource 2756 discovery request. RDs may not transfer Resource information between themselves due to the 2757 restriction on publishable Resources. It is the publishing Device’s responsibility to choose the RD 2758 and to manage the published Resources. 2759

11.3.6.4 Resource exposure 2760

11.3.6.4.1 "/oic/res" and retrieving of the Resources 2761

The "/oic/res" based discovery process remains the same as that in the absence of an RD. 2762 Resources may be discovered by retrieving the "/oic/res" Resource by sending a multicast or 2763 unicast request. In the case of a multicast discovery request, an RD shall include in its response 2764 any published Resources on behalf of the Device that hosts the Resources. Clients should be 2765 prepared to process duplicate Resource information from more than one RD responding with the 2766 same information or from an RD and the hosting Ddevice (publishing the Rresource information) 2767 both responding to the request. Interaction with Resources discovered using the RD is done using 2768 the same mechanism and methods as with Resources discovered by retrieving the "/oic/res" 2769 Resource of the Device hosting the Resources (e.g., connect to the hosting Device and perform 2770 CRUDN operations on the Resource). 2771

Resource Directories provide different "/oic/res" responses according to the requesting Clients, 2772 which indicate their preference with content format. OCF 1.0 Clients request with a “Content 2773 Format of "application/vnd.ocf+cbor" in the Accept Option, whereas the the Content-Format 2774 "application/cbor" in the Accept Option indicates OIC 1.1 Clients. For OIC 1.1 Clients, the "/oic/res" 2775 response includes Links conforming to OIC 1.1 specification, which OIC 1.1 Clients can understand. 2776 In this case the Resources hosted by the same Device shall be grouped together within a single 2777 JSON Object with "di" indicating the hosting Device. For a 3rd party Resource, i.e., a Resource 2778 which doesn't belong to the responding RD, its "href" value shall be a fully qualified transfer 2779 protocol URI with an IP address and port number as its authority component (e.g., 2780 coaps://[2001:db8:b::c2e5]:22222/myLightSwitch). 2781

For example, an RD might return the following to an OIC 1.1 Clients: 2782

[ 2783 { 2784 "di": "88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2785 "links": [ 2786 { 2787 "href": "/oic/res", 2788 "rel": "self", 2789 "rt": ["oic.wk.res"], 2790


"if": ["oic.if.ll", "oic.if.baseline"], 2791 "p": {"bm": 3, "sec": false} 2792 }, 2793 { 2794 "href": "/oic/d", 2795 "rt": ["oic.wk.d", "oic.d.fan"], 2796 "if": ["oic.if.r", "oic.if.baseline"], 2797 "p": {"bm": 3, "sec": false} 2798 }, 2799 { 2800 "href": "/oic/p", 2801 "rt": ["oic.wk.p"], 2802 "if": ["oic.if.r", "oic.if.baseline"], 2803 "p": {"bm": 3, "sec": true, "port": 33333} 2804 }, 2805 { 2806 "href": "/myFanIntrospection", 2807 "rt": ["oic.wk.introspection"], 2808 "if": ["oic.if.r", "oic.if.baseline"], 2809 "p": {"bm": 3, "sec": true, "port": 33333} 2810 }, 2811 { 2812 "href": "/oic/rd", 2813 "rt": ["oic.wk.rd"], 2814 "if": ["oic.if.baseline"], 2815 "p": {"bm": 3, "sec": true, "port": 33333} 2816 }, 2817 { 2818 "href": "/myFanSwitch", 2819 "rt": ["oic.r.switch.binary"], 2820 "if": ["oic.if.a", "oic.if.baseline"], 2821 "p": {"bm": 3, "sec": true, "port": 33333} 2822 }, 2823 { 2824 "href": "/oic/sec/doxm", 2825 "rt": ["oic.r.doxm"], 2826 "if": ["oic.if.baseline"], 2827 "p": {"bm": 1, "sec": false} 2828 }, 2829 { 2830 "href": "/oic/sec/pstat", 2831 "rt": ["oic.r.pstat"], 2832 "if": ["oic.if.baseline"], 2833 "p": {"bm": 1, "sec": true, "port": 33333} 2834 }, 2835 { 2836 "href": "/oic/sec/cred", 2837 "rt": ["oic.r.cred"], 2838 "if": ["oic.if.baseline"], 2839 "p": {"bm": 1, "sec": true, "port": 33333} 2840 }, 2841 { 2842 "href": "/oic/sec/acl2", 2843 "rt": ["oic.r.acl2"], 2844 "if": ["oic.if.baseline"], 2845 "p": {"bm": 1, "sec": true, "port": 33333} 2846 } 2847 ] 2848 }, 2849 { 2850 "di": "dc70373c-1e8d-4fb3-962e-017eaa863989", 2851 "links": [ 2852 { 2853


"href": "coap://[2001:db8:b::c2e5]:66666/oic/d", 2854 "rt": ["oic.wk.d", "oic.d.light", "oic.d.virtual"], 2855 "if": ["oic.if.r", "oic.if.baseline"], 2856 "p": {"bm": 3, "sec": false} 2857 }, 2858 { 2859 "href": "coaps://[2001:db8:b::c2e5]:22222/oic/p", 2860 "rt": ["oic.wk.p"], 2861 "if": ["oic.if.r", "oic.if.baseline"], 2862 "p": {"bm": 3, "sec": true, "port": 22222} 2863 }, 2864 { 2865 "href": "coaps://[2001:db8:b::c2e5]:22222/myLightSwitch", 2866 "rt": ["oic.r.switch.binary"], 2867 "if": ["oic.if.a", "oic.if.baseline"], 2868 "p": {"bm": 3, "sec": true, "port": 22222} 2869 }, 2870 { 2871 "href": "coaps://[2001:db8:b::c2e5]:22222/myLightBrightness", 2872 "rt": ["oic.r.brightness"], 2873 "if": ["oic.if.a", "oic.if.baseline"], 2874 "p": {"bm": 3, "sec": true, "port": 22222} 2875 } 2876 ] 2877 } 2878 ] 2879 2880

For OCF 1.0 Clients, the "/oic/res" response includes the OCF 1.0 Links with the "anchor" 2881 Parameter containing an OCF URI. The "/oic/res" response has a single array of Links to conform 2882 to IETF RFC 6690. Each Link shall contain the "anchor" Parameter of the value OCF URI where 2883 the authority component of <deviceID> indicates the Device hosting the target Resource. 2884

For example, an RD may return the following to an OCF 1.0 Client. 2885

[ 2886 { 2887 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2888 "href": "/oic/res", 2889 "rel": "self", 2890 "rt": ["oic.wk.res"], 2891 "if": ["oic.if.ll", "oic.if.baseline"], 2892 "p": {"bm": 3}, 2893 "eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2894 {"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2895 }, 2896 { 2897 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2898 "href": "/oic/d", 2899 "rt": ["oic.wk.d", "oic.d.fan"], 2900 "if": ["oic.if.r", "oic.if.baseline"], 2901 "p": {"bm": 3}, 2902 "eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2903 {"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2904 }, 2905 { 2906 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2907 "href": "/oic/p", 2908 "rt": ["oic.wk.p"], 2909 "if": ["oic.if.r", "oic.if.baseline"], 2910 "p": {"bm": 3}, 2911 "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2912


}, 2913 { 2914 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2915 "href": "/myFanIntrospection", 2916 "rt": ["oic.wk.introspection"], 2917 "if": ["oic.if.r", "oic.if.baseline"], 2918 "p": {"bm": 3}, 2919 "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2920 }, 2921 { 2922 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2923 "href": "/oic/rd", 2924 "rt": ["oic.wk.rd"], 2925 "if": ["oic.if.baseline"], 2926 "p": {"bm": 3}, 2927 "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2928 }, 2929 { 2930 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2931 "href": "/myFanSwitch", 2932 "rt": ["oic.r.switch.binary"], 2933 "if": ["oic.if.a", "oic.if.baseline"], 2934 "p": {"bm": 3}, 2935 "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2936 }, 2937 { 2938 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2939 "href": "/oic/sec/doxm", 2940 "rt": ["oic.r.doxm"], 2941 "if": ["oic.if.baseline"], 2942 "p": {"bm": 1}, 2943 "eps": [{"ep": "coap://[2001:db8:a::b1d4]:77777"}, 2944 {"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2945 }, 2946 { 2947 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2948 "href": "/oic/sec/pstat", 2949 "rt": ["oic.r.pstat"], 2950 "if": ["oic.if.baseline"], 2951 "p": {"bm": 1}, 2952 "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2953 }, 2954 { 2955 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2956 "href": "/oic/sec/cred", 2957 "rt": ["oic.r.cred"], 2958 "if": ["oic.if.baseline"], 2959 "p": {"bm": 1}, 2960 "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2961 }, 2962 { 2963 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 2964 "href": "/oic/sec/acl2", 2965 "rt": ["oic.r.acl2"], 2966 "if": ["oic.if.baseline"], 2967 "p": {"bm": 1}, 2968 "eps": [{"ep": "coaps://[2001:db8:a::b1d4]:33333"}] 2969 }, 2970 2971 { 2972 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2973 "href": "/oic/d", 2974 "rt": ["oic.wk.d", "oic.d.light"], 2975


"if": ["oic.if.r", "oic.if.baseline"], 2976 "p": {"bm": 3}, 2977 "eps": [{"ep": "coap://[2001:db8:b::c2e5]:66666"}, 2978 {"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2979 }, 2980 { 2981 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2982 "href": "/oic/p", 2983 "rt": ["oic.wk.p"], 2984 "if": ["oic.if.r", "oic.if.baseline"], 2985 "p": {"bm": 3}, 2986 "eps": [{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2987 }, 2988 { 2989 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2990 "href": "/myLightSwitch", 2991 "rt": ["oic.r.switch.binary"], 2992 "if": ["oic.if.a", "oic.if.baseline"], 2993 "p": {"bm": 3}, 2994 "eps": [{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 2995 }, 2996 { 2997 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2998 "href": "/myLightBrightness", 2999 "rt": ["oic.r.brightness"], 3000 "if": ["oic.if.a", "oic.if.baseline"], 3001 "p": {"bm": 3}, 3002 "eps": [{"ep": "coaps://[2001:db8:b::c2e5]:22222"}] 3003 } 3004 ] 3005

3006

11.4 Notification 3007

Overview 3008

A Server shall support NOTIFY operation to enable a Client to request and be notified of desired 3009 states of one or more Resources in an asynchronous manner. section 11.4.2 specifies the observe 3010 mechanism in which updates are delivered to the requester. 3011

Observe 3012

In observe mechanism the Client utilizes the RETRIEVE operation to require the Server for updates 3013 in case of Resource state changes. The Observe mechanism consists of five steps which are 3014 depicted in Figure 19 and described below. 3015

Note: the observe mechanism can only be used for a resource with a property of observable 3016 (section 7.3.2.2). 3017


3018

Figure 19. Observe Mechanism 3019

11.4.2.1 RETRIEVE request with observe indication 3020

The Client transmits a RETRIEVE request message to the Server to request updates for the 3021 Resource on the Server if there is a state change. The RETRIEVE request message carries the 3022 following parameters: 3023


• to: Resource that the Client is requesting to observe 3025

• ri: Identifier of the RETRIEVE request 3026

• op: RETRIEVE 3027

• obs: Indication for observe request 3028

11.4.2.2 Processing by the Server 3029

Following the receipt of the RETRIEVE request, the Server may validate if the Client has the 3030 appropriate rights for the requested operation and the properties are readable and observable. If 3031 the validation is successful, the Server caches the information related to the observe request. The 3032 Server caches the value of the ri parameter from the RETRIEVE request for use in the initial 3033 response and future responses in case of a change of state. 3034

11.4.2.3 RETRIEVE response with observe indication 3035

The Server shall transmit a RETRIEVE response message in response to a RETRIEVE request 3036 message from a Client. The RETRIEVE response message shall include the following parameters. 3037 If validation succeeded, the response includes an observe indication. If not, the observe indication 3038 is omitted from the response which signals to the requesting client that registration for notification 3039 was not allowed. 3040

The RETRIEVE response message shall include the following parameters: 3041



• ri: Identifier included in the RETRIEVE request 3044

• cn: Information resource representation as requested by the Client 3045

• rs: The result of the RETRIEVE operation 3046


• obs: Indication that the response is made to an observe request 3047

11.4.2.4 Resource monitoring by the Server 3048

The Server shall monitor the state the Resource identified in the observe request from the Client. 3049 Anytime there is a change in the state of the observed resource, the Server sends another 3050 RETRIEVE response with the observe indication. The mechanism does not allow the client to 3051 specify any bounds or limits which trigger a notification, the decision is left entirely to the server. 3052

11.4.2.5 Additional RETRIEVE responses with observe indication 3053

The Server shall transmit updated RETRIEVE response messages following observed changes in 3054 the state of the Resources indicated by the Client. The RETRIEVE response message shall include 3055 the parameters listed in section 11.4.2.3. 3056

11.4.2.6 Cancelling Observe 3057

The Client can explicitly cancel observe by sending a RETRIEVE request without the observe 3058 indication field to the same resource on Server which it was observing. For certain protocol 3059 mappings, the client may also be also be able to cancel an observe by ceasing to respond to the 3060 RETRIEVE responses. 3061

11.5 Device management 3062

Overview 3063

The Device Management includes the following functions: 3064

• Diagnostics and maintenance 3065

The device management functionalities specified in this version of specification are intended to 3066 address the basic device management features. Addition of new device management features in 3067 the future versions of the specification is expected. 3068

Diagnostics and maintenance 3069

The Diagnostics and Maintenance function is intended for use by administrators to resolve issues 3070 encountered with the Devices while operating in the field. If diagnostics and maintenance is 3071 supported by a Device, the Core Resource “/oic/mnt” shall be supported as described in Table 24. 3072

Table 24. Optional diagnostics and maintenance device management Core Resources 3073

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

Device Management

3074

Table 25 defines the “oic.wk.mnt” Resource Type. At least one of the Factory_Reset, and Reboot 3075 properties shall be implemented. 3076

Table 25. “oic.wk.mnt” Resource Type definition 3077


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)

3078

Note: * - Default indicates the value of this property as soon as the device is rebooted or factory reset 3079

3080

11.6 Scenes 3081

Introduction 3082

Scenes are a mechanism for automating certain operations. 3083

A scene is a static entity that stores a set of defined resource property values for a collection of 3084 resources. Scenes provide a mechanism to store a setting over multiple Resources that may be 3085 hosted by multiple separate Servers. Scenes, once set up, can be used by multiple Clients to recall 3086 a setup. 3087

Scenes can be grouped and reused, a group of scenes is also a scene. 3088

In short, scenes are bundled user settings. 3089

Scenes 3090


Scenes are described by means of resources. The scene resources are hosted by a Server and 3092 the top level resource is listed in “/oic/res”. This means that a Client can determine if the scene 3093 functionality is hosted on a Server via a RETRIEVE on “/oic/res” or via Resource discovery. The 3094 setup of scenes is driven by Client interactions. This includes creating new scenes, and mappings 3095 of Server resource properties that are part of a scene. 3096

The scene functionality is created by multiple resources and has the structure depicted in Figure 3097 20. The sceneList and sceneCollection resources are overloaded collection resources. The 3098 sceneCollection contains a list of scenes. This list contains zero or more scenes. The 3099 sceneMember resource contains the mapping between a scene and what needs to happen 3100 according to that scene on an indicated resource. 3101


3102

Figure 20 Generic scene resource structure 3103

11.6.2.2 Scene creation 3104

A Client desiring to interact with scenes needs to first determine if the server supports the scene 3105 feature; the sceneMembers of a scene do not have to be co-located on the server supporting the 3106 scene feature. This can be done by checking if “/oic/res” contains the rt of the sceneList resource. 3107 This is depicted in first steps of Figure 21. The sceneCollection is created by the Server using 3108 some out of bound mechanism, Client creation of scenes is not supported at this time. This will 3109 entail defining the scene with an applicable list of scene values and the mappings for each 3110 Resource being part of the scene. The mapping for each resource being part of the sceneCollection 3111 is described by a resource called sceneMember. The sceneMember resource contains the link to 3112 a resource and the mapping between the scene listed in the sceneValues property and the actual 3113 resource property value of the Resource indicated by the link. 3114


3115

Figure 21 Interactions to check Scene support and setup of specific scenes 3116

11.6.2.3 Interacting with Scenes 3117

All capable Clients can interact with scenes. The allowed scene values and the last applied scene 3118 value can be retrieved from the server hosting the scene. The scene value shall be changed by 3119 issuing an UPDATE operation with a payload that sets the lastScene property to one of the listed 3120 allowed scene values. These steps are depicted in Figure 22. Note that the lastScene value does 3121 not imply that the current state of all resources that are part of the scene will be at the mapped 3122 value. This is due to that the setting the scene values are not modelled as actual states of the 3123 system. This means that another Client can change just one resource being part of the scene 3124 without having feedback that the state of the scene is changed. 3125


3126

Figure 22 Client interactions on a specific scene 3127

As described previously, a scene can reference one or more resources that are present on one or 3128 more Servers. The scene members are re-evaluated each time a scene change takes place. This 3129 evaluation is triggered by a Client that is either embedded as part of the Server hosting the scene, 3130 or separate to the server having knowledge of the scene via a RETRIEVE operation, observing the 3131 referenced resources using the mechanism described in section 11.4.2. During the evaluation the 3132 mappings for the new scene value will be applied to the Server. This behaviour is depicted in 3133 Figure 23. 3134


3135

Figure 23 Interaction overview due to a Scene change 3136

11.6.2.4 Summary of Resource Types defined for Scene functionality 3137

Table 26 summarizes the list of Resource Types that are part of Scenes. 3138

Table 26 list of Resource Types for Scenes 3139

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 3140

Creation of Scenes on a Server that is capable of this functionality is dependent on the ACLs 3141 applied to the resources and the Client having the appropriate permissions. Interaction between 3142 a Client (embedded or separate) and a Server that hosts the resource that is referenced as a scene 3143 member is contingent on the Client having appropriate permissions to access the resource on the 3144 host Server. 3145

See OCF Security for details on the use of ACLs and also the mechanisms around Device 3146 Authentication that are necessary to ensure that the correct permissions exist for the Client to 3147 access the scene member resource(s) on the Server. 3148


11.7 Icons 3149

Overview 3150

Icons are a primitive that are needed by various OCF subsystems, such as bridging. An optional 3151 Resource Type of “oic.r.icon” has been defined to provide a common representation of an icon 3152 Resource that can be used by Devices. 3153

Resource 3154

The icon Resource is as defined in Table 27. 3155

Table 27. Optional Icon Core Resource 3156

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

Icon

3157

Table 28 defines the details for the “oic.r.icon” Resource Type. 3158

Table 28. “oic.r.icon” Resource Type definition 3159


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.

3160

11.8 Introspection 3161

Overview 3162

Introspection is a mechanism to announce the capabilities of Resources hosted on the Device. 3163

The intended usage of the Introspection Device Data is to enable dynamic clients. E.g. clients that 3164 can use the Introspection Device Data to generate dynamically an UI or dynamically create 3165 translations of the hosted Resources to another eco-system. Other usages of the Introspection is 3166 that the information can be used to generate client code. The Introspection Device Data is designed 3167 to augment the existing data already on the wire. This means that existing mechanism needs to 3168 be used to get a full overview of what is implemented in the Device. For example the Introspection 3169 Device Data does not convey information about observe, since that is already conveyed with the 3170 “p” property on the links in “/oic/res” (see section 7.8.2.1.2). 3171


The Introspection Device Data is recommended to be conveyed as "static" data. Meaning that the 3172 data does not change during the uptime of a Device. However when the data is not static the 3173 Introspection Resource shall indicate to be observable and the url property value of 3174 “oic.wk.introspection” Resource shall change to indicate that the Introspection Device Data is 3175 changed. 3176

The Introspection Device Data describes the Resources that make up the Device. For the complete 3177 list of included Resources Table 13. The Introspection Device Data is described as a swagger2.0 3178 in JSON format file. The swagger2.0 file will contain the description of the Resources as defined 3179 below: All Resources with the next remarks: 3180

• The URLs of the Resources in the Introspection Device Data shall be without the endpoint 3181 description, e.g. it shall not be a full URL but only the relative path from the endpoint. The 3182 relative path shall be the same as being conveyed by “/oic/res”. 3183

• “/oic/res” Resource shall not be listed in the Introspection Device Data. 3184

• The Resources “/oic/d”, “/oic/p” and the security Resources are allowed to be present in the 3185 Introspection Device Data, but are not required. The “/oic/d”, “/oic/p”, “/oic/res” and the security 3186 Resources shall be included when vendor defined or optional properties are implemented. 3187

• All other Resources are required to be listed in the Introspection Device Data. 3188

• Per Resource it will include: 3189

o All Implemented Methods 3190

o Per Supported Method: 3191

Implemented queryParameters per Method. 3192

• This includes the supported interfaces ("if") as enum value. 3193

Schemas of the payload for the request and response bodies of the Method 3194

The schema data shall be conveyed by the swagger schema object as 3195 defined in the parameters section. 3196

The swagger2.0 schema object shall comply with: 3197

• The schemas shall be fully resolved, e.g. no references shall exist 3198 outside the swagger file. 3199

• The schemas shall list which interfaces are supported on the method. 3200

• The schemas shall list if a property is optional or required. 3201

• The schemas shall indicate if an property is read only or read-write 3202

o By means of the readOnly schema tag belonging to the 3203 property 3204

• The default value of the “rt” property shall be used to indicate the 3205 supported Resource Types. 3206

• oneOf and anyOf constructs are allowed to be used as part of an 3207 swagger2.0 schema object. 3208

Dynamic Resources (e.g. Resources that can be created up on a request by a Client) shall have 3209 an URL definition which contains a URL identifier (e.g. using the {} syntax). An URL with {} identifies 3210 that the Resource definition applies to the whole group of Resources that can be created. The 3211 actual path can contain the collection node that links to the Resource. 3212

Example of an URL with identifiers: 3213

/SceneListResURI/{SceneCollectionResURI}/{SceneMemberResURI}: 3214


When different Resource Types are allowed to be created in a collection, then the different 3215 schemas for the create method shall define all possible Resource Types that can be created. The 3216 schema construct oneOf allows the definition of a schema with selectable Resources. The oneOf 3217 construct allows the integration of all schemas and that only one existing sub schemas shall be 3218 used to indicate the definition of the Resource that can be created. 3219

Example usage of oneOf JSON schema construct: 3220

{ 3221

"oneOf": [ 3222

{ <<subschema 1 definition>> }, 3223

{ << sub schema 2 definition >> } 3224

… 3225

] 3226

} 3227

3228

A Client using the Introspection Device Data of a Device should check the version of the supported 3229 Introspection Device Data of the Device. The swagger version is indicated in each file with the tag 3230 "swagger". Example of the 2.0 supported version of the tag is: "swagger": "2.0". Later versions of 3231 the spec may reference newer versions of the swagger specification, for example 3.0. 3232

A Server shall support one Resource with a Resource Type of “oic.wk.introspection” as defined in 3233 Table 29. The Resource with a Resource Type of “oic.wk.introspection” shall be included in the 3234 Resource “/oic/res”. 3235

Table 29. Introspection Resource 3236

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

3237

Table 30defines “oic.wk.introspection” Resource Type. 3238

Table 30. “oic.wk.introspection” Resource Type definition 3239


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 3240

The Introspection Device Data is retrieved in the following steps: 3241

1) Check if the Introspection Resource is supported and retrieve the URL of the Resource. 3242

2) Retrieve the contents of the Introspection Resource 3243

3) Download the Introspection Device Data from the URL specified the Introspection Resource. 3244

4) Usage of the Introspection Device Data by the Client 3245

3246

3247

Figure 24 Interactions to check Introspection support and download the Introspection 3248 Device Data. 3249


12 Messaging 3250


This section specifies the protocol messaging mapping to the CRUDN messaging operations 3252 (section 8) for each messaging protocol specified (e.g., CoAP.). Mapping to additional protocols is 3253 expected in later version of this specification. All the property information from the resource model 3254 shall be carried within the message payload. This payload shall be generated in the resource 3255 model layer and shall be encapsulated in the data connectivity layer. The message header shall 3256 only be used to describe the message payload (e.g., verb, mime-type, message payload format), 3257 in addition to the mandatory header fields defined in messaging protocol (e.g., CoAP) specification. 3258 If the message header does not support this, then this information shall also be carried in the 3259 message payload. Resource model information shall not be included in the message header 3260 structure unless the message header field is mandatory in the messaging protocol specification. 3261

12.2 Mapping of CRUDN to CoAP 3262

Overview 3263

A Device implementing CoAP shall conform to IETF RFC 7252 for the methods specified in section 3264 12.2.3. A Device implementing CoAP shall conform to IETF RFC 7641 to implement the CoAP 3265 Observe option. Support for CoAP block transfer when the payload is larger than the MTU is 3266 defined in section 12.2.8. 3267

URIs 3268

An OCF: URI is mapped to a coap: URI by replacing the scheme name ‘oic’ with ‘coap’ if unsecure 3269 or ‘coaps’ if secure before sending over the network by the requestor. Similarly on the receiver 3270 side, the scheme name is replaced with ‘oic’. 3271

Any query string that is present within the URI is encoded as one or more URI-Query Options as 3272 defined in IETF RFC 7252 section 6.4. 3273

3274

CoAP method with request and response 3275

12.2.3.1 Overview 3276

Every request has a CoAP method that realizes the request. The primary methods and their 3277 meanings are shown in Table 31, which provides the mapping of GET/PUT/POST/DELETE 3278 methods to CREATE, RETRIEVE, UPDATE, and DELETE operations. The associated text provides 3279 the generic behaviours when using these methods, however resource interfaces may modify these 3280 generic semantics. 3281 3282

Table 31. CoAP request and response 3283

Method for CRUDN (mandatory) Request data (mandatory) Response data

GET for RETRIEVE

- Method code: GET (0.01) - Request URI: an existing URI for the Resource to be retrieved

- Response code: success (2.xx) or error (4.xx or 5.xx) - Payload: Resource representation of the target Resource (when successful)

POST for CREATE

- Method code: POST (0.02) - Request URI: an existing URI for the Resource responsible for the creation - Payload: Resource presentation of the Resource to be created

- Response code: success (2.xx) or error (4.xx or 5.xx) - Payload: the URI of the newly created Resource (when successful).


PUT for CREATE

- Method code: PUT (0.03) - Request URI: a new URI for the Resource to be created. - Payload: Resource presentation of the Resource to be created.

- Response code: success (2.xx) or error (4.xx or 5.xx)

POST for UPDATE

- Method code: POST (0.02) - Request URI: an existing URI for the Resource to be updated. - Payload: representation of the Resource to be updated.

- Response Code: success (2.xx) or error (4.xx or 5.xx)

DELETE for DELETE

- Method code: DELETE (0.04) - Request URI: an existing URI for the Resource to be deleted.

- Response code: success (2.xx) or error (4.xx or 5.xx)

3284

12.2.3.2 CREATE with POST or PUT 3285

12.2.3.2.1 With POST 3286

POST shall be used only in situations where the request URI is valid, that is it is the URI of an 3287 existing Resource on the Server that is processing the request. If no such Resource is present, 3288 the Server shall respond with an error response code of 4.xx. The use of POST for CREATE shall 3289 use an existing request URI which identifies the Resource on the Server responsible for creation. 3290 The URI of the created Resource is determined by the Server and provided to the Client in the 3291 response. 3292

A Client shall include the representation of the new Resource in the request payload. The new 3293 resource representation in the payload shall have all the necessary properties to create a valid 3294 Resource instance, i.e. the created Resource should be able to properly respond to the valid 3295 Request with mandatory Interface (e.g., “GET with ?if=oic.if.baseline”). 3296

Upon receiving the POST request, the Server shall either 3297

• create the new Resource with a new URI, respond with the new URI for the newly created 3298 Resource and a success response code (2.xx); or 3299

• respond with an error response code (4.xx or 5.xx). 3300

POST is unsafe and is the supported method when idempotent behaviour cannot be expected or 3301 guaranteed. 3302

12.2.3.2.2 With PUT 3303

PUT shall be used to create a new Resource or completely replace the entire representation of an 3304 existing Resource. The resource representation in the payload of the PUT request shall be the 3305 complete representation. PUT for CREATE shall use a new request URI identifying the new 3306 Resource to be created. 3307

The new resource representation in the payload shall have all the necessary properties to create 3308 a valid Resource instance, i.e. the created Resource should be able to properly respond to the 3309 valid Request with mandatory Interface (e.g. “GET with ?if=oic.if.baseline”). 3310

Upon receiving the PUT request, the Server shall either 3311

• create the new Resource with the request URI provided in the PUT request and send back a 3312 response with a success response code (2.xx); or 3313



PUT is an unsafe method but it is idempotent, thus when a PUT request is repeated the outcome 3315 is the same each time. 3316

12.2.3.3 RETRIEVE with GET 3317

GET shall be used for the RETRIEVE operation. The GET method retrieves the representation of 3318 the target Resource identified by the request URI. 3319

Upon receiving the GET request, the Server shall either 3320

• send back the response with the representation of the target Resource with a success response 3321 code (2.xx); or 3322

• respond with an error response code (4.xx or 5.xx) or ignore it (e.g. non-applicable multicast 3323 GET). 3324

GET is a safe method and is idempotent. 3325

12.2.3.4 UPDATE with POST 3326

POST shall be used only in situations where the request URI is valid, that is it is the URI of an 3327 existing Resource on the Server that is processing the request. If no such Resource is present, 3328 the Server shall respond with an error response code of 4.xx. A client shall use POST to UPDATE 3329 Property values of an existing Resource (see sections 3.1.32 and 8.4.2). 3330

Upon receiving the request, the Server shall either 3331

• apply the request to the Resource identified by the request URI in accordance with the applied 3332 interface (i.e. POST for non-existent Properties is ignored) and send back a response with a 3333 success response code (2.xx); or 3334

• respond with an error response code (4.xx or 5.xx). Note that if the representation in the 3335 payload is incompatible with the target Resource for POST using the applied interface (i.e. the 3336 "overwrite" semantic cannot be honored because of read-only property in the payload), then 3337 the error response code 4.xx shall be returned. 3338

POST is unsafe and is the supported method when idempotent behaviour cannot be expected or 3339 guaranteed. 3340

12.2.3.5 DELETE with DELETE 3341

DELETE shall be used for DELETE operation. The DELETE method requests that the resource 3342 identified by the request URI be deleted. 3343 Upon receiving the DELETE request, the Server shall either 3344 • delete the target Resource and send back a response with a success response code (2.xx); or 3345


DELETE is unsafe but idempotent (unless URIs are recycled for new instances). 3347 3348 3349

Content-Format negotiation 3350

The OCF Framework mandates support of CBOR, however it allows for negotiation of the payload 3351 body if more than one Content-Format (e.g. CBOR and JSON) is supported by an implementation. 3352 In this case the Accept Option defined in section 5.10.4 of IETF RFC 7252 shall be used to indicate 3353 which Content–Format (e.g. JSON) is requested by the Client. 3354

The Content-Formats supported are shown in Table 32. 3355


Table 32. OCF Content-Formats 3356

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 3357 shall include a Content-Format Option for all success (2.xx) responses with a payload body. Per 3358 IETF RFC 7252 section 5.5.1, Servers shall include a Content-Format Option for all error (4.xx or 3359 5.xx) responses with a payload body unless they include a Diagnostic Payload; error responses 3360 with a Diagnostic Payload do not include a Content-Format Option. The Content-Format Option 3361 shall use the ID column numeric value from Table 32. An OCF vertical may mandate a specific 3362 Content-Format Option. 3363

Clients shall also include an Accept Option in every request message. The Accept Option shall 3364 indicate the required Content-Format as defined in Table 32 for response messages. The Server 3365 shall return the required Content-Format if available. If the required Content-Format cannot be 3366 returned, then the Server shall respond with an appropriate error message. 3367

OCF-Content-Format-Version information 3368

Servers and Clients shall include the OCF-Content-Format-Version Option in both request and 3369 response messages with a payload. Clients shall include the OCF-Accept-Content-Format-Version 3370 Option in request messages. The OCF-Content-Format-Version Option and OCF-Accept-Content-3371 Format-Version Option are specified as Option Numbers in the CoAP header as shown in Table 3372 33. 3373

Table 33. OCF-Content-Format-Version and OCF-Accept-Content-Format-Version Option 3374 Numbers 3375

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 both the OCF-Accept-Content-Format-Version Option and the OCF-Content-Format-3376 Version Option is a two-byte unsigned integer that is used to define the major, minor and sub 3377 versions. The major and minor versions are represented by 5 bits and the sub version is 3378 represented by 6 bits as shown in Table 34. 3379

Table 34. OCF-Accept-Content-Format-Version and OCF-Content-Format-Version 3380 Representation 3381

Major Version Minor Version Sub Version Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

Table 35 illustrates several examples: 3382

Table 35. Examples of OCF-Content-Format-Version and OCF-Accept-Content-Format-3383 Version Representation 3384

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 Option and OCF-Content-Format-Version Option for this 3385 version of the specification shall be 1.0.0 (i.e. 0b0000 1000 0000 0000). 3386

Content-Format policy 3387

To maintain compatibility between devices implemented to different versions of this specification, 3388 Devices shall follow the policy as described in Figure 25. 3389

3390

3391

Figure 25 Content-Format Policy 3392

All Devices shall support the current and all previous Content-Format Option and Versions. Clients 3393 shall send discovery request messages with the current and all previous Content-Format and 3394 Versions until it discovers all Servers in the network. 3395

CRUDN to CoAP response codes 3396

The mapping of CRUDN operations response codes to CoAP response codes are identical to the 3397 response codes defined in IETF RFC 7252. 3398

CoAP block transfer 3399

Basic CoAP messages work well for the small payloads typical of light-weight, constrained IoT 3400 devices. However scenarios can be envisioned in which an application needs to transfer larger 3401 payloads. 3402

CoAP block-wise transfer as defined in https://tools.ietf.org/html/rfc7721 3403

IETF RFC 7959 shall be used by all Servers which generate a content payload that would exceed 3404 the size of a CoAP datagram as the result of handling any defined CRUDN operation. 3405

Similarly, CoAP block-wise transfer as defined in https://tools.ietf.org/html/rfc7721 3406


IETF RFC 7959 shall be supported by all Clients. The use of block-wise transfer is applied to 3407 both the reception of payloads as well as transmission of payloads that would exceed the size of 3408 a CoAP datagram. 3409

All blocks that are sent using this mechanism for a single instance of a transfer shall all have the 3410 same reliability setting (i.e. all confirmable or all non-confirmable). 3411

A Client may support both the block1 (as descriptive) and block2 (as control) options as 3412 described by IETF RFC 7959 A Server may support both the block1 (as control) and block2 (as 3413 descriptive) options as described by https://tools.ietf.org/html/rfc7721 3414

IETF RFC 7959. 3415

12.3 CoAP serialization over TCP 3416

Introduction 3417

In environments where TCP is already available, CoAP can take advantage of it to provide 3418 reliability. Also in some environments UDP traffic is blocked, so deployments may use TCP. For 3419 example, consider a cloud application acting as a Client and the Server is located at the user’s 3420 home. The Server which already support CoAP as a messaging protocol (e.g., Smart Home vertical 3421 profile) could easily support CoAP serialization over TCP rather than adding another messaging 3422 protocol. A Device implementing CoAP Serialization over TCP should conform to IETF draft-ietf-3423 core-coap-tcp-tls-07. 3424

Indication of support 3425

If UDP is blocked, clients depend on the pre-configured details on the device to find support for 3426 CoAP over TCP. If UDP is not-blocked, a Device which supports CoAP serialization over TCP shall 3427 populate the Messaging Protocol (“mpro”) property in “/oic/res” with the value “coap+tcp” or 3428 “coaps+tcp” to indicate that the device supports messaging protocol as specified by section 11.3.4. 3429

Message type and header 3430

The message type transported between Client and Server shall be a non-confirmable message 3431 (NON). The protocol stack used in this scenario should be as described in section 3 in IETF draft-3432 ietf-core-coap-tcp-tls-07. 3433

The CoAP header as described in figure 6 in IETF draft-ietf-core-coap-tcp-tls-07 should be used 3434 for messages transmitted between a Client and a Server. A Device should use “Alternative L3” as 3435 defined in IETF draft-ietf-core-coap-tcp-tls-07. 3436

URI scheme 3437

The URI scheme used shall be as defined in section 6 in IETF draft-ietf-core-coap-tcp-tls-07. 3438

For the “coaps+tcp” URI scheme the “TLS Application Layer Protocol Negotiation Extension” 3439 IETF RFC 7301 shall be used. 3440

KeepAlive 3441

12.3.5.1 Overview 3442

In order to ensure that the connection between a Devices is maintained, when using CoAP 3443 serialization over TCP, a Device that initiated the connection should send application layer 3444 KeepAlive messages. The reasons to support application layer KeepAlive are as follows: 3445

• TCP KeepAlive only guarantees that a connection is alive at the network layer, but not at the 3446 application layer 3447

• Interval of TCP KeepAlive is configurable only using kernel parameters, and is OS dependent 3448 (e.g., 2 hours by default in Linux) 3449


12.3.5.2 KeepAlive Mechanism 3450

Devices supporting CoAP over TCP should use Ping and Pong messages as described in 3451 IETF draft-ietf-core-coap-tcp-tls-07. 3452

CoAP native Cloud 3453

12.3.6.1 Overview 3454

CoAP native Cloud extends the use of CoAP to reach a native Cloud service without the need of 3455 a hub or gateway by utilizing following features 3456

• CoAP over TCP protocol defined in section 12.3 3457

• Keep-Alive defined in section 12.3.5 3458

• Resource Directory defined in section 11.3.6 3459

• Token management defined in section xx of OCF Security 3460

12.3.6.2 Architecture flow 3461

This section describes the operational flow utilitzing CoAP native Cloud for Resource discovery 3462 and endpoint routing. 3463

Figure 26 illustrates the case when a Client discovers the published Resources on a Resource 3464 Directory (RD). The RD responds with Links for the Resources on the Server. The "anchor" 3465 Property and the "eps" Property in the response message imply the value of the Cloud Interface. 3466 The value of the “eps” Property can be the address of Cloud Interface. 3467

3468

3469

Figure 26 Resource discovery through OCF Cloud 3470


3471

Figure 27 illustrates the case when a Client accesses a Server. The Client sends message to 3472 Cloud Interface, then the Cloud Interface will route the packets to the Server. The Cloud Interface 3473 maintains mapping table between URI and packet addressing information (ex, port number, socket 3474 id, etc). 3475

3476

3477

Figure 27 Endpoint routing through OCF Cloud 3478

12.4 Payload Encoding in CBOR 3479

OCF implementations shall perform the conversion to CBOR from JSON defined schemas and to 3480 JSON from CBOR in accordance with IETF RFC 7049 section 4 unless otherwise specified in this 3481 section. 3482

Properties defined as a JSON integer shall be encoded in CBOR as an integer (CBOR major types 3483 0 and 1). Properties defined as a JSON number shall be encoded as an integer, single- or double-3484


precision floating point (CBOR major type 7, sub-types 26 and 27); the choice is implementation 3485 dependent. Half-precision floating point (CBOR major 7, sub-type 25) shall not be used. Integer 3486 numbers shall be within the closed interval [-2^53, 2^53]. Properties defined as a JSON number 3487 should be encoded as integers whenever possible; if this is not possible Properties defined as a 3488 JSON number should use single-precision if the loss of precision does not affect the quality of 3489 service, otherwise the Property shall use double-precision. 3490

3491

On receipt of a CBOR payload, an implementation shall be able to interpret CBOR integer values 3492 in any position. If a property defined as a JSON integer is received encoded other than as an 3493 integer, the implementation may reject this encoding using a final response as appropriate for the 3494 underlying transport (e.g. 4.00 for CoAP) and thus optimise for the integer case. If a property is 3495 defined as a JSON number an implementation shall accept integers, single- and double-precision 3496 floating point. 3497

13 Security 3498

The details for handling security and privacy are specified in [OCF Security]. 3499

3500


Annex A 3501

(informative) 3502

3503

Operation Examples 3504

A.1 Introduction 3505

This section describes some example scenarios using sequence of operations between the entities 3506 involved. In all the examples below “Light” is a Server and “Smartphone” is a Client. In one of the 3507 scenario “Garage” additionally acts as a Server. All the examples are based on the following 3508 example resource definitions: 3509

rt=oic.example.light with Resource Type definition as illustration in Table 36. 3510

Table 36. oic.example.light Resource Type definition 3511


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

3512

rt=oic.example.garagedoor with Resource Type definition as illustration in Table 37. 3513

Table 37. oic.example.garagedoor Resource Type definition 3514


Value type



Name n string R, W no

open-close oc boolean R, W yes Open/Close Control: 0 = Open 1 = Close

3515

“/oic/mnt” (“rt=oic.wk.mnt”) used in below examples is defined in section 11.5.2. 3516

A.2 When at home: From smartphone turn on a single light 3517

This sequence highlights (Figure 28) the discovery and control of an OCF light resource from an 3518 OCF smartphone. 3519

3520


3521

Figure 28. When at home: from smartphone turn on a single light 3522

Discovery request can be sent to “All OCF Nodes” Multicast address FF0X::158 or can be sent 3523 directly to the IP address of device hosting the light resource. 3524

1) Smartphone sends a GET request to “/oic/res” resource to discover all resources hosted on 3525 targeted end point 3526

5) The end point (bulb) responds with the list of Resource URI, Resource Type and 3527 Interfaces supported on the end point (one of the resource is ‘/light’ whose 3528 rt=oic.example.light) 3529

6) Smartphone sends a GET request to ’/light’ resource to know its current state 3530

7) The end point responds with representation of light resource ({n=bedlight;of=0}) 3531

8) Smartphone changes the ‘of’ property of the light resource by sending a POST 3532 request to ‘/light’ resource ({of=1}) 3533

9) On Successful execution of the request, the end point responds with the changed 3534 resource representation. Else, error code is returned. Details of the error codes are defined 3535 in section 12.2.7. 3536

A.3 GroupAction execution 3537

This example will be added when groups feature is added in later version of specification 3538

A.4 When garage door opens, turn on lights in hall; also notify smartphone 3539

This example will be added when scripts feature is added in later version of specification 3540

A.5 Device management 3541

This sequence highlights (Figure 29) the device management function of maintenance. 3542

3543


3544

Figure 29. Device management (maintenance) 3545

Pre-Condition: Admin device has different security permissions and hence can perform device 3546 management operations on the Device 3547

1) Admin device sends a GET request to “/oic/res” resource to discover all resources hosted on 3548 a targeted end point (in this case Bulb) 3549

10) The end point (bulb) responds with the list of Resource URI, Resource Type and Interfaces 3550 supported on the end point (one of the resources is “/oic/mnt” whose “rt=oic.wk.mnt”) 3551

11) Admin Device changes the ‘fr’ property of the maintenance resource by 3552 sending a POST request to “/oic/mnt” resource ({fr=1}). This triggers a factory reset of the 3553 end point (bulb) 3554

12) On successful execution of the request, the end point responds with the changed 3555 resource representation. Else, error code is returned. Details of the error codes are defined 3556 in section 12.2.7. 3557


Annex B 3558

(informative) 3559

3560

OCF interaction scenarios and deployment models 3561

B.1 OCF interaction scenarios 3562

A Client connects to one or multiple Servers in order to access the resources provided by those 3563 Servers. The following are scenarios representing possible interactions among Roles: 3564

• Direct interaction between Client and Server (Figure 30). In this scenario the Client and the 3565 Server directly communicate without involvement of any other Device. A smartphone which 3566 controls an actuator directly uses this scenario. 3567

Server Client

3568

Figure 30. Direct interaction between Server and Client 3569

• Interaction between Client and Server using another server (Figure 31). In this scenario, 3570 another Server provides the support needed for the Client to directly access the desired 3571 resource on a specific Server. This scenario is used for example, when a smartphone first 3572 accesses a discovery server to find the addressing information of a specific appliance, and 3573 then directly accesses the appliance to control it. 3574

Server Client

Server

3575

Figure 31. Interaction between Client and Server using another Server 3576

• Interaction between Client and Server using Intermediary (Figure 32). In this scenario an 3577 Intermediary facilitates the interaction between the Client and the Server. A smartphone which 3578 controls appliances in a smart home via MQTT broker uses this scenario. 3579

Server Intermediary Client

3580

Figure 32. Interaction between Client and Server using Intermediary 3581

• Interaction between Client and Server using support from multiple Servers and intermediary 3582 (Figure 33). In this scenario, both Server and Intermediary roles are present to facilitate the 3583 transaction between the Client and a specific Server. An example scenario is when a 3584


smartphone first accesses a Resource Directory (RD) server to find the address to a specific 3585 appliance, then utilizes MQTT broker to deliver a command message to the appliance. The 3586 smartphone can utilize the mechanisms defined in CoRE Resource Directory such as default 3587 location, anycast address or DHCP to discover the Resource Directory information. 3588

Server Intermediary Client

Server

Server

3589

Figure 33. Interaction between Client and Server using support from multiple Servers and 3590 Intermediary 3591

B.2 Deployment model 3592

In deployment, Devices are deployed and interact via either wired or wireless connections. Devices 3593 are the physical entities that may host resources and play one or more Roles. There is no constraint 3594 on the structure of a deployment or number of Devices in it. Architecture is flexible and scalable 3595 and capable of addressing large number of devices with different device capabilities, including 3596 constrained devices which have limited memory and capabilities. Constrained devices are defined 3597 and categorized in [TCNN]. 3598

3599

Figure 34. Example of Devices 3600


Figure 34 depicts a typical deployment and set of Devices, which may be divided in the following 3601 categories: 3602

• Things: Networked devices which are able to interface with physical environments. Things are 3603 the devices which are primarily controlled and monitored. Examples include smart appliances, 3604 sensors, and actuators. Things mostly take the role of Sever but they may also take the role of 3605 Client, for example in machine-to-machine communications. 3606

• User Devices: Devices employed by the users enabling the users to access resources and 3607 services. Examples include smart phones, tablets, and wearable devices. User Devices mainly 3608 take the role of Client, but may also take the role of Server or Intermediary. 3609

• Service Gateways: Network equipment which take the role of Intermediary. Examples are 3610 home gateways. 3611

• Infra Servers: Data centers residing in cloud infrastructure, which facilitate the interaction 3612 among Devices by providing network services such as AAA, NAT traversal or discovery. It can 3613 also play the role of Client or Intermediary 3614


Annex C 3615

(informative) 3616

3617

Other Resource Models and OCF Mapping 3618

C.1 Multiple resource models 3619

RESTful interactions are defined dependent on the resource model; hence, Devices require a 3620 common understanding of the resource model for interoperability. 3621

There are multiple resource models defined by different organizations including OCF, IPSO 3622 Alliance and oneM2M, and used in the industry, which may restrict interoperability among 3623 respective ecosystems. The main differences from Resource model are as follows: 3624

• Resource structure: Resources may be defined to have properties (e.g., oneM2M defined 3625 resources), or may be defined as an atomic entity and not be decomposable into properties 3626 (e.g., IPSO alliance defined resources). For example, a smart light may be represented as a 3627 resource with an on-off property or a resource collection containing an on-off resource. In the 3628 former, on-off property doesn’t have a URI of its own and can only be accessed indirectly via 3629 the resource. In the latter, being a resource itself, on-off resource is assigned its own URI and 3630 can be directly manipulated. 3631

• Resource name & type: Resources may be allowed to be named freely and have their 3632 characteristics indicated using a Resource Type property (e.g., as defined in oneM2M). 3633 Alternatively, the name of resources may be defined a priori in a way that the name by itself is 3634 indicative of its characteristic (e.g., as defined by IPSO alliance). For example, in oneM2M 3635 resource model, a smart light can be named with no restrictions, such as ‘LivingRoomLight_1” 3636 but in IPSO alliance resource model it is required to have the fixed Object name with numerical 3637 Object ID of “IPSO Light Control (3311)”. Consequently, it’s likely that in the former case the 3638 data path in URI is freely defined and in the latter case it is predetermined. 3639

• Resource hierarchy: Resources may be allowed to be organized in hierarchy where a resource 3640 contains another resource with a parent-child relationship (e.g., in oneM2M definition of 3641 resource model). Resources may also be required to have a flat structure and associate with 3642 other resources only by referencing their links. 3643

In addition to the above, different organizations use different syntax and define different features 3644 (e.g., resource interface), which preclude interoperability. 3645

C.2 OCF approach for support of multiple resource models 3646

In order to expand the IoT ecosystem the Framework takes an inclusive approach for interworking 3647 with existing resource models. Specifically, the Framework defines a resource model while 3648 providing a mechanism to easily map to other models. By embracing existing resource models 3649 OCF is inclusive of existing ecosystems while allowing for the transition toward definition of a 3650 comprehensive resource model integrating all ecosystems. 3651

The following OCF characteristics enable support of other resource models: 3652

• resource model is the superset of multiple models: the resource model is defined as the 3653 superset of existing resource models. In other words, any existing resource model can be 3654 mapped to a subset of resource model concepts. 3655

• Framework may allow for resource model negotiation: the Client and Server exchange the 3656 information about what resource model(s) each supports. Based on the exchanged information, 3657 the Client and Server choose a resource model to perform RESTful interactions or to perform 3658 translation. This feature is out of scope of the current version of this specification, however, 3659 the following is a high level description for resource model negotiation. 3660


C.3 Resource model indication 3661

The Client and server exchange the information about what resource model(s) each supports. 3662 Based on the exchanged information, the Client and Server choose a resource model to perform 3663 RESTful interactions or to perform translation. The exchange could be part of discovery and 3664 negotiation. Based on the exchange, the Client and Server follow a procedure to ensure 3665 interoperability among them. They may choose a common resource model or execute translation 3666 between resource models. 3667

• Resource model schema exchange: The Client and Server may share the resource model 3668 information when they initiate a RESTful interaction. They may exchange the information about 3669 which resource model they support as part of session establishment procedures. Alternatively, 3670 each request or response message may carry the indication of which resource model it is using. 3671 For example, [COAP] defines “Content-Format option” to indicate the “representation format” 3672 such as “application/json”. It’s possible to extend the Content-Format Option to indicate the 3673 resource model used with the representation format such as “application/ipso-json”. 3674

• Ensuing procedures: After the Client and Server exchange the resource model information, 3675 they perform a suitable procedure to ensure interoperability among them. The simplest way is 3676 to choose a resource model supported by both the Client and Server. In case there is no 3677 common resource model, the Client and Server may interact through a 3rd party. 3678

In addition to translation which can be resource intensive, a method based on profiles can be used 3679 in which an OCF implementation can accommodate multiple profiles and hence multiple 3680 ecosystems. 3681

• Resource Model Profile: the Framework defines resource model profiles and implementers or 3682 users choose the active profile. The chosen profile constraints the Device to strict rules in how 3683 resources are defined, instantiated and interacted with. This would allow for interoperation with 3684 devices from the ecosystem identified by the profile (e.g., IPSO, OneM2M etc.). Although this 3685 enables a Device to participate in and be part of any given ecosystem, this scheme does not 3686 allow for generic interoperability at runtime. While this approach may be suitable for resource 3687 constrained devices, more resource capable devices are expected to support more than one 3688 profile. 3689

C.4 An Example Profile (IPSO profile) 3690

IPSO defines smart objects that have specific resources and they take values determined by the 3691 data type of that resource. The smart object specification defines a category of such objects. Each 3692 resource represents a characteristic of the smart object being modelled. 3693

While the terms may be different, there are equivalent concepts in OCF to represent these terms. 3694 This section provides the equivalent OCF terms and then frames the IPSO smart object in OCF 3695 terms. 3696

The IPSO object Light Control defined in section 16 of the IPSO Smart Objects 1.0 is used as the 3697 reference example. 3698

C.4.1 Conceptual equivalence 3699

The IPSO smart object definition is equivalent to an Resource Type definition which defines the 3700 relevant characteristics of an entity being modelled. The specific IPSO Resource is equivalent to 3701 a Property that like an IPSO Resource has a defined data type, enumeration of acceptable values, 3702 units, a general description and access modes (based on the Interface). 3703

The general method for developing the equivalent Resource Type from an IPSO Smart Object 3704 definition is to ignore the Object ID and replace the Object URN with and OCF ‘.’ (dot) separated 3705 name that incorporates the IPSO object. Alternatively the Object URN can be used as the Resource 3706


Type ID as is (as long as the URN does not contain any ‘.’ (dots)) – using the same Object URN 3707 as the Resource Type ID allows for compatibility when interacting with an IPSO compliant device. 3708 The object URN based naming does not have any bearing for OCF to OCF interoperability and so 3709 the OCF format is preferred – for OCF to OCF interoperability only the data model consistency is 3710 required. 3711

Two models are available to render IPSO objects into OCF. 3712

1) One is where the IPSO Smart Object represents a Resource. In this case, the IP Smart Object 3713 is regarded as a resource with the Resource Type matching the description of the Smart Object. 3714 Furthermore, each resource in the IPSO definition is represented as a Property in the Resource 3715 Type (the IPSO Resource ID is replaced with a string representing the Property). This is the 3716 preferred approach when the IPSO Data Model is expressed in the Resource Model. 3717

13) The other approach is to model an IPSO Smart Object as a Collection. Each IPSO 3718 Resource is then modelled as a Resource with an Resource Type that matches the 3719 definition of the IPSO Resource. Each of these resource instances are then bound to the 3720 Collection that represents this IPSO Smart Object. 3721

3722

Below is an example showing how an IPSO LightControl Object is modelled as a Resource. 3723

Resource Type: Light Control 3724

Description: This Object is used to control a light source, such as a LED or other light. It allows a 3725 light to be turned on or off and its dimmer setting to be controlled as a percentage value between 3726 0 and 100. An optional colour setting enables a string to be used to indicate the desired colour. 3727 Table 38 and Table 39 define the Resource Type and its properties, respectively. 3728

Table 38. Light control Resource Type definition 3729

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

3730

Table 39. Light control Resource Type definition 3731


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

3732

3733


Annex D 3734

(normative) 3735

3736

Resource Type definitions 3737

D.1 List of Resource Type definitions 3738

Table 40 contains the list of defined core resources in this specification. 3739

Table 40. Alphabetized list of core resources 3740

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

Discoverable Resources, link list interface

“oic.wk.res” D.9

Icon “oic.r.icon” D.14

Introspection “oic.wk.introspection” D.15

Maintenance “oic.wk.mnt” D.6

Platform “oic.wk.p” D.7

Resource Directory “oic.wk.rd” D.13

Scenes (Top Level) “oic.wk.scenelist” D.10

Scenes Collections “oic.wk.scenecollection” D.11

Scenes Member “oic.wk.scenemember” D.12

3741

3742


D.2 OCF Collection 3743

D.2.1 Introduction 3744

OCF Collection Resource Type contains properties and links. The oic.if.baseline interface exposes 3745 a representation of the links and the properties of the collection resource itself 3746

D.2.2 Example URI 3747

/CollectionBaselineInterfaceURI 3748

D.2.3 Resource Type 3749

The resource type (rt) is defined as: oic.wk.col. 3750

D.2.4 RAML Definition 3751

#%RAML 0.8 3752

title: Collections 3753 version: 1.0 3754

traits: 3755 - interface-ll : 3756 queryParameters: 3757

if: 3758 enum: ["oic.if.ll"] 3759

- interface-b : 3760 queryParameters: 3761

if: 3762 enum: ["oic.if.b"] 3763

- interface-baseline : 3764 queryParameters: 3765

if: 3766 enum: ["oic.if.baseline"] 3767

- interface-all : 3768 queryParameters: 3769

if: 3770 enum: ["oic.if.ll", "oic.if.baseline", "oic.if.b"] 3771

3772

/CollectionBaselineInterfaceURI: 3773

description: | 3774 OCF Collection Resource Type contains properties and links. 3775 The oic.if.baseline interface exposes a representation of 3776 the links and the properties of the collection resource itself 3777 3778

is : ['interface-baseline'] 3779

get: 3780

description: | 3781 Retrieve on Baseline Interface 3782 3783

responses : 3784

200: 3785

body: 3786 application/json: 3787

schema: | 3788

{ 3789 "$schema": "http://json-schema.org/draft-04/schema#", 3790 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 3791 reserved.", 3792 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-3793 schema.json#", 3794


"title": "Collection", 3795 "definitions": { 3796 "oic.collection.setoflinks": { 3797 "description": "A set of simple or individual OIC Links.", 3798 "type": "array", 3799 "items": { 3800 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 3801 } 3802 }, 3803 "oic.collection.alllinks": { 3804 "description": "All forms of links in a collection.", 3805 "oneOf": [ 3806 { 3807 "$ref": "#/definitions/oic.collection.setoflinks" 3808 } 3809 ] 3810 }, 3811 "oic.collection": { 3812 "type": "object", 3813 "description": "A collection is a set of links along with additional 3814 properties to describe the collection itself", 3815 "properties": { 3816 "rts": { 3817 "allOf": [ 3818 { 3819 "$ref": "oic.core-3820 schema.json#/definitions/oic.core/properties/rt" 3821 }, 3822 { 3823 "description": "The list of allowable resource types (for 3824 Target and anchors) in links included in the collection" 3825 } 3826 ] 3827 }, 3828 "links": { 3829 "$ref": "#/definitions/oic.collection.alllinks" 3830 } 3831 } 3832 } 3833 }, 3834 "type": "object", 3835 "allOf": [ 3836 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 3837 {"$ref": "#/definitions/oic.collection"} 3838 ] 3839 } 3840 3841

example: | 3842

{ 3843 "rt": ["oic.wk.col"], 3844 "id": "unique_example_id", 3845 "rts": [ "oic.r.switch.binary", "oic.r.airflow" ], 3846 "links": [ 3847 { 3848 "href": "switch", 3849 "rt": ["oic.r.switch.binary"], 3850 "if": ["oic.if.a", "oic.if.baseline"], 3851 "eps": [ 3852 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 3853 {"ep": "coaps://[fe80::b1d6]:1122"}, 3854 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 3855 ] 3856 }, 3857 { 3858 "href": "airFlow", 3859 "rt": ["oic.r.airflow"], 3860 "if": ["oic.if.a", "oic.if.baseline"], 3861 "eps": [ 3862 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 3863 {"ep": "coaps://[fe80::b1d6]:1122"}, 3864


{"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 3865 ] 3866 } 3867 ] 3868 } 3869 3870

post: 3871

description: | 3872 Update on Baseline Interface 3873 3874


schema: | 3877

{ 3878 "$schema": "http://json-schema.org/draft-04/schema#", 3879 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 3880 reserved.", 3881 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-3882 schema.json#", 3883 "title": "Collection", 3884 "definitions": { 3885 "oic.collection.setoflinks": { 3886 "description": "A set of simple or individual OIC Links.", 3887 "type": "array", 3888 "items": { 3889 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 3890 } 3891 }, 3892 "oic.collection.alllinks": { 3893 "description": "All forms of links in a collection.", 3894 "oneOf": [ 3895 { 3896 "$ref": "#/definitions/oic.collection.setoflinks" 3897 } 3898 ] 3899 }, 3900 "oic.collection": { 3901 "type": "object", 3902 "description": "A collection is a set of links along with additional 3903 properties to describe the collection itself", 3904 "properties": { 3905 "rts": { 3906 "allOf": [ 3907 { 3908 "$ref": "oic.core-schema.json#/definitions/oic.core/properties/rt" 3909 }, 3910 { 3911 "description": "The list of allowable resource types (for Target 3912 and anchors) in links included in the collection" 3913 } 3914 ] 3915 }, 3916 "links": { 3917 "$ref": "#/definitions/oic.collection.alllinks" 3918 } 3919 } 3920 } 3921 }, 3922 "type": "object", 3923 "allOf": [ 3924 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 3925 {"$ref": "#/definitions/oic.collection"} 3926 ] 3927 } 3928 3929

responses : 3930

200: 3931



schema: | 3934

{ 3935 "$schema": "http://json-schema.org/draft-04/schema#", 3936 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 3937 reserved.", 3938 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-3939 schema.json#", 3940 "title": "Collection", 3941 "definitions": { 3942 "oic.collection.setoflinks": { 3943 "description": "A set of simple or individual OIC Links.", 3944 "type": "array", 3945 "items": { 3946 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 3947 } 3948 }, 3949 "oic.collection.alllinks": { 3950 "description": "All forms of links in a collection.", 3951 "oneOf": [ 3952 { 3953 "$ref": "#/definitions/oic.collection.setoflinks" 3954 } 3955 ] 3956 }, 3957 "oic.collection": { 3958 "type": "object", 3959 "description": "A collection is a set of links along with additional 3960 properties to describe the collection itself", 3961 "properties": { 3962 "rts": { 3963 "allOf": [ 3964 { 3965 "$ref": "oic.core-3966 schema.json#/definitions/oic.core/properties/rt" 3967 }, 3968 { 3969 "description": "The list of allowable resource types (for 3970 Target and anchors) in links included in the collection" 3971 } 3972 ] 3973 }, 3974 "links": { 3975 "$ref": "#/definitions/oic.collection.alllinks" 3976 } 3977 } 3978 } 3979 }, 3980 "type": "object", 3981 "allOf": [ 3982 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 3983 {"$ref": "#/definitions/oic.collection"} 3984 ] 3985 } 3986 3987

D.2.5 Property Definition 3988

Property name Value type Mandatory Access mode Description rt array: see

schema yes Read Write Resource Type

of the Resource di multiple types:

see schema Read Write

title string Read Write A title for the link relation. Can be used by the UI to


provide a context.

eps array: see schema

Read Write the Endpoint information of the target Resource

ins multiple types: see schema

Read Write The instance identifier for this web link in an array of web links - used in collections

p object: see schema

Read Write Specifies the framework policies on the Resource referenced by the target URI

href string yes Read Write This is the target URI, it can be specified as a Relative Reference or fully-qualified URI.

rel multiple types: see schema

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

type array: see schema

Read Write 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 Read Write This is used to override the context URI e.g. override the URI of the containing collection.

if array: see schema

yes Read Write The interface set supported by this resource

D.2.6 CRUDN behavior 3989

Resource Create Read Update Delete Notify /CollectionBaselineInterfaceURI get post


D.2.7 Referenced JSON schemas 3990

D.2.8 oic.oic-link-schema.json 3991

{ 3992 "$schema": "http://json-schema.org/draft-04/schema#", 3993 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 3994 reserved.", 3995 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.oic-link-schema.json#", 3996 "definitions": { 3997 "oic.oic-link": { 3998 "type": "object", 3999 "properties": { 4000 "href": { 4001 "type": "string", 4002 "maxLength": 256, 4003 "description": "This is the target URI, it can be specified as a Relative Reference or 4004 fully-qualified URI.", 4005 "format": "uri" 4006 }, 4007 "rel": { 4008 "oneOf":[ 4009 { 4010 "type": "array", 4011 "items": { 4012 "type": "string", 4013 "maxLength": 64 4014 }, 4015 "minItems": 1, 4016 "default": ["hosts"] 4017 }, 4018 { 4019 "type": "string", 4020 "maxLength": 64, 4021 "default": "hosts" 4022 } 4023 ], 4024 "description": "The relation of the target URI referenced by the link to the context URI" 4025 }, 4026 "rt": { 4027 "type": "array", 4028 "items" : { 4029 "type" : "string", 4030 "maxLength": 64 4031 }, 4032 "minItems" : 1, 4033 "description": "Resource Type of the Resource" 4034 }, 4035 "if": { 4036 "type": "array", 4037 "items": { 4038 "type" : "string", 4039 "enum" : ["oic.if.baseline", "oic.if.ll", "oic.if.b", "oic.if.rw", "oic.if.r", 4040 "oic.if.a", "oic.if.s" ] 4041 }, 4042 "minItems": 1, 4043 "description": "The interface set supported by this resource" 4044 }, 4045 "di": { 4046 "allOf": [ 4047 { 4048 "$ref": "oic.types-schema.json#/definitions/uuid" 4049 }, 4050 { 4051 "description": "The device ID" 4052 } 4053 ] 4054 }, 4055 "p": { 4056 "description": "Specifies the framework policies on the Resource referenced by the target 4057 URI", 4058


"type": "object", 4059 "properties": { 4060 "bm": { 4061 "description": "Specifies the framework policies on the Resource referenced by the 4062 target URI for e.g. observable and discoverable", 4063 "type": "integer" 4064 } 4065 }, 4066 "required" : ["bm"] 4067 }, 4068 "title": { 4069 "type": "string", 4070 "maxLength": 64, 4071 "description": "A title for the link relation. Can be used by the UI to provide a 4072 context." 4073 }, 4074 "anchor": { 4075 "type": "string", 4076 "maxLength": 256, 4077 "description": "This is used to override the context URI e.g. override the URI of the 4078 containing collection.", 4079 "format": "uri" 4080 }, 4081 "ins": { 4082 "oneOf": [ 4083 { 4084 "type": "integer", 4085 "description": "An ordinal number that is not repeated - must be unique in the 4086 collection context." 4087 }, 4088 { 4089 "type": "string", 4090 "maxLength": 256, 4091 "format" : "uri", 4092 "description": "A unique string" 4093 }, 4094 { 4095 "allOf": [ 4096 { 4097 "$ref": "oic.types-schema.json#/definitions/uuid" 4098 }, 4099 { 4100 "description": "A UUID" 4101 } 4102 ] 4103 } 4104 ], 4105 "description": "The instance identifier for this web link in an array of web links - used 4106 in collections" 4107 }, 4108 "type": { 4109 "type": "array", 4110 "description": "A hint at the representation of the resource referenced by the target 4111 URI. This represents the media types that are used for both accepting and emitting.", 4112 "items" : { 4113 "type": "string", 4114 "maxLength": 64 4115 }, 4116 "minItems": 1, 4117 "default": "application/cbor" 4118 }, 4119 "eps": { 4120 "type": "array", 4121 "description": "the Endpoint information of the target Resource", 4122 "items": { 4123 "type": "object", 4124 "properties": { 4125 "ep": { 4126 "type": "string", 4127 "format": "uri", 4128 "description": "Transport Protocol Suite + Endpoint Locator" 4129


}, 4130 "pri": { 4131 "type": "integer", 4132 "minimum": 1, 4133 "description": "The priority among multiple Endpoints" 4134 } 4135 } 4136 } 4137 } 4138 }, 4139 "required": [ "href", "rt", "if" ] 4140 } 4141 }, 4142 "type": "object", 4143 "allOf": [ 4144 { "$ref": "#/definitions/oic.oic-link" } 4145 ] 4146 } 4147 4148

D.3 Device Configuration 4149


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


/example/DeviceConfigurationResURI 4153


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


#%RAML 0.8 4157

title: OCF Configuration 4158 version: v1-20160622 4159

traits: 4160 - interface-rw : 4161 queryParameters: 4162

if: 4163 enum: ["oic.if.rw"] 4164


if: 4167 enum: ["oic.if.rw", "oic.if.baseline"] 4168

4169

/example/DeviceConfigurationResURI: 4170

description: | 4171 Resource that allows for Device specific information to be configured. 4172 4173

get: 4174

description: | 4175 Retrieves the current Device configuration settings 4176 4177

is : ['interface-all'] 4178

responses : 4179

200: 4180


schema: | 4183


{ 4184 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con-4185 schema.json#", 4186 "$schema": "http://json-schema.org/draft-04/schema#", 4187 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4188 rights reserved.", 4189 "definitions": { 4190 "oic.wk.con": { 4191 "type": "object", 4192 "properties": { 4193 "loc": { 4194 "type": "array", 4195 "description": "Location information (lat, long)", 4196 "items": { 4197 "type": "number" 4198 }, 4199 "minItems": 2, 4200 "maxItems": 2 4201 }, 4202 "locn": { 4203 "type": "string", 4204 "maxLength": 64, 4205 "description": "Human Friendly Name for location" 4206 }, 4207 "c": { 4208 "type": "string", 4209 "maxLength": 64, 4210 "description": "Currency" 4211 }, 4212 "r": { 4213 "type": "string", 4214 "maxLength": 64, 4215 "description": "Region" 4216 }, 4217 "ln": { 4218 "type": "array", 4219 "items" : 4220 { 4221 "type": "object", 4222 "properties": { 4223 "language": { 4224 "allOf": [ 4225 { 4226 "$ref": "oic.types-schema.json#/definitions/language-tag" 4227 }, 4228 { 4229 "description": "An RFC 5646 language tag." 4230 } 4231 ] 4232 }, 4233 "value": { 4234 "type": "string", 4235 "maxLength": 64, 4236 "description": "The Device name in the indicated language." 4237 } 4238 } 4239 }, 4240 "minItems" : 1, 4241 "description": "Localized names" 4242 }, 4243 "dl": { 4244 "allOf": [ 4245 { 4246 "$ref": "oic.types-schema.json#/definitions/language-tag" 4247 }, 4248 { 4249 "description": "Default Language as an RFC 5646 language tag." 4250 } 4251 ] 4252 } 4253 } 4254


} 4255 }, 4256 "type": "object", 4257 "allOf": [ 4258 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4259 { "$ref": "#/definitions/oic.wk.con" } 4260 ], 4261 "required": ["n"] 4262 } 4263 4264

example: | 4265

{ 4266 "n": "My Friendly Device Name", 4267 "rt": ["oic.wk.con"], 4268 "loc": [32.777,-96.797], 4269 "locn": "My Location Name", 4270 "c": "USD", 4271 "r": "MyRegion", 4272 "dl": "en" 4273 } 4274 4275

post: 4276

description: | 4277 Update the information about the Device 4278 4279

is : ['interface-rw'] 4280


schema: | 4283

{ 4284 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con-Update-4285 schema.json#", 4286 "$schema": "http://json-schema.org/draft-04/schema#", 4287 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 4288 reserved.", 4289 "definitions": { 4290 "oic.wk.con": { 4291 "type": "object", 4292 "properties": { 4293 "loc": { 4294 "type": "array", 4295 "description": "Location information (lat, long)", 4296 "items": { 4297 "type": "number" 4298 }, 4299 "minItems": 2, 4300 "maxItems": 2 4301 }, 4302 "locn": { 4303 "type": "string", 4304 "maxLength": 64, 4305 "description": "Human Friendly Name for location" 4306 }, 4307 "c": { 4308 "type": "string", 4309 "maxLength": 64, 4310 "description": "Currency" 4311 }, 4312 "r": { 4313 "type": "string", 4314 "maxLength": 64, 4315 "description": "Region" 4316 }, 4317 "ln": { 4318 "type": "array", 4319 "items" : 4320 { 4321


"type": "object", 4322 "properties": { 4323 "language": { 4324 "allOf": [ 4325 { 4326 "$ref": "oic.types-schema.json#/definitions/language-tag" 4327 }, 4328 { 4329 "description": "An RFC 5646 language tag." 4330 } 4331 ] 4332 }, 4333 "value": { 4334 "type": "string", 4335 "maxLength": 64, 4336 "description": "The Device name in the indicated language." 4337 } 4338 } 4339 }, 4340 "minItems" : 1, 4341 "description": "Localized names" 4342 }, 4343 "dl": { 4344 "allOf": [ 4345 { 4346 "$ref": "oic.types-schema.json#/definitions/language-tag" 4347 }, 4348 { 4349 "description": "Default Language as an RFC 5646 language tag." 4350 } 4351 ] 4352 } 4353 } 4354 } 4355 }, 4356 "type": "object", 4357 "allOf": [ 4358 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4359 { "$ref": "#/definitions/oic.wk.con" } 4360 ], 4361 "required": ["n"] 4362 } 4363 4364

example: | 4365

{ 4366 "n": "Nuevo Nombre Amistoso", 4367 "r": "MyNewRegion", 4368 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 4369 "dl": "es" 4370 } 4371 4372

responses : 4373

200: 4374


schema: | 4377

{ 4378 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con-Update-4379 schema.json#", 4380 "$schema": "http://json-schema.org/draft-04/schema#", 4381 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 4382 reserved.", 4383 "definitions": { 4384 "oic.wk.con": { 4385 "type": "object", 4386 "properties": { 4387 "loc": { 4388


"type": "array", 4389 "description": "Location information (lat, long)", 4390 "items": { 4391 "type": "number" 4392 }, 4393 "minItems": 2, 4394 "maxItems": 2 4395 }, 4396 "locn": { 4397 "type": "string", 4398 "maxLength": 64, 4399 "description": "Human Friendly Name for location" 4400 }, 4401 "c": { 4402 "type": "string", 4403 "maxLength": 64, 4404 "description": "Currency" 4405 }, 4406 "r": { 4407 "type": "string", 4408 "maxLength": 64, 4409 "description": "Region" 4410 }, 4411 "ln": { 4412 "type": "array", 4413 "items" : 4414 { 4415 "type": "object", 4416 "properties": { 4417 "language": { 4418 "allOf": [ 4419 { 4420 "$ref": "oic.types-schema.json#/definitions/language-tag" 4421 }, 4422 { 4423 "description": "An RFC 5646 language tag." 4424 } 4425 ] 4426 }, 4427 "value": { 4428 "type": "string", 4429 "maxLength": 64, 4430 "description": "The Device name in the indicated language." 4431 } 4432 } 4433 }, 4434 "minItems" : 1, 4435 "description": "Localized names" 4436 }, 4437 "dl": { 4438 "allOf": [ 4439 { 4440 "$ref": "oic.types-schema.json#/definitions/language-tag" 4441 }, 4442 { 4443 "description": "Default Language as an RFC 5646 language tag." 4444 } 4445 ] 4446 } 4447 } 4448 } 4449 }, 4450 "type": "object", 4451 "allOf": [ 4452 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4453 { "$ref": "#/definitions/oic.wk.con" } 4454 ], 4455 "required": ["n"] 4456 } 4457 4458


example: | 4459

{ 4460 "n": "Nuevo Nombre Amistoso", 4461 "r": "MyNewRegion", 4462 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 4463 "dl": "es" 4464 } 4465 4466


Property name Value type Mandatory Access mode Description loc array: see

schema Read Write Location

information (lat, long)

c string Read Write Currency ln array: see

schema Read Write Localized names

locn string Read Write Human Friendly Name for location

dl multiple types: see schema

Read Write

r string Read Write Region


Resource Create Read Update Delete Notify /example/DeviceConfigurationResURI get post

D.4 Platform Configuration 4469


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


/example/PlatformConfigurationResURI 4473


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


#%RAML 0.8 4477

title: OCF Platform Configuration 4478 version: v1-20160622 4479


if: 4483 enum: ["oic.if.rw"] 4484



4489

/example/PlatformConfigurationResURI: 4490

description: | 4491 Resource that allows for platform specific information to be configured. 4492 4493


get: 4494

description: | 4495 Retrieves the current platform configuration settings 4496 4497


responses : 4499

200: 4500


schema: | 4503

{ 4504 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con.p-4505 schema.json#", 4506 "$schema": "http://json-schema.org/draft-04/schema#", 4507 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 4508 reserved.", 4509 "definitions": { 4510 "oic.wk.con.p": { 4511 "type": "object", 4512 "properties": { 4513 "mnpn": { 4514 "type": "array", 4515 "items" : 4516 { 4517 "type": "object", 4518 "properties": { 4519 "language": { 4520 "allOf": [ 4521 { 4522 "$ref": "oic.types-schema.json#/definitions/language-tag" 4523 }, 4524 { 4525 "description": "An RFC 5646 language tag." 4526 } 4527 ] 4528 }, 4529 "value": { 4530 "type": "string", 4531 "maxLength": 64, 4532 "description": "The Platform description in the indicated 4533 language." 4534 } 4535 } 4536 }, 4537 "minItems" : 1, 4538 "description": "Platform names" 4539 } 4540 } 4541 } 4542 }, 4543 "type": "object", 4544 "allOf": [ 4545 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4546 { "$ref": "#/definitions/oic.wk.con.p" } 4547 ] 4548 } 4549 4550

example: | 4551

{ 4552 "rt": ["oic.wk.con.p"], 4553 "mnpn": [ { "language": "en", "value": "My Friendly Device Name" } ] 4554 } 4555 4556

post: 4557

description: | 4558


Update the information about the platform 4559 4560



schema: | 4564

{ 4565 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con.p-Update-4566 schema.json#", 4567 "$schema": "http://json-schema.org/draft-04/schema#", 4568 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 4569 reserved.", 4570 "definitions": { 4571 "oic.wk.con.p": { 4572 "type": "object", 4573 "properties": { 4574 "mnpn": { 4575 "type": "array", 4576 "items" : 4577 { 4578 "type": "object", 4579 "properties": { 4580 "language": { 4581 "allOf": [ 4582 { 4583 "$ref": "oic.types-schema.json#/definitions/language-tag" 4584 }, 4585 { 4586 "description": "An RFC 5646 language tag." 4587 } 4588 ] 4589 }, 4590 "value": { 4591 "type": "string", 4592 "maxLength": 64, 4593 "description": "The Platform description in the indicated language." 4594 } 4595 } 4596 }, 4597 "minItems" : 1, 4598 "description": "Platform names" 4599 } 4600 } 4601 } 4602 }, 4603 "type": "object", 4604 "allOf": [ 4605 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4606 { "$ref": "#/definitions/oic.wk.con.p" } 4607 ], 4608 "required": ["mnpn"] 4609 } 4610 4611

example: | 4612

{ 4613 "n": "Nuevo nombre", 4614 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 4615 } 4616 4617

responses : 4618

200: 4619


schema: | 4622


{ 4623 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.con.p-Update-4624 schema.json#", 4625 "$schema": "http://json-schema.org/draft-04/schema#", 4626 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 4627 reserved.", 4628 "definitions": { 4629 "oic.wk.con.p": { 4630 "type": "object", 4631 "properties": { 4632 "mnpn": { 4633 "type": "array", 4634 "items" : 4635 { 4636 "type": "object", 4637 "properties": { 4638 "language": { 4639 "allOf": [ 4640 { 4641 "$ref": "oic.types-schema.json#/definitions/language-tag" 4642 }, 4643 { 4644 "description": "An RFC 5646 language tag." 4645 } 4646 ] 4647 }, 4648 "value": { 4649 "type": "string", 4650 "maxLength": 64, 4651 "description": "The Platform description in the indicated 4652 language." 4653 } 4654 } 4655 }, 4656 "minItems" : 1, 4657 "description": "Platform names" 4658 } 4659 } 4660 } 4661 }, 4662 "type": "object", 4663 "allOf": [ 4664 { "$ref": "oic.core-schema.rw.json#/definitions/oic.core"}, 4665 { "$ref": "#/definitions/oic.wk.con.p" } 4666 ], 4667 "required": ["mnpn"] 4668 } 4669 4670

example: | 4671

{ 4672 "n": "Nuevo nombre", 4673 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 4674 } 4675 4676


Property name Value type Mandatory Access mode Description mnpn array: see

schema Read Write Platform names


Resource Create Read Update Delete Notify /example/PlatformConfigurationResURI get post


D.5 Device 4679


Known resource that is hosted by every Server. Allows for logical device specific information to be 4681 discovered. 4682

D.5.2 Wellknown URI 4683

/oic/d 4684


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


#%RAML 0.8 4688

title: OIC Root Device 4689 version: v1-20160622 4690

traits: 4691 - interface : 4692 queryParameters: 4693

if: 4694 enum: ["oic.if.r", "oic.if.baseline"] 4695

4696

/oic/d: 4697

description: | 4698 Known resource that is hosted by every Server. 4699 Allows for logical device specific information to be discovered. 4700 4701

is : ['interface'] 4702

get: 4703

description: | 4704 Retrieve the information about the Device 4705 4706

responses : 4707

200: 4708


schema: | 4711

{ 4712 "$schema": "http://json-schemas.org/draft-04/schema#", 4713 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4714 rights reserved.", 4715 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.d-4716 schema.json#", 4717 "definitions": { 4718 "oic.wk.d": { 4719 "type": "object", 4720 "properties": { 4721 "di": { 4722 "allOf": [ 4723 { 4724 "$ref": "oic.types-schema.json#/definitions/uuid" 4725 }, 4726 { 4727 "readOnly": true, 4728 "description": "Unique identifier for device" 4729 } 4730 ] 4731 }, 4732 "icv": { 4733


"type": "string", 4734 "maxLength": 64, 4735 "readOnly": true, 4736 "description": "The version of the OIC Server" 4737 }, 4738 "dmv": { 4739 "type": "string", 4740 "maxLength": 256, 4741 "readOnly": true, 4742 "description": "Spec versions of the Resource and Device Specifications to 4743 which this device data model is implemented" 4744 }, 4745 "ld": { 4746 "type": "array", 4747 "items" : 4748 { 4749 "type": "object", 4750 "properties": { 4751 "language": { 4752 "allOf": [ 4753 { 4754 "$ref": "oic.types-schema.json#/definitions/language-tag" 4755 }, 4756 { 4757 "readOnly": true, 4758 "description": "An RFC 5646 language tag." 4759 } 4760 ] 4761 }, 4762 "value": { 4763 "type": "string", 4764 "maxLength": 64, 4765 "readOnly": true, 4766 "description": "Device description in the indicated language." 4767 } 4768 } 4769 }, 4770 "minItems" : 1, 4771 "readOnly": true, 4772 "description": "Localized Descriptions." 4773 }, 4774 "sv": { 4775 "type": "string", 4776 "maxLength": 64, 4777 "readOnly": true, 4778 "description": "Software version." 4779 }, 4780 "dmn": { 4781 "type": "array", 4782 "items" : 4783 { 4784 "type": "object", 4785 "properties": { 4786 "language": { 4787 "allOf": [ 4788 { 4789 "$ref": "oic.types-schema.json#/definitions/language-tag" 4790 }, 4791 { 4792 "readOnly": true, 4793 "description": "An RFC 5646 language tag." 4794 } 4795 ] 4796 }, 4797 "value": { 4798 "type": "string", 4799 "maxLength": 64, 4800 "readOnly": true, 4801 "description": "Manufacturer name in the indicated language." 4802 } 4803 } 4804


}, 4805 "minItems" : 1, 4806 "readOnly": true, 4807 "description": "Manufacturer Name." 4808 }, 4809 "dmno": { 4810 "type": "string", 4811 "maxLength": 64, 4812 "readOnly": true, 4813 "description": "Model number as designated by manufacturer." 4814 }, 4815 "piid": { 4816 "allOf": [ 4817 { 4818 "$ref": "oic.types-schema.json#/definitions/uuid" 4819 }, 4820 { 4821 "readOnly": true, 4822 "description": "Protocol independent unique identifier for device that 4823 is immutable." 4824 } 4825 ] 4826 } 4827 } 4828 } 4829 }, 4830 "type": "object", 4831 "allOf": [ 4832 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4833 { "$ref": "#/definitions/oic.wk.d" } 4834 ], 4835 "required": [ "n", "di", "icv", "dmv", "piid" ] 4836 } 4837 4838

example: | 4839

{ 4840 "n": "Device 1", 4841 "rt": ["oic.wk.d"], 4842 "di": "54919CA5-4101-4AE4-595B-353C51AA983C", 4843 "icv": "ocf.1.0.0", 4844 "dmv": "ocf.res.1.0.0, ocf.sh.1.0.0", 4845 "piid": "6F0AAC04-2BB0-468D-B57C-16570A26AE48" 4846 } 4847 4848


Property name Value type Mandatory Access mode Description ld array: see

schema Read Only Localized

Descriptions. piid multiple types:

see schema yes Read Write

di multiple types: see schema

yes Read Write

dmno string Read Only Model number as designated by manufacturer.

sv string Read Only Software version.

dmn array: see schema

Read Only Manufacturer Name.

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


Resource Create Read Update Delete Notify /oic/d get

D.6 Maintenance 4851


The resource through which a Device is maintained and can be used for diagnostic purposes. fr 4853 (Factory Reset) is a boolean. The value 0 means No action (Default), the value 1 means Start 4854 Factory Reset After factory reset, this value shall be changed back to the default value rb (Reboot) 4855 is a boolean. The value 0 means No action (Default), the value 1 means Start Reboot After Reboot, 4856 this value shall be changed back to the default value 4857


/oic/mnt 4859


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


#%RAML 0.8 4863

title: Maintenance 4864 version: v1-20160622 4865




if: 4873 enum: ["oic.if.rw", "oic.if.r", "oic.if.baseline"] 4874

4875

/oic/mnt: 4876

description: | 4877 The resource through which a Device is maintained and can be used for diagnostic purposes. 4878 fr (Factory Reset) is a boolean. 4879 The value 0 means No action (Default), the value 1 means Start Factory Reset 4880 After factory reset, this value shall be changed back to the default value 4881 rb (Reboot) is a boolean. 4882 The value 0 means No action (Default), the value 1 means Start Reboot 4883 After Reboot, this value shall be changed back to the default value 4884 4885

get: 4886

description: | 4887 Retrieve the maintenance action status 4888 4889


responses : 4891

200: 4892



schema: | 4895

{ 4896 "$schema": "http://json-schemas.org/draft-04/schema#", 4897 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4898 rights reserved.", 4899 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.mnt-4900 schema.json#", 4901 "definitions": { 4902 "oic.wk.mnt": { 4903 "type": "object", 4904 "anyOf": [ 4905 {"required": ["fr"]}, 4906 {"required": ["rb"]} 4907 ], 4908 "properties": { 4909 "fr":{ 4910 "type": "boolean", 4911 "description": "Factory Reset" 4912 }, 4913 "rb": { 4914 "type": "boolean", 4915 "description": "Reboot Action" 4916 } 4917 } 4918 } 4919 }, 4920 "type": "object", 4921 "allOf": [ 4922 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4923 { "$ref": "#/definitions/oic.wk.mnt" } 4924 ] 4925 } 4926 4927

example: | 4928

{ 4929 "rt": ["oic.wk.mnt"], 4930 "fr": false, 4931 "rb": false 4932 } 4933 4934

post: 4935

description: | 4936 Set the maintenance action(s) 4937 4938



schema: | 4942

{ 4943 "$schema": "http://json-schemas.org/draft-04/schema#", 4944 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 4945 reserved.", 4946 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.mnt-schema.json#", 4947 "definitions": { 4948 "oic.wk.mnt": { 4949 "type": "object", 4950 "anyOf": [ 4951 {"required": ["fr"]}, 4952 {"required": ["rb"]} 4953 ], 4954 "properties": { 4955 "fr":{ 4956 "type": "boolean", 4957


"description": "Factory Reset" 4958 }, 4959 "rb": { 4960 "type": "boolean", 4961 "description": "Reboot Action" 4962 } 4963 } 4964 } 4965 }, 4966 "type": "object", 4967 "allOf": [ 4968 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 4969 { "$ref": "#/definitions/oic.wk.mnt" } 4970 ] 4971 } 4972 4973

example: | 4974

{ 4975 "fr": false, 4976 "rb": false 4977 } 4978 4979

responses : 4980

200: 4981


schema: | 4984

{ 4985 "$schema": "http://json-schemas.org/draft-04/schema#", 4986 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 4987 rights reserved.", 4988 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.mnt-4989 schema.json#", 4990 "definitions": { 4991 "oic.wk.mnt": { 4992 "type": "object", 4993 "anyOf": [ 4994 {"required": ["fr"]}, 4995 {"required": ["rb"]} 4996 ], 4997 "properties": { 4998 "fr":{ 4999 "type": "boolean", 5000 "description": "Factory Reset" 5001 }, 5002 "rb": { 5003 "type": "boolean", 5004 "description": "Reboot Action" 5005 } 5006 } 5007 } 5008 }, 5009 "type": "object", 5010 "allOf": [ 5011 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 5012 { "$ref": "#/definitions/oic.wk.mnt" } 5013 ] 5014 } 5015 5016

example: | 5017

{ 5018 "fr": false, 5019 "rb": false 5020 } 5021 5022



Property name Value type Mandatory Access mode Description fr boolean yes Read Write Factory Reset rb boolean yes Read Write Reboot Action


Resource Create Read Update Delete Notify /oic/mnt get post

D.7 Platform 5025


Known resource that is defines the platform on which an Server is hosted. Allows for platform 5027 specific information to be discovered. 5028


/oic/p 5030


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


#%RAML 0.8 5034

title: Platform 5035 version: v1-20160622 5036



5042

/oic/p: 5043

description: | 5044 Known resource that is defines the platform on which an Server is hosted. 5045 Allows for platform specific information to be discovered. 5046 5047


get: 5049

description: | 5050 Retrieve the information about the Platform 5051 5052

responses : 5053

200: 5054


schema: | 5057

{ 5058 "$schema": "http://json-schemas.org/draft-04/schema#", 5059 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5060 rights reserved.", 5061 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.p-5062 schema.json#", 5063 "definitions": { 5064 "oic.wk.p": { 5065 "type": "object", 5066 "properties": { 5067


"pi": { 5068 "allOf": [ 5069 { 5070 "$ref": "oic.types-schema.json#/definitions/uuid" 5071 }, 5072 { 5073 "readOnly": true, 5074 "description": "Platform Identifier" 5075 } 5076 ] 5077 }, 5078 "mnmn": { 5079 "type": "string", 5080 "readOnly": true, 5081 "description": "Manufacturer Name", 5082 "maxLength": 64 5083 }, 5084 "mnml": { 5085 "type": "string", 5086 "readOnly": true, 5087 "description": "Manufacturer's URL", 5088 "maxLength": 256, 5089 "format": "uri" 5090 }, 5091 "mnmo": { 5092 "type": "string", 5093 "maxLength": 64, 5094 "readOnly": true, 5095 "description": "Model number as designated by the manufacturer" 5096 }, 5097 "mndt": { 5098 "allOf": [ 5099 { 5100 "$ref": "oic.types-schema.json#/definitions/date" 5101 }, 5102 { 5103 "readOnly": true, 5104 "description": "Manufacturing Date in ISO8601 format." 5105 } 5106 ] 5107 }, 5108 "mnpv": { 5109 "type": "string", 5110 "maxLength": 64, 5111 "readOnly": true, 5112 "description": "Platform Version" 5113 }, 5114 "mnos": { 5115 "type": "string", 5116 "maxLength": 64, 5117 "readOnly": true, 5118 "description": "Platform Resident OS Version" 5119 }, 5120 "mnhw": { 5121 "type": "string", 5122 "maxLength": 64, 5123 "readOnly": true, 5124 "description": "Platform Hardware Version" 5125 }, 5126 "mnfv": { 5127 "type": "string", 5128 "maxLength": 64, 5129 "readOnly": true, 5130 "description": "Manufacturer's firmware version" 5131 }, 5132 "mnsl": { 5133 "type": "string", 5134 "readOnly": true, 5135 "description": "Manufacturer's Support Information URL", 5136 "maxLength": 256, 5137 "format": "uri" 5138


}, 5139 "st": { 5140 "type": "string", 5141 "readOnly": true, 5142 "description": "Reference time for the device in ISO8601 format.", 5143 "format": "date-time" 5144 }, 5145 "vid": { 5146 "type": "string", 5147 "maxLength": 64, 5148 "readOnly": true, 5149 "description": "Manufacturer's defined information for the platform. The 5150 content is freeform, with population rules up to the manufacturer" 5151 } 5152 } 5153 } 5154 }, 5155 "type": "object", 5156 "allOf": [ 5157 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 5158 { "$ref": "#/definitions/oic.wk.p" } 5159 ], 5160 "required": [ "pi", "mnmn" ] 5161 } 5162 5163

example: | 5164

{ 5165 "pi": "54919CA5-4101-4AE4-595B-353C51AA983C", 5166 "rt": ["oic.wk.p"], 5167 "mnmn": "Acme, Inc" 5168 } 5169 5170


Property name Value type Mandatory Access mode Description mnfv string Read Only Manufacturer's

firmware version vid string Read Only Manufacturer's

defined information for the platform. The content is freeform, with population rules up to the manufacturer

mnmn string yes Read Only Manufacturer Name

mnmo string Read Only Model number as designated by the manufacturer

mnml string Read Only Manufacturer's URL

mnos string Read Only Platform Resident OS Version

mndt multiple types: see schema

Read Write

st string Read Only Reference time for the device in ISO8601 format.


mnsl string Read Only Manufacturer's Support Information URL

mnpv string Read Only Platform Version pi multiple types:

see schema yes Read Write

mnhw string Read Only Platform Hardware Version


Resource Create Read Update Delete Notify /oic/p get

D.8 Discoverable Resources Baseline Interface 5173


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


/oic/res 5177


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


#%RAML 0.8 5181

title: Discoverable Resources 5182 version: v1-20160622 5183


if: 5187 enum: ["oic.if.ll"] 5188




if: 5195 enum: ["oic.if.ll", "oic.if.baseline"] 5196

5197

/oic-res-BaselineInterfaceURI: 5198

description: | 5199 Baseline representation of /oic/res; list of discoverable resources 5200 5201


get: 5203

description: | 5204 Retrieve the discoverable resource set, baseline interface 5205 5206

responses : 5207

200: 5208

body: 5209


application/json: 5210

schema: | 5211

{ 5212 "$schema": "http://json-schema.org/draft-v4/schema#", 5213 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5214 rights reserved.", 5215 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.res-5216 schema.json#", 5217 "definitions": { 5218 "oic.res-baseline": { 5219 "type": "object", 5220 "properties": { 5221 "rt": { 5222 "type": "array", 5223 "items" : { 5224 "type" : "string", 5225 "maxLength": 64 5226 }, 5227 "minItems" : 1, 5228 "readOnly": true, 5229 "description": "Resource Type of the Resource" 5230 }, 5231 "if": { 5232 "type": "array", 5233 "items": { 5234 "type" : "string", 5235 "enum" : ["oic.if.baseline", "oic.if.ll"] 5236 }, 5237 "minItems": 1, 5238 "readOnly": true, 5239 "description": "The interface set supported by this resource" 5240 }, 5241 "n": { 5242 "type": "string", 5243 "maxLength": 64, 5244 "readOnly": true, 5245 "description": "Human friendly name" 5246 }, 5247 "mpro": { 5248 "readOnly": true, 5249 "description": "Supported messaging protocols", 5250 "type": "string", 5251 "maxLength": 64 5252 }, 5253 "links": { 5254 "type": "array", 5255 "items": { 5256 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 5257 } 5258 } 5259 }, 5260 "required": ["rt", "if", "links"] 5261 } 5262 }, 5263 "description": "The list of resources expressed as Links", 5264 "type": "array", 5265 "items": { 5266 "$ref": "#/definitions/oic.res-baseline" 5267 } 5268 } 5269 5270

example: | 5271

[ 5272 { 5273 "rt": ["oic.wk.res"], 5274 "if": ["oic.if.baseline", "oic.if.ll" ], 5275 "links": 5276 [ 5277 { 5278


"href": "/humidity", 5279 "rt": ["oic.r.humidity"], 5280 "if": ["oic.if.s"], 5281 "p": {"bm": 3}, 5282 "eps": [ 5283 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 5284 {"ep": "coaps://[fe80::b1d6]:1122"}, 5285 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 5286 ] 5287 }, 5288 { 5289 "href": "/temperature", 5290 "rt": ["oic.r.temperature"], 5291 "if": ["oic.if.s"], 5292 "p": {"bm": 3}, 5293 "eps": [ 5294 {"ep": "coaps://[[2001:db8:a::123]:2222"} 5295 ] 5296 } 5297 ] 5298 } 5299 ] 5300 5301



schema yes Read Only Resource Type

of the Resource n string Read Only Human friendly

name links array: see

schema yes Read Write

mpro string Read Only Supported messaging protocols


yes Read Only The interface set supported by this resource


Resource Create Read Update Delete Notify /oic/res get

D.9 Discoverable Resources Link List interface 5304


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


/oic/res 5308




#%RAML 0.8 5312




if: 5318 enum: ["oic.if.ll"] 5319




if: 5326 enum: ["oic.if.ll", "oic.if.baseline"] 5327

5328

/oic-res-llInterfaceURI: 5329

description: | 5330 Link list representation of /oic/res; list of discoverable resources 5331 5332

is : ['interface-ll'] 5333

get: 5334

description: | 5335 Retrieve the discoverable resource set, link list interface 5336 5337

responses : 5338

200: 5339


schema: | 5342

{ 5343 "$schema": "http://json-schema.org/draft-v4/schema#", 5344 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5345 rights reserved.", 5346 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.res-schema-5347 ll.json#", 5348 "description": "The list of resources expressed as OCF links without di", 5349 "definitions": { 5350 "oic.res-ll": { 5351 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 5352 } 5353 }, 5354 "type": "array", 5355 "items": { 5356 "$ref": "#/definitions/oic.res-ll" 5357 } 5358 } 5359 5360

example: | 5361

[ 5362 { 5363 "href": "/humidity", 5364 "rt": ["oic.r.humidity"], 5365 "if": ["oic.if.s"], 5366 "p": {"bm": 3}, 5367 "eps": [ 5368 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 5369 {"ep": "coaps://[fe80::b1d6]:1122"}, 5370 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 5371 ] 5372 }, 5373 { 5374 "href": "/temperature", 5375 "rt": ["oic.r.temperature"], 5376 "if": ["oic.if.s"], 5377 "p": {"bm": 3}, 5378


"eps": [ 5379 {"ep": "coaps://[[2001:db8:a::123]:2222"} 5380 ] 5381 } 5382 ] 5383 5384




of the Resource di multiple types:


title string Read Write A title for the link relation. Can be used by the UI to provide a context.


Read Write the Endpoint information of the target Resource





href string yes Read Write This is the target URI, it can be specified as a Relative Reference or fully-qualified URI.




Read Write 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 Read Write This is used to override the context URI e.g. override the URI of the containing collection.





D.9.7 Referenced JSON schemas 5387

D.9.8 oic.oic-link-schema.json 5388

{ 5389 "$schema": "http://json-schema.org/draft-04/schema#", 5390 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 5391 reserved.", 5392 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.oic-link-schema.json#", 5393 "definitions": { 5394 "oic.oic-link": { 5395 "type": "object", 5396 "properties": { 5397 "href": { 5398 "type": "string", 5399 "maxLength": 256, 5400 "description": "This is the target URI, it can be specified as a Relative Reference or 5401 fully-qualified URI.", 5402 "format": "uri" 5403 }, 5404 "rel": { 5405 "oneOf":[ 5406 { 5407 "type": "array", 5408 "items": { 5409 "type": "string", 5410 "maxLength": 64 5411 }, 5412 "minItems": 1, 5413 "default": ["hosts"] 5414 }, 5415 { 5416 "type": "string", 5417 "maxLength": 64, 5418 "default": "hosts" 5419 } 5420 ], 5421 "description": "The relation of the target URI referenced by the link to the context URI" 5422 }, 5423 "rt": { 5424 "type": "array", 5425 "items" : { 5426 "type" : "string", 5427 "maxLength": 64 5428 }, 5429 "minItems" : 1, 5430 "description": "Resource Type of the Resource" 5431 }, 5432 "if": { 5433 "type": "array", 5434 "items": { 5435 "type" : "string", 5436 "enum" : ["oic.if.baseline", "oic.if.ll", "oic.if.b", "oic.if.rw", "oic.if.r", 5437 "oic.if.a", "oic.if.s" ] 5438


}, 5439 "minItems": 1, 5440 "description": "The interface set supported by this resource" 5441 }, 5442 "di": { 5443 "allOf": [ 5444 { 5445 "$ref": "oic.types-schema.json#/definitions/uuid" 5446 }, 5447 { 5448 "description": "The device ID" 5449 } 5450 ] 5451 }, 5452 "p": { 5453 "description": "Specifies the framework policies on the Resource referenced by the target 5454 URI", 5455 "type": "object", 5456 "properties": { 5457 "bm": { 5458 "description": "Specifies the framework policies on the Resource referenced by the 5459 target URI for e.g. observable and discoverable", 5460 "type": "integer" 5461 } 5462 }, 5463 "required" : ["bm"] 5464 }, 5465 "title": { 5466 "type": "string", 5467 "maxLength": 64, 5468 "description": "A title for the link relation. Can be used by the UI to provide a 5469 context." 5470 }, 5471 "anchor": { 5472 "type": "string", 5473 "maxLength": 256, 5474 "description": "This is used to override the context URI e.g. override the URI of the 5475 containing collection.", 5476 "format": "uri" 5477 }, 5478 "ins": { 5479 "oneOf": [ 5480 { 5481 "type": "integer", 5482 "description": "An ordinal number that is not repeated - must be unique in the 5483 collection context." 5484 }, 5485 { 5486 "type": "string", 5487 "maxLength": 256, 5488 "format" : "uri", 5489 "description": "A unique string" 5490 }, 5491 { 5492 "allOf": [ 5493 { 5494 "$ref": "oic.types-schema.json#/definitions/uuid" 5495 }, 5496 { 5497 "description": "A UUID" 5498 } 5499 ] 5500 } 5501 ], 5502 "description": "The instance identifier for this web link in an array of web links - used 5503 in collections" 5504 }, 5505 "type": { 5506 "type": "array", 5507 "description": "A hint at the representation of the resource referenced by the target 5508 URI. This represents the media types that are used for both accepting and emitting.", 5509


"items" : { 5510 "type": "string", 5511 "maxLength": 64 5512 }, 5513 "minItems": 1, 5514 "default": "application/cbor" 5515 }, 5516 "eps": { 5517 "type": "array", 5518 "description": "the Endpoint information of the target Resource", 5519 "items": { 5520 "type": "object", 5521 "properties": { 5522 "ep": { 5523 "type": "string", 5524 "format": "uri", 5525 "description": "Transport Protocol Suite + Endpoint Locator" 5526 }, 5527 "pri": { 5528 "type": "integer", 5529 "minimum": 1, 5530 "description": "The priority among multiple Endpoints" 5531 } 5532 } 5533 } 5534 } 5535 }, 5536 "required": [ "href", "rt", "if" ] 5537 } 5538 }, 5539 "type": "object", 5540 "allOf": [ 5541 { "$ref": "#/definitions/oic.oic-link" } 5542 ] 5543 } 5544 5545

D.10 Scenes (Top level) 5546


Toplevel Scene resource. This resource is a generic collection resource. The rts value shall contain 5548 oic.wk.scenecollection resource types. 5549


/SceneListResURI 5551


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


#%RAML 0.8 5555

title: Scene 5556 version: v1-20160622 5557


if: 5561 enum: ["oic.if.a", "oic.if.ll", "oic.if.baseline"] 5562

5563

/SceneListResURI: 5564

description: | 5565 Toplevel Scene resource. 5566 This resource is a generic collection resource. 5567


The rts value shall contain oic.wk.scenecollection resource types. 5568 5569

get: 5570

description: | 5571 Provides the current list of web links pointing to scenes 5572 5573

responses : 5574

200: 5575


schema: | 5578

{ 5579 "$schema": "http://json-schema.org/draft-04/schema#", 5580 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 5581 reserved.", 5582 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-5583 schema.json#", 5584 "title": "Collection", 5585 "definitions": { 5586 "oic.collection.setoflinks": { 5587 "description": "A set of simple or individual OIC Links.", 5588 "type": "array", 5589 "items": { 5590 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 5591 } 5592 }, 5593 "oic.collection.alllinks": { 5594 "description": "All forms of links in a collection.", 5595 "oneOf": [ 5596 { 5597 "$ref": "#/definitions/oic.collection.setoflinks" 5598 } 5599 ] 5600 }, 5601 "oic.collection": { 5602 "type": "object", 5603 "description": "A collection is a set of links along with additional 5604 properties to describe the collection itself", 5605 "properties": { 5606 "rts": { 5607 "allOf": [ 5608 { 5609 "$ref": "oic.core-5610 schema.json#/definitions/oic.core/properties/rt" 5611 }, 5612 { 5613 "description": "The list of allowable resource types (for 5614 Target and anchors) in links included in the collection" 5615 } 5616 ] 5617 }, 5618 "links": { 5619 "$ref": "#/definitions/oic.collection.alllinks" 5620 } 5621 } 5622 } 5623 }, 5624 "type": "object", 5625 "allOf": [ 5626 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 5627 {"$ref": "#/definitions/oic.collection"} 5628 ] 5629 } 5630 5631

example: | 5632


{ 5633 "rt": ["oic.wk.scenelist"], 5634 "n": "list of scene Collections", 5635 "rts": ["oic.wk.scenecollection"], 5636 "links": [ 5637 ] 5638 } 5639 5640


Property name Value type Mandatory Access mode Description links multiple types:


rts multiple types: see schema

Read Write


Resource Create Read Update Delete Notify /SceneListResURI get

D.11 Scene Collections 5643


Collection that models a set of Scenes. This resource is a generic collection resource with 5645 additional parameters. The rts value shall contain oic.scenemember resource types. The additional 5646 parameters are lastScene, this is the scene value last set by any OCF Client sceneValues, this 5647 is the list of available scenes lastScene shall be listed in sceneValues. 5648


/SceneCollectionResURI 5650


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


#%RAML 0.8 5654




5662

/SceneCollectionResURI: 5663

description: | 5664 Collection that models a set of Scenes. 5665 This resource is a generic collection resource with additional parameters. 5666 The rts value shall contain oic.scenemember resource types. 5667 The additional parameters are 5668 lastScene, this is the scene value last set by any OCF Client 5669 sceneValues, this is the list of available scenes 5670 lastScene shall be listed in sceneValues. 5671 5672

get: 5673

description: | 5674 Provides the current list of web links pointing to scenes 5675 5676

responses : 5677


200: 5678


schema: | 5681

{ 5682 "$schema": "http://json-schema.org/draft-04/schema#", 5683 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5684 rights reserved.", 5685 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneCollection-5686 schema.json#", 5687 "title" : "Scene Collection", 5688 "definitions": { 5689 "oic.sceneCollection": { 5690 "type": "object", 5691 "allOf": [ 5692 { 5693 "$ref": "oic.collection-schema.json#/definitions/oic.collection" 5694 }, 5695 { 5696 "properties": { 5697 "lastScene": { 5698 "type": "string", 5699 "description": "Last selected Scene from the set of sceneValues" 5700 }, 5701 "sceneValues": { 5702 "type": "array", 5703 "readOnly": true, 5704 "description": "All available scene values", 5705 "items": { 5706 "type": "string" 5707 } 5708 } 5709 } 5710 } 5711 ], 5712 "required": [ "lastScene","sceneValues","rts","id" ] 5713 } 5714 }, 5715 "type": "object", 5716 "allOf" : [ 5717 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 5718 { "$ref": "#/definitions/oic.sceneCollection" } 5719 ] 5720 } 5721 5722

example: | 5723

{ 5724 "lastScene": "off", 5725 "sceneValues": ["off","Reading","TVWatching"], 5726 "rt": ["oic.wk.scenecollection"], 5727 "n": "My Scenes for my living room", 5728 "id": "0685B960-736F-46F7-BEC0-9E6CBD671ADC1", 5729 "rts": ["oic.wk.scenemember"], 5730 "links": [ 5731 ] 5732 } 5733 5734

post: 5735

description: | 5736 Provides the action to change the last set scene selection. 5737 Calling this method shall update all scene members to the prescribed membervalue. 5738 When this method is called with the same value as the current lastScene value 5739 then all scene members shall be updated. 5740 5741



schema: | 5744

{ 5745 "$schema": "http://json-schema.org/draft-04/schema#", 5746 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All rights 5747 reserved.", 5748 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneCollection-5749 Update-schema.json#", 5750 "title" : "Scene Collection", 5751 "definitions": { 5752 "oic.sceneCollection-Update": { 5753 "type": "object", 5754 "allOf": [ 5755 { 5756 "$ref": "oic.collection-schema.json#/definitions/oic.collection" 5757 }, 5758 { 5759 "properties": { 5760 "lastScene": { 5761 "type": "string", 5762 "description": "Last selected Scene from the set of sceneValues" 5763 } 5764 } 5765 } 5766 ], 5767 "required": [ "lastScene" ] 5768 } 5769 }, 5770 "type": "object", 5771 "allOf" : [ 5772 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 5773 { "$ref": "#/definitions/oic.sceneCollection-Update" } 5774 ] 5775 } 5776 5777

example: | 5778

{ 5779 "lastScene": "Reading" 5780 } 5781 5782

responses : 5783

200: 5784

description: | 5785 Indicates that the value is changed. 5786 The changed properties are provided in the response. 5787 5788


schema: | 5791

{ 5792 "$schema": "http://json-schema.org/draft-04/schema#", 5793 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5794 rights reserved.", 5795 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneCollection-5796 Update-schema.json#", 5797 "title" : "Scene Collection", 5798 "definitions": { 5799 "oic.sceneCollection-Update": { 5800 "type": "object", 5801 "allOf": [ 5802 { 5803 "$ref": "oic.collection-schema.json#/definitions/oic.collection" 5804 }, 5805 { 5806 "properties": { 5807 "lastScene": { 5808 "type": "string", 5809


"description": "Last selected Scene from the set of sceneValues" 5810 } 5811 } 5812 } 5813 ], 5814 "required": [ "lastScene" ] 5815 } 5816 }, 5817 "type": "object", 5818 "allOf" : [ 5819 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 5820 { "$ref": "#/definitions/oic.sceneCollection-Update" } 5821 ] 5822 } 5823 5824

example: | 5825

{ 5826 "lastScene": "Reading" 5827 } 5828 5829


Property name Value type Mandatory Access mode Description lastScene string yes Read Write Last selected

Scene from the set of sceneValues

sceneValues array: see schema

yes Read Only All available scene values


Resource Create Read Update Delete Notify /SceneCollectionResURI get post

D.12 Scene Member 5832


Collection that models a scene member. 5834


/SceneMemberResURI 5836


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


#%RAML 0.8 5840




5848

/SceneMemberResURI: 5849

description: | 5850 Collection that models a scene member. 5851 5852


get: 5853

description: | 5854 Provides the scene member 5855 5856

responses : 5857

200: 5858


schema: | 5861

{ 5862 "$schema": "http://json-schema.org/draft-04/schema#", 5863 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 5864 rights reserved.", 5865 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.sceneMember-5866 schema.json#", 5867 "title" : "Scene Member", 5868 "definitions": { 5869 "oic.sceneMember": { 5870 "type": "object", 5871 "properties": { 5872 "SceneMappings" : { 5873 "type": "array", 5874 "description": "array of mappings per scene, can be one(1)", 5875 "items": { 5876 "type": "object", 5877 "properties": { 5878 "scene": { 5879 "type": "string", 5880 "description": "Specifies a scene value that will be acted upon" 5881 }, 5882 "memberProperty": { 5883 "type": "string", 5884 "readOnly": true, 5885 "description": "property name that will be mapped" 5886 }, 5887 "memberValue": { 5888 "type": "string", 5889 "readOnly": true, 5890 "description": "value of the Member Property" 5891 } 5892 }, 5893 "required": [ "scene", "memberProperty", "memberValue" ] 5894 } 5895 }, 5896 "link": { 5897 "allOf": [ 5898 { 5899 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 5900 }, 5901 { 5902 "description": "OCF link that points to a resource" 5903 } 5904 ] 5905 } 5906 }, 5907 "required": [ "link" ] 5908 } 5909 }, 5910 5911 "type": "object", 5912 "allOf" : [ 5913 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 5914 { "$ref": "#/definitions/oic.sceneMember" } 5915 ] 5916 } 5917 5918

example: | 5919


{ 5920 "rt": ["oic.wk.scenemember"], 5921 "id": "0685B960-FFFF-46F7-BEC0-9E6234671ADC1", 5922 "n": "my binary switch (for light bulb) mappings", 5923 "link": { 5924 "href": "binarySwitch", 5925 "rt": ["oic.r.switch.binary"], 5926 "if": ["oic.if.a", "oic.if.baseline"], 5927 "eps": [ 5928 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 5929 {"ep": "coaps://[fe80::b1d6]:1122"}, 5930 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 5931 ] 5932 }, 5933 "sceneMappings": [ 5934 { 5935 "scene": "off", 5936 "memberProperty": "value", 5937 "memberValue": true 5938 }, 5939 { 5940 "scene": "Reading", 5941 "memberProperty": "value", 5942 "memberValue": false 5943 }, 5944 { 5945 "scene": "TVWatching", 5946 "memberProperty": "value", 5947 "memberValue": true 5948 } 5949 ] 5950 } 5951 5952


Property name Value type Mandatory Access mode Description SceneMappings array: see

schema Read Write array of

mappings per scene, can be one(1)

link multiple types: see schema

yes Read Write


Resource Create Read Update Delete Notify /SceneMemberResURI get

D.13 Resource directory resource 5955


Resource to be exposed by any Device that can act as a Resource Directory. 1) Provides selector 5957 criteria (e.g., integer) with GET request 2) Publish or Update a Link in /oic/res with POST request 5958 3) Delete a Link in /oic/res with DELETE request 5959


/oic/rd 5961


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


#%RAML 0.8 5965

title: Resource Directory 5966


version: v1-20160622 5967

traits: 5968 - rddelete-di : 5969 queryParameters: 5970

di: 5971 description: This is used to determine which set of links to operata on. (Need 5972 authentication to ensure that there is no spoofing). If instance is ommitted then the entire set of 5973 links from this device ID is deleted 5974 Example: DELETE /oic/rd?di="0685B960-736F-46F7-BEC0-9E6CBD671ADC1" 5975 5976

- rddelete-ins : 5977 queryParameters: 5978

ins: 5979 description: Instance of the link to delete 5980 Value of parameter is a string where instance to be deleted are comma separated 5981 Example: DELETE /oic/rd?di="0685B960-736F-46F7-BEC0-9E6CBD671ADC1";ins="20" 5982 5983

- rdgetinterface : 5984 queryParameters: 5985

if: 5986 enum: ["oic.if.baseline"] 5987 description: Interface is optional since there is only one interface supported for the 5988 Resource Type 5989 Both for RD selection and for publish. 5990 Example: GET /oic/rd?if=oic.if.baseline 5991 5992

- rdpostinterface : 5993 queryParameters: 5994

if: 5995 enum: ["oic.if.baseline"] 5996 description: Interface is optional since there is only one interface supported for the 5997 Resource Type 5998 Both for RD selection and for publish. 5999 Example: POST /oic/rd?if=oic.if.baseline 6000 6001

6002

/oic/rd: 6003

description: | 6004 Resource to be exposed by any Device that can act as a Resource Directory. 6005 1) Provides selector criteria (e.g., integer) with GET request 6006 2) Publish or Update a Link in /oic/res with POST request 6007 3) Delete a Link in /oic/res with DELETE request 6008 6009

get: 6010

description: | 6011 Get the attributes of the Resource Directory for selection purposes. 6012 6013

is : ['rdgetinterface'] 6014

responses : 6015

200: 6016

description: | 6017 Respond with the selector criteria - either the set of attributes or the bias factor 6018 6019


schema: | 6022

{ 6023 "$schema": "http://json-schema.org/draft-04/schema#", 6024 "description" : "Copyright (c) 2016, 2017 Open Connectivity Foundation, Inc. All 6025 rights reserved.", 6026


"id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.rd.selection-6027 schema.json#", 6028 "title" : "RD Selection", 6029 "definitions": { 6030 "oic.rd.attributes": { 6031 "type": "object", 6032 "properties": { 6033 "sel": { 6034 "type": "integer", 6035 "minimum": 0, 6036 "maximum": 100, 6037 "description": "A bias factor calculated by the Resource directory" 6038 } 6039 }, 6040 "required": ["sel"] 6041 } 6042 }, 6043 "type": "object", 6044 "allOf": [ 6045 { "$ref": "oic.core-schema.json#/definitions/oic.core" }, 6046 { "$ref": "#/definitions/oic.rd.attributes" } 6047 ] 6048 } 6049 6050

example: | 6051

{ 6052 "rt": ["oic.wk.rd"], 6053 "if": ["oic.if.baseline"], 6054 "sel": 50 6055 } 6056 6057

post: 6058

description: | 6059 Publish the resource information for the first time or Update the existing one in /oic/res. 6060 Appropriates parts of the information, i.e., Links of the published Resources will be 6061 discovered through /oic/res. 6062 1) When a Device first publishes a Link, the request payload to RD may include the Links 6063 without "ins" Parameter. 6064 2) Upon granting the request, the RD assigns a unique instance value identifying the Link 6065 among all the Links it advertises 6066 and sends back the instance value in "ins" Parameter in the Link to the publishing Device. 6067 3) When later the publishing Device updates the existing Link, i.e., changing its Endpoint 6068 information, 6069 the request payload to RD needs to include the instance value in "ins" Parameter to 6070 identify the Link to update. 6071 6072

is : ['rdpostinterface'] 6073


schema: | 6076

{ 6077 "$schema": "http://json-schema.org/draft-04/schema#", 6078 "description": "Copyright (c) 2016,2017 Open Connectivity Foundation, Inc. All rights 6079 reserved.", 6080 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.rd.publish-6081 schema.json#", 6082 "title": "RD Publish & Update", 6083 "definitions": { 6084 "oic.rd.publish": { 6085 "description": "Publishes resources as OIC Links into the resource directory", 6086 "properties": { 6087 "di": { 6088 "allOf": [ 6089 { 6090 "$ref": "oic.types-schema.json#/definitions/uuid" 6091 }, 6092 { 6093


"description": "A UUID that is the identifier for the publishing Device" 6094 } 6095 ] 6096 }, 6097 "links": { 6098 "$ref": "oic.collection-schema.json#/definitions/oic.collection.setoflinks" 6099 }, 6100 "ttl": { 6101 "type": "integer", 6102 "description": "Time to indicate a RD, i.e. how long to keep this published 6103 item." 6104 } 6105 } 6106 } 6107 }, 6108 "type": "object", 6109 "allOf": [ 6110 { 6111 "$ref": "oic.core-schema.json#/definitions/oic.core" 6112 }, 6113 { 6114 "$ref": "#/definitions/oic.rd.publish" 6115 } 6116 ], 6117 "required": [ 6118 "di", 6119 "links", 6120 "ttl" 6121 ] 6122 } 6123 6124

example: | 6125

{ 6126 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6127 "links": [ 6128 { 6129 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6130 "href": "/myLightSwitch", 6131 "rt": ["oic.r.switch.binary"], 6132 "if": ["oic.if.a", "oic.if.baseline"], 6133 "p": {"bm": 3}, 6134 "eps": [ 6135 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 6136 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 6137 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 6138 ] 6139 }, 6140 { 6141 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6142 "href": "/myLightBrightness", 6143 "rt": ["oic.r.brightness"], 6144 "if": ["oic.if.a", "oic.if.baseline"], 6145 "p": {"bm": 3}, 6146 "eps": [ 6147 {"ep": "coaps://[[2001:db8:a::123]:2222"} 6148 ] 6149 } 6150 ], 6151 "ttl": 600 6152 } 6153 6154

responses : 6155

200: 6156

description: | 6157 Respond with the same schema as publish but, when a Link is first published, 6158 with the additional "ins" Parameter in the Link. 6159 This value is used by the receiver to manage that OCF Link instance. 6160 6161



schema: | 6164

{ 6165 "$schema": "http://json-schema.org/draft-04/schema#", 6166 "description": "Copyright (c) 2016,2017 Open Connectivity Foundation, Inc. All 6167 rights reserved.", 6168 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.rd.publish-6169 schema.json#", 6170 "title": "RD Publish & Update", 6171 "definitions": { 6172 "oic.rd.publish": { 6173 "description": "Publishes resources as OIC Links into the resource directory", 6174 "properties": { 6175 "di": { 6176 "allOf": [ 6177 { 6178 "$ref": "oic.types-schema.json#/definitions/uuid" 6179 }, 6180 { 6181 "description": "A UUID that is the identifier for the publishing 6182 Device" 6183 } 6184 ] 6185 }, 6186 "links": { 6187 "$ref": "oic.collection-schema.json#/definitions/oic.collection.setoflinks" 6188 }, 6189 "ttl": { 6190 "type": "integer", 6191 "description": "Time to indicate a RD, i.e. how long to keep this published 6192 item." 6193 } 6194 } 6195 } 6196 }, 6197 "type": "object", 6198 "allOf": [ 6199 { 6200 "$ref": "oic.core-schema.json#/definitions/oic.core" 6201 }, 6202 { 6203 "$ref": "#/definitions/oic.rd.publish" 6204 } 6205 ], 6206 "required": [ 6207 "di", 6208 "links", 6209 "ttl" 6210 ] 6211 } 6212 6213

example: | 6214

{ 6215 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6216 "links": [ 6217 { 6218 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6219 "href": "/myLightSwitch", 6220 "rt": ["oic.r.switch.binary"], 6221 "if": ["oic.if.a", "oic.if.baseline"], 6222 "p": {"bm": 3}, 6223 "eps": [ 6224 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 6225 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 6226 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 6227 ], 6228 "ins": "11235" 6229 }, 6230


{ 6231 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 6232 "href": "/myLightBrightness", 6233 "rt": ["oic.r.brightness"], 6234 "if": ["oic.if.a", "oic.if.baseline"], 6235 "p": {"bm": 3}, 6236 "eps": [ 6237 {"ep": "coaps://[2001:db8:a::123]:2222"} 6238 ], 6239 "ins": "112358" 6240 } 6241 ], 6242 "ttl": 600 6243 } 6244 6245

delete: 6246

description: | 6247 Delete a particular OIC Link - the link may be a simple link or a link in a tagged set. 6248 6249

is : ['rddelete-di','rddelete-ins'] 6250

responses : 6251

200: 6252

description: | 6253 The delete succeeded 6254 6255


Property name Value type Mandatory Access mode Description sel integer yes Read Write A bias factor

calculated by the Resource directory


Resource Create Read Update Delete Notify /oic/rd get post delete

D.14 Icon 6258


This resource describes the attributes associated with an Icon. 6260


/IconResURI 6262


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


#%RAML 0.8 6266

title: OICIcon 6267 version: v1.1.0-20161107 6268



6274


/IconResURI: 6275

description: | 6276 This resource describes the attributes associated with an Icon. 6277 6278


get: 6280

description: | 6281 Retrieves the current icon properties. 6282 6283

responses : 6284

200: 6285


schema: | 6288

{ 6289 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.r.icon.json#", 6290 "$schema": "http://json-schema.org/draft-04/schema#", 6291 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 6292 reserved.", 6293 "title": "Icon", 6294 "definitions": { 6295 "oic.r.icon": { 6296 "properties": { 6297 "mimetype": { 6298 "type": "string", 6299 "maxLength": 64, 6300 "readOnly": true, 6301 "description": "The format of the MIME Type" 6302 }, 6303 "width": { 6304 "type": "integer", 6305 "minimum": 1, 6306 "readOnly": true, 6307 "description": "The width in pixels" 6308 }, 6309 "height": { 6310 "type": "integer", 6311 "minimum": 1, 6312 "readOnly": true, 6313 "description": "The height in pixels" 6314 }, 6315 "media": { 6316 "type": "string", 6317 "maxLength": 256, 6318 "format" : "uri", 6319 "readOnly": true, 6320 "description": "Specifies the URI to the icon" 6321 } 6322 } 6323 } 6324 }, 6325 "type": "object", 6326 "allOf": [ 6327 { "$ref": "oic.core-schema.json#/definitions/oic.core"}, 6328 { "$ref": "#/definitions/oic.r.icon"} 6329 ], 6330 "required": ["mimetype","width","height","media"] 6331 } 6332 6333

example: | 6334

{ 6335 "rt": ["oic.r.icon"], 6336 "id": "unique_example_id", 6337 "mimetype": "image/png", 6338 "width": 256, 6339


"height": 256, 6340 "media": "http://findbetter.ru/public/uploads/1481662800/2043.png" 6341 } 6342 6343


Property name Value type Mandatory Access mode Description mimetype string yes Read Only The format of the

MIME Type width integer yes Read Only The width in

pixels media string yes Read Only Specifies the URI

to the icon height integer yes Read Only The height in

pixels


Resource Create Read Update Delete Notify /IconResURI get

D.15 Introspection Resource 6346


This resource provides the means to get the device introspection data specifiying all the endpoints 6348 of the device. The url hosted by this resource is either a local or an external url. 6349


/IntrospectionResURI 6351


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


#%RAML 0.8 6355

title: OICIntrospection 6356 version: v1.0.0-20160707 6357



6363

/IntrospectionResURI: 6364

description: | 6365 This resource provides the means to get the device introspection data specifiying all the 6366 endpoints of the device. 6367 The url hosted by this resource is either a local or an external url. 6368 6369


get: 6371 responses : 6372

200: 6373


schema: | 6376


{ 6377 "id": "http://www.openconnectivity.org/ocf-6378 apis/core/schemas/oic.wk.introspectionInfo.json#", 6379 "$schema": "http://json-schema.org/draft-04/schema#", 6380 "description" : "Copyright (c) 2017 Open Interconnect Consortium, Inc. All rights 6381 reserved.", 6382 "title": "introspection resource", 6383 "definitions": { 6384 "oic.wk.introspectionInfo": { 6385 "type": "object", 6386 "properties": { 6387 "urlInfo": { 6388 "type": "array", 6389 "description": "Information on the location of the introspection data.", 6390 "readOnly": true, 6391 "minItems": 1, 6392 "items": { 6393 "type" : "object", 6394 "properties": { 6395 "url": { 6396 "type": "string", 6397 "format": "uri", 6398 "description" : "The URL of the introspection information." 6399 }, 6400 "protocol": { 6401 "type": "string", 6402 "enum": [ "coap", "coaps", "http", "https", "coap+tcp", 6403 "coaps+tcp" ], 6404 "description" : "Identifier for the protocol to be used to obtain the 6405 introspection information" 6406 }, 6407 "content-type": { 6408 "type": "string", 6409 "enum": [ "application/json", "application/cbor" ], 6410 "default" : "application/cbor", 6411 "description" : "content-type of the introspection data" 6412 }, 6413 "version": { 6414 "type": "integer", 6415 "enum": [ 1 ], 6416 "default" : 1, 6417 "description" : "The version of the introspection data that can be 6418 downloaded" 6419 } 6420 }, 6421 "required" : [ "url","protocol"] 6422 } 6423 } 6424 }, 6425 "required" : ["urlInfo"] 6426 } 6427 }, 6428 "type": "object", 6429 "allOf": [ 6430 {"$ref": "#/definitions/oic.wk.introspectionInfo"}, 6431 {"$ref": "oic.core-schema.json#/definitions/oic.core"} 6432 ] 6433 } 6434 6435

example: | 6436

{ 6437 "rt" : ["oic.wk.introspection"], 6438 "urlInfo" : [ 6439 { 6440 "content-type" : "application/cbor", 6441 "protocol" : "coap", 6442 "url" : "coap://[fe80::1]:1234/IntrospectionExampleURI" 6443 } 6444 ] 6445


} 6446 6447


Property name Value type Mandatory Access mode Description urlInfo array: see

schema yes Read Only Information on

the location of the introspection data.


Resource Create Read Update Delete Notify /IntrospectionResURI get

6450


Annex E 6451

(normative) 6452

6453

OIC 1.1 Resource Type definitions 6454

E.1 List of Resource Type Definitions 6455

Table 41 contains the list of OIC 1.1 defined core resources that are referenced in this specification 6456 and so included herein to enable backwards compatibility. These definitions are only to be used 6457 when communicating with OIC 1.1 Devices where specifically referenced in this specification. 6458

Table 41. Alphabetized list of referenced OIC 1.1 core resources 6459

Friendly Name (informative)

Resource Type (rt) Section

Collection, baseline Interface

“oic.wk.col” E.2

Collection, link list interface

“oic.wk.col” E.3

Discoverable Resources, baseline interface

“oic.wk.res” E.4

Discoverable Resources, link list interface

“oic.wk.res” E.5

Link N/A E.2.8

6460

E.2 Collection, baseline interface 6461

E.2.1 Introduction 6462

OCF Collection Resource Type contains properties and links. The oic.if.baseline interface exposes 6463 a representation of the links and the properties of the collection resource itself 6464

E.2.2 Example URI 6465


E.2.3 Resource Type 6467


E.2.4 RAML Definition 6469

#%RAML 0.8 6470




if: 6476 enum: ["oic.if.ll"] 6477


if: 6480 enum: ["oic.if.b"] 6481



6486

/CollectionBaselineInterfaceURI: 6487

description: | 6488 OCF Collection Resource Type contains properties and links. 6489 The oic.if.baseline interface exposes a representation of 6490 the links and the properties of the collection resource itself 6491 6492


get: 6494

description: | 6495 Retrieve on Baseline Interface 6496 6497

responses : 6498

200: 6499


schema: | 6502

{ 6503 "$schema": "http://json-schema.org/draft-04/schema#", 6504 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 6505 reserved.", 6506 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-6507 schema.json#", 6508 "title": "Collection", 6509 "definitions": { 6510 "oic.collection.setoflinks": { 6511 "description": "A set (array) of simple or individual OIC Links. In 6512 addition to properties required for an OIC Link, the identifier for that link in this set is also 6513 required", 6514 "type": "array", 6515 "items": { 6516 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 6517 } 6518 }, 6519 "oic.collection.alllinks": { 6520 "description": "All forms of links in a collection", 6521 "oneOf": [ 6522 { 6523 "$ref": "#/definitions/oic.collection.setoflinks" 6524 } 6525 ] 6526 }, 6527 "oic.collection": { 6528 "type": "object", 6529 "description": "A collection is a set (array) of tagged-link or set 6530 (array) of simple links along with additional properties to describe the collection itself", 6531 "properties": { 6532 "n": { 6533 "type": "string", 6534 "description": "User friendly name of the 6535 collection" }, 6536 "id": { 6537


"anyOf": [ 6538 { 6539 "type": "integer", 6540 "description": "A number that is unique to that 6541 collection; like an ordinal number that is not repeated" 6542 }, 6543 { 6544 "type": "string", 6545 "description": "A unique string that could be a hash or 6546 similarly unique" 6547 }, 6548 { 6549 "$ref": "oic.types-schema.json#/definitions/uuid", 6550 "description": "A unique string that could be a UUIDv4" 6551 } 6552 ], 6553 "description": "ID for the collection. Can be an value that is 6554 unique to the use context or a UUIDv4" 6555 }, 6556 "di": { 6557 "$ref": "oic.types-schema.json#/definitions/uuid", 6558 "description": "The device ID which is an UUIDv4 string; used for 6559 backward compatibility with Spec A definition of /oic/res" 6560 }, 6561 "rts": { 6562 "$ref": "oic.core-6563 schema.json#/definitions/oic.core/properties/rt", 6564 "description": "Defines the list of allowable resource types (for 6565 Target and anchors) in links included in the collection; new links being created can only be from 6566 this list" }, 6567 "drel": { 6568 "type": "string", 6569 "description": "When specified this is the default relationship 6570 to use when an OIC Link does not specify an explicit relationship with *rel* parameter" 6571 }, 6572 "links": { 6573 "$ref": "#/definitions/oic.collection.alllinks" 6574 } 6575 } 6576 } 6577 }, 6578 "type": "object", 6579 "allOf": [ 6580 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 6581 {"$ref": "#/definitions/oic.collection"} 6582 ] 6583 } 6584 6585

example: | 6586

{ 6587 "rt": ["oic.wk.col"], 6588 "id": "unique_example_id", 6589 "rts": [ "oic.r.switch.binary", "oic.r.airflow" ], 6590 "links": [ 6591 { 6592 "href": "switch", 6593 "rt": ["oic.r.switch.binary"], 6594 "if": ["oic.if.a", "oic.if.baseline"] 6595 }, 6596 { 6597 "href": "airFlow", 6598 "rt": ["oic.r.airflow"], 6599 "if": ["oic.if.a", "oic.if.baseline"] 6600 } 6601 ] 6602 } 6603 6604

post: 6605

description: | 6606


Update on Baseline Interface 6607 6608


schema: | 6611

{ 6612 "$schema": "http://json-schema.org/draft-04/schema#", 6613 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 6614 reserved.", 6615 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-6616 schema.json#", 6617 "title": "Collection", 6618 "definitions": { 6619 "oic.collection.setoflinks": { 6620 "description": "A set (array) of simple or individual OIC Links. In addition 6621 to properties required for an OIC Link, the identifier for that link in this set is also required", 6622 "type": "array", 6623 "items": { 6624 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 6625 } 6626 }, 6627 "oic.collection.alllinks": { 6628 "description": "All forms of links in a collection", 6629 "oneOf": [ 6630 { 6631 "$ref": "#/definitions/oic.collection.setoflinks" 6632 } 6633 ] 6634 }, 6635 "oic.collection": { 6636 "type": "object", 6637 "description": "A collection is a set (array) of tagged-link or set (array) 6638 of simple links along with additional properties to describe the collection itself", 6639 "properties": { 6640 "n": { 6641 "type": "string", 6642 "description": "User friendly name of the 6643 collection" }, 6644 "id": { 6645 "anyOf": [ 6646 { 6647 "type": "integer", 6648 "description": "A number that is unique to that collection; 6649 like an ordinal number that is not repeated" 6650 }, 6651 { 6652 "type": "string", 6653 "description": "A unique string that could be a hash or 6654 similarly unique" 6655 }, 6656 { 6657 "$ref": "oic.types-schema.json#/definitions/uuid", 6658 "description": "A unique string that could be a UUIDv4" 6659 } 6660 ], 6661 "description": "ID for the collection. Can be an value that is unique 6662 to the use context or a UUIDv4" 6663 }, 6664 "di": { 6665 "$ref": "oic.types-schema.json#/definitions/uuid", 6666 "description": "The device ID which is an UUIDv4 string; used for 6667 backward compatibility with Spec A definition of /oic/res" 6668 }, 6669 "rts": { 6670 "$ref": "oic.core-schema.json#/definitions/oic.core/properties/rt", 6671 "description": "Defines the list of allowable resource types (for 6672 Target and anchors) in links included in the collection; new links being created can only be from 6673 this list" }, 6674 "drel": { 6675


"type": "string", 6676 "description": "When specified this is the default relationship to 6677 use when an OIC Link does not specify an explicit relationship with *rel* parameter" 6678 }, 6679 "links": { 6680 "$ref": "#/definitions/oic.collection.alllinks" 6681 } 6682 } 6683 } 6684 }, 6685 "type": "object", 6686 "allOf": [ 6687 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 6688 {"$ref": "#/definitions/oic.collection"} 6689 ] 6690 } 6691 6692

responses : 6693

200: 6694


schema: | 6697

{ 6698 "$schema": "http://json-schema.org/draft-04/schema#", 6699 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 6700 reserved.", 6701 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.collection-6702 schema.json#", 6703 "title": "Collection", 6704 "definitions": { 6705 "oic.collection.setoflinks": { 6706 "description": "A set (array) of simple or individual OIC Links. In 6707 addition to properties required for an OIC Link, the identifier for that link in this set is also 6708 required", 6709 "type": "array", 6710 "items": { 6711 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 6712 } 6713 }, 6714 "oic.collection.alllinks": { 6715 "description": "All forms of links in a collection", 6716 "oneOf": [ 6717 { 6718 "$ref": "#/definitions/oic.collection.setoflinks" 6719 } 6720 ] 6721 }, 6722 "oic.collection": { 6723 "type": "object", 6724 "description": "A collection is a set (array) of tagged-link or set 6725 (array) of simple links along with additional properties to describe the collection itself", 6726 "properties": { 6727 "n": { 6728 "type": "string", 6729 "description": "User friendly name of the 6730 collection" }, 6731 "id": { 6732 "anyOf": [ 6733 { 6734 "type": "integer", 6735 "description": "A number that is unique to that 6736 collection; like an ordinal number that is not repeated" 6737 }, 6738 { 6739 "type": "string", 6740 "description": "A unique string that could be a hash or 6741 similarly unique" 6742 }, 6743


{ 6744 "$ref": "oic.types-schema.json#/definitions/uuid", 6745 "description": "A unique string that could be a UUIDv4" 6746 } 6747 ], 6748 "description": "ID for the collection. Can be an value that is 6749 unique to the use context or a UUIDv4" 6750 }, 6751 "di": { 6752 "$ref": "oic.types-schema.json#/definitions/uuid", 6753 "description": "The device ID which is an UUIDv4 string; used for 6754 backward compatibility with Spec A definition of /oic/res" 6755 }, 6756 "rts": { 6757 "$ref": "oic.core-6758 schema.json#/definitions/oic.core/properties/rt", 6759 "description": "Defines the list of allowable resource types (for 6760 Target and anchors) in links included in the collection; new links being created can only be from 6761 this list" }, 6762 "drel": { 6763 "type": "string", 6764 "description": "When specified this is the default relationship 6765 to use when an OIC Link does not specify an explicit relationship with *rel* parameter" 6766 }, 6767 "links": { 6768 "$ref": "#/definitions/oic.collection.alllinks" 6769 } 6770 } 6771 } 6772 }, 6773 "type": "object", 6774 "allOf": [ 6775 {"$ref": "oic.core-schema.json#/definitions/oic.core"}, 6776 {"$ref": "#/definitions/oic.collection"} 6777 ] 6778 } 6779 6780

E.2.5 Property Definition 6781




Read Write Unique identifier for device (UUID)

title string Read Write A title for the link relation. Can be used by the UI to provide a context

buri string Read Write The base URI used to fully qualify a Relative Reference in the href parameter. Use the OCF Schema for URI




Read Write Specifies the framework


policies on the Resource referenced by the target URI

href string yes Read Write 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 Write 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 Read Write This is used to override the context URI e.g. override the URI of the containing collection



E.2.6 CRUDN behavior 6782


E.2.7 Referenced JSON schemas 6783

E.2.8 oic.oic-link-schema.json 6784

{ 6785 "$schema": "http://json-schema.org/draft-04/schema#", 6786 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights reserved.", 6787 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.oic-link-schema.json#", 6788 "definitions": { 6789 "oic.oic-link": { 6790 "type": "object", 6791 "properties": { 6792 "href": { 6793 "type": "string", 6794 "maxLength": 256, 6795


"description": "This is the target URI, it can be specified as a Relative Reference or 6796 fully-qualified URI. Relative Reference should be used along with the di parameter to make it 6797 unique.", 6798 "format": "uri" 6799 }, 6800 "rel": { 6801 "oneOf":[ 6802 { 6803 "type": "array", 6804 "items": { 6805 "type": "string", 6806 "maxLength": 64 6807 }, 6808 "minItems": 1, 6809 "default": ["hosts"] 6810 }, 6811 { 6812 "type": "string", 6813 "maxLength": 64, 6814 "default": "hosts" 6815 } 6816 ], 6817 "description": "The relation of the target URI referenced by the link to the context URI" 6818 }, 6819 "rt": { 6820 "type": "array", 6821 "items" : { 6822 "type" : "string", 6823 "maxLength": 64 6824 }, 6825 "minItems" : 1, 6826 "description": "Resource Type" 6827 }, 6828 "if": { 6829 "type": "array", 6830 "items": { 6831 "type" : "string", 6832 "enum" : ["oic.if.baseline", "oic.if.ll", "oic.if.b", "oic.if.rw", "oic.if.r", 6833 "oic.if.a", "oic.if.s" ] 6834 }, 6835 "minItems": 1, 6836 "description": "The interface set supported by this resource" 6837 }, 6838 "di": { 6839 "$ref": "oic.types-schema.json#/definitions/uuid", 6840 "description": "Unique identifier for device (UUID)" 6841 }, 6842 "buri": { 6843 "type": "string", 6844 "description": "The base URI used to fully qualify a Relative Reference in the href 6845 parameter. Use the OCF Schema for URI", 6846 "maxLength": 256, 6847 "format": "uri" 6848 }, 6849 "p": { 6850 "description": "Specifies the framework policies on the Resource referenced by the target 6851 URI", 6852 "type": "object", 6853 "properties": { 6854 "bm": { 6855 "description": "Specifies the framework policies on the Resource referenced by the 6856 target URI for e.g. observable and discoverable", 6857 "type": "integer" 6858 }, 6859 "sec": { 6860 "description": "Specifies if security needs to be turned on when looking to interact 6861 with the Resource", 6862 "default": false, 6863 "type": "boolean" 6864 }, 6865 "port": { 6866


"description": "Secure port to be used for connection", 6867 "type": "integer" 6868 } 6869 }, 6870 "required" : ["bm"] 6871 }, 6872 "title": { 6873 "type": "string", 6874 "maxLength": 64, 6875 "description": "A title for the link relation. Can be used by the UI to provide a 6876 context" 6877 }, 6878 "anchor": { 6879 "type": "string", 6880 "maxLength": 256, 6881 "description": "This is used to override the context URI e.g. override the URI of the 6882 containing collection", 6883 "format": "uri" 6884 }, 6885 "ins": { 6886 "oneOf": [ 6887 { 6888 "type": "integer", 6889 "description": "An ordinal number that is not repeated - must be unique in the 6890 collection context" 6891 }, 6892 { 6893 "type": "string", 6894 "maxLength": 256, 6895 "format" : "uri", 6896 "description": "Any unique string including a URI" 6897 }, 6898 { 6899 "$ref": "oic.types-schema.json#/definitions/uuid", 6900 "description": "Unique identifier (UUID)" 6901 } 6902 ], 6903 "description": "The instance identifier for this web link in an array of web links - used 6904 in collections" 6905 }, 6906 "type": { 6907 "type": "array", 6908 "description": "A hint at the representation of the resource referenced by the target 6909 URI. This represents the media types that are used for both accepting and emitting", 6910 "items" : { 6911 "type": "string", 6912 "maxLength": 64 6913 }, 6914 "minItems": 1, 6915 "default": "application/cbor" 6916 } 6917 }, 6918 "required": [ "href", "rt", "if" ] 6919 } 6920 }, 6921 "type": "object", 6922 "allOf": [ 6923 { "$ref": "#/definitions/oic.oic-link" } 6924 ] 6925 } 6926 6927 6928

E.3 Collection, link list interface 6929


OCF Collection Resource Type contains properties and links. The oic.if.ll interface exposes a 6931 representation of the links 6932


E.3.2 Example URI 6933

/CollectionLinkListInterfaceURI 6934




#%RAML 0.8 6938



if: 6944 enum: ["oic.if.ll"] 6945


if: 6948 enum: ["oic.if.b"] 6949



6954

/CollectionLinkListInterfaceURI: 6955

description: | 6956 OCF Collection Resource Type contains properties and links. 6957 The oic.if.ll interface exposes a representation of the links 6958 6959


get: 6961

description: | 6962 Retrieve on Link List Interface 6963 6964

responses : 6965

200: 6966


schema: | 6969

{ 6970 "$schema": "http://json-schema.org/draft-v4/schema#", 6971 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 6972 reserved.", 6973 "id": "http://www.openconnectivity.org/ocf-6974 apis/core/schemas/oic.collection.linkslist-schema.json#", 6975 "definitions": { 6976 "oic.collection.alllinks": { 6977 "$ref": "oic.collection-6978 schema.json#/definitions/oic.collection.alllinks" 6979 } 6980 }, 6981 "type": "object", 6982 "properties": { 6983 "links": { 6984 "$ref": "#/definitions/oic.collection.alllinks" 6985 } 6986 } 6987 } 6988 6989


example: | 6990

{ 6991 "links": 6992 [ 6993 { 6994 "href": "switch", 6995 "rt": ["oic.r.switch.binary"], 6996 "if": ["oic.if.a", "oic.if.baseline"] 6997 }, 6998 { 6999 "href": "airFlow", 7000 "rt": ["oic.r.airflow"], 7001 "if": ["oic.if.a", "oic.if.baseline"] 7002 } 7003 ] 7004 } 7005 7006






















Resource Create Read Update Delete Notify /CollectionLinkListInterfaceURI get



{ 7011 "$schema": "http://json-schema.org/draft-04/schema#", 7012 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights reserved.", 7013 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.oic-link-schema.json#", 7014 "definitions": { 7015 "oic.oic-link": { 7016 "type": "object", 7017 "properties": { 7018 "href": { 7019 "type": "string", 7020 "maxLength": 256, 7021 "description": "This is the target URI, it can be specified as a Relative Reference or 7022 fully-qualified URI. Relative Reference should be used along with the di parameter to make it 7023 unique.", 7024 "format": "uri" 7025 }, 7026 "rel": { 7027 "oneOf":[ 7028 { 7029 "type": "array", 7030 "items": { 7031 "type": "string", 7032 "maxLength": 64 7033 }, 7034 "minItems": 1, 7035 "default": ["hosts"] 7036 }, 7037 { 7038 "type": "string", 7039 "maxLength": 64, 7040 "default": "hosts" 7041


} 7042 ], 7043 "description": "The relation of the target URI referenced by the link to the context URI" 7044 }, 7045 "rt": { 7046 "type": "array", 7047 "items" : { 7048 "type" : "string", 7049 "maxLength": 64 7050 }, 7051 "minItems" : 1, 7052 "description": "Resource Type" 7053 }, 7054 "if": { 7055 "type": "array", 7056 "items": { 7057 "type" : "string", 7058 "enum" : ["oic.if.baseline", "oic.if.ll", "oic.if.b", "oic.if.rw", "oic.if.r", 7059 "oic.if.a", "oic.if.s" ] 7060 }, 7061 "minItems": 1, 7062 "description": "The interface set supported by this resource" 7063 }, 7064 "di": { 7065 "$ref": "oic.types-schema.json#/definitions/uuid", 7066 "description": "Unique identifier for device (UUID)" 7067 }, 7068 "buri": { 7069 "type": "string", 7070 "description": "The base URI used to fully qualify a Relative Reference in the href 7071 parameter. Use the OCF Schema for URI", 7072 "maxLength": 256, 7073 "format": "uri" 7074 }, 7075 "p": { 7076 "description": "Specifies the framework policies on the Resource referenced by the target 7077 URI", 7078 "type": "object", 7079 "properties": { 7080 "bm": { 7081 "description": "Specifies the framework policies on the Resource referenced by the 7082 target URI for e.g. observable and discoverable", 7083 "type": "integer" 7084 }, 7085 "sec": { 7086 "description": "Specifies if security needs to be turned on when looking to interact 7087 with the Resource", 7088 "default": false, 7089 "type": "boolean" 7090 }, 7091 "port": { 7092 "description": "Secure port to be used for connection", 7093 "type": "integer" 7094 } 7095 }, 7096 "required" : ["bm"] 7097 }, 7098 "title": { 7099 "type": "string", 7100 "maxLength": 64, 7101 "description": "A title for the link relation. Can be used by the UI to provide a 7102 context" 7103 }, 7104 "anchor": { 7105 "type": "string", 7106 "maxLength": 256, 7107 "description": "This is used to override the context URI e.g. override the URI of the 7108 containing collection", 7109 "format": "uri" 7110 }, 7111 "ins": { 7112


"oneOf": [ 7113 { 7114 "type": "integer", 7115 "description": "An ordinal number that is not repeated - must be unique in the 7116 collection context" 7117 }, 7118 { 7119 "type": "string", 7120 "maxLength": 256, 7121 "format" : "uri", 7122 "description": "Any unique string including a URI" 7123 }, 7124 { 7125 "$ref": "oic.types-schema.json#/definitions/uuid", 7126 "description": "Unique identifier (UUID)" 7127 } 7128 ], 7129 "description": "The instance identifier for this web link in an array of web links - used 7130 in collections" 7131 }, 7132 "type": { 7133 "type": "array", 7134 "description": "A hint at the representation of the resource referenced by the target 7135 URI. This represents the media types that are used for both accepting and emitting", 7136 "items" : { 7137 "type": "string", 7138 "maxLength": 64 7139 }, 7140 "minItems": 1, 7141 "default": "application/cbor" 7142 } 7143 }, 7144 "required": [ "href", "rt", "if" ] 7145 } 7146 }, 7147 "type": "object", 7148 "allOf": [ 7149 { "$ref": "#/definitions/oic.oic-link" } 7150 ] 7151 } 7152 7153 7154

E.4 Discoverable Resources, baseline interface 7155


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

E.4.2 Wellknown URI 7158

/oic/res 7159




#%RAML 0.8 7163



if: 7169 enum: ["oic.if.ll"] 7170




7175

/oic-res-baseline-URI: 7176

description: | 7177 Baseline representation of /oic/res; list of discoverable resources 7178 7179


get: 7181

description: | 7182 Retrieve the discoverable resource set, baseline interface 7183 7184

responses : 7185

200: 7186


schema: | 7189

{ 7190 "$schema": "http://json-schema.org/draft-v4/schema#", 7191 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 7192 reserved.", 7193 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.res-7194 schema.json#", 7195 "definitions": { 7196 "oic.res-baseline": { 7197 "type": "object", 7198 "properties": { 7199 "rt": { 7200 "type": "array", 7201 "items" : { 7202 "type" : "string", 7203 "maxLength": 64 7204 }, 7205 "minItems" : 1, 7206 "readOnly": true, 7207 "description": "Resource Type" 7208 }, 7209 "if": { 7210 "type": "array", 7211 "items": { 7212 "type" : "string", 7213 "enum" : ["oic.if.baseline", "oic.if.ll"] 7214 }, 7215 "minItems": 1, 7216 "readOnly": true, 7217 "description": "The interface set supported by this resource" 7218 }, 7219 "n": { 7220 "type": "string", 7221 "maxLength": 64, 7222 "readOnly": true, 7223 "description": "Human friendly name" 7224 }, 7225 "di": { 7226 "$ref": "oic.types-schema.json#/definitions/uuid", 7227 "readOnly": true, 7228 "description": "Unique identifier for device (UUID) as indicated by the 7229 /oic/d resource of the device" 7230 }, 7231 "mpro": { 7232 "readOnly": true, 7233 "description": "Supported messaging protocols", 7234 "type": "string", 7235 "maxLength": 64 7236 }, 7237


"links": { 7238 "type": "array", 7239 "items": { 7240 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 7241 } 7242 } 7243 }, 7244 "required": ["rt", "if", "di", "links"] 7245 } 7246 }, 7247 "description": "The list of resources expressed as OIC links", 7248 "type": "array", 7249 "items": { 7250 "$ref": "#/definitions/oic.res-baseline" 7251 } 7252 } 7253 7254

example: | 7255

[ 7256 { 7257 "rt": ["oic.wk.res"], 7258 "if": ["oic.if.baseline", "oic.if.ll" ], 7259 "di": "0685B960-736F-46F7-BEC0-9E6CBD61ADC1", 7260 "links": 7261 [ 7262 { 7263 "href": "/humidity", 7264 "rt": ["oic.r.humidity"], 7265 "if": ["oic.if.s"] 7266 }, 7267 { 7268 "href": "/temperature", 7269 "rt": ["oic.r.temperature"], 7270 "if": ["oic.if.s"] 7271 } 7272 ] 7273 } 7274 ] 7275 7276




links array: see schema

yes Read Write


yes Read Only Unique identifier for device (UUID) as indicated by the /oic/d resource of the device


n string Read Only Human friendly name




Resource Create Read Update Delete Notify


/oic/res get

E.5 Discoverable Resources, link list interface 7279


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

E.5.2 Wellknown URI 7282

/oic/res 7283




#%RAML 0.8 7287



if: 7293 enum: ["oic.if.ll"] 7294



7299

/oic-res-ll-URI: 7300

description: | 7301 Link list representation of /oic/res; list of discoverable resources 7302 7303


get: 7305

description: | 7306 Retrieve the discoverable resource set, link list interface 7307 7308

responses : 7309

200: 7310


schema: | 7313

{ 7314 "$schema": "http://json-schema.org/draft-v4/schema#", 7315 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 7316 reserved.", 7317 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.wk.res-schema-7318 ll.json#", 7319 "definitions": { 7320 "oic.res-ll": { 7321 "type": "object", 7322 "properties": { 7323 "di": { 7324 "$ref": "oic.types-schema.json#/definitions/uuid", 7325 "readOnly": true, 7326 "description": "Unique identifier for device (UUID) as indicated by the 7327 /oic/d resource of the device" 7328 }, 7329 "links": { 7330


"type": "array", 7331 "items": { 7332 "$ref": "oic.oic-link-schema.json#/definitions/oic.oic-link" 7333 } 7334 } 7335 }, 7336 "required": ["di", "links"] 7337 } 7338 }, 7339 "description": "The list of resources expressed as OIC links with di ", 7340 "type": "array", 7341 "items": { 7342 "$ref": "#/definitions/oic.res-ll" 7343 } 7344 } 7345 7346

example: | 7347

[ 7348 { 7349 "di": "0685B960-736F-46F7-BEC0-9E6CBD61ADC1", 7350 "links": 7351 [ 7352 { 7353 "href": "/humidity", 7354 "rt": ["oic.r.humidity"], 7355 "if": ["oic.if.s"] 7356 }, 7357 { 7358 "href": "/temperature", 7359 "rt": ["oic.r.temperature"], 7360 "if": ["oic.if.s"] 7361 } 7362 ] 7363 } 7364 ] 7365 7366


Property name Value type Mandatory Access mode Description links array: see

schema yes Read Write


yes Read Only Unique identifier for device (UUID) as indicated by the /oic/d resource of the device

rt array: see schema

yes Read Write Resource Type























{ 7371 "$schema": "http://json-schema.org/draft-04/schema#", 7372 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights reserved.", 7373 "id": "http://www.openconnectivity.org/ocf-apis/core/schemas/oic.oic-link-schema.json#", 7374 "definitions": { 7375 "oic.oic-link": { 7376 "type": "object", 7377 "properties": { 7378 "href": { 7379 "type": "string", 7380 "maxLength": 256, 7381 "description": "This is the target URI, it can be specified as a Relative Reference or 7382 fully-qualified URI. Relative Reference should be used along with the di parameter to make it 7383 unique.", 7384 "format": "uri" 7385 }, 7386 "rel": { 7387 "oneOf":[ 7388 { 7389 "type": "array", 7390 "items": { 7391 "type": "string", 7392 "maxLength": 64 7393 }, 7394 "minItems": 1, 7395 "default": ["hosts"] 7396 }, 7397 { 7398 "type": "string", 7399 "maxLength": 64, 7400 "default": "hosts" 7401 } 7402 ], 7403 "description": "The relation of the target URI referenced by the link to the context URI" 7404 }, 7405 "rt": { 7406 "type": "array", 7407 "items" : { 7408 "type" : "string", 7409 "maxLength": 64 7410 }, 7411 "minItems" : 1, 7412 "description": "Resource Type" 7413 }, 7414 "if": { 7415 "type": "array", 7416 "items": { 7417 "type" : "string", 7418 "enum" : ["oic.if.baseline", "oic.if.ll", "oic.if.b", "oic.if.rw", "oic.if.r", 7419 "oic.if.a", "oic.if.s" ] 7420 }, 7421 "minItems": 1, 7422 "description": "The interface set supported by this resource" 7423 }, 7424 "di": { 7425 "$ref": "oic.types-schema.json#/definitions/uuid", 7426 "description": "Unique identifier for device (UUID)" 7427 }, 7428 "buri": { 7429 "type": "string", 7430 "description": "The base URI used to fully qualify a Relative Reference in the href 7431 parameter. Use the OCF Schema for URI", 7432 "maxLength": 256, 7433 "format": "uri" 7434 }, 7435 "p": { 7436 "description": "Specifies the framework policies on the Resource referenced by the target 7437


URI", 7438 "type": "object", 7439 "properties": { 7440 "bm": { 7441 "description": "Specifies the framework policies on the Resource referenced by the 7442 target URI for e.g. observable and discoverable", 7443 "type": "integer" 7444 }, 7445 "sec": { 7446 "description": "Specifies if security needs to be turned on when looking to interact 7447 with the Resource", 7448 "default": false, 7449 "type": "boolean" 7450 }, 7451 "port": { 7452 "description": "Secure port to be used for connection", 7453 "type": "integer" 7454 } 7455 }, 7456 "required" : ["bm"] 7457 }, 7458 "title": { 7459 "type": "string", 7460 "maxLength": 64, 7461 "description": "A title for the link relation. Can be used by the UI to provide a 7462 context" 7463 }, 7464 "anchor": { 7465 "type": "string", 7466 "maxLength": 256, 7467 "description": "This is used to override the context URI e.g. override the URI of the 7468 containing collection", 7469 "format": "uri" 7470 }, 7471 "ins": { 7472 "oneOf": [ 7473 { 7474 "type": "integer", 7475 "description": "An ordinal number that is not repeated - must be unique in the 7476 collection context" 7477 }, 7478 { 7479 "type": "string", 7480 "maxLength": 256, 7481 "format" : "uri", 7482 "description": "Any unique string including a URI" 7483 }, 7484 { 7485 "$ref": "oic.types-schema.json#/definitions/uuid", 7486 "description": "Unique identifier (UUID)" 7487 } 7488 ], 7489 "description": "The instance identifier for this web link in an array of web links - used 7490 in collections" 7491 }, 7492 "type": { 7493 "type": "array", 7494 "description": "A hint at the representation of the resource referenced by the target 7495 URI. This represents the media types that are used for both accepting and emitting", 7496 "items" : { 7497 "type": "string", 7498 "maxLength": 64 7499 }, 7500 "minItems": 1, 7501 "default": "application/cbor" 7502 } 7503 }, 7504 "required": [ "href", "rt", "if" ] 7505 } 7506 }, 7507 "type": "object", 7508


"allOf": [ 7509 { "$ref": "#/definitions/oic.oic-link" } 7510 ] 7511 } 7512 7513

7514


Annex F 7515

(informative) 7516

7517

Swagger2.0 definitions 7518

7519

7520

F.1 Icon 7521

F.1.1 Introduction 7522

This resource describes the attributes associated with an Icon. 7523 Retrieves the current icon properties. 7524 7525

F.1.2 Wellknown URI 7526

/IconResURI 7527

F.1.3 Resource Type 7528

The resource type (rt) is defined as: ['oic.r.icon']. 7529

F.1.4 Swagger2.0 Definition 7530

{ 7531 "swagger": "2.0", 7532 "info": { 7533 "title": "Icon", 7534 "version": "v1.1.0-20161107", 7535 "license": { 7536 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 7537 "x-description": "Redistribution and use in source and binary forms, with or without 7538 modification, are permitted provided that the following conditions are met:\n 1. 7539 Redistributions of source code must retain the above copyright notice, this list of conditions and 7540 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 7541 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 7542 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 7543 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 7544 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 7545 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 7546 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 7547 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 7548 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 7549 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 7550 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 7551 OF SUCH DAMAGE.\n" 7552 } 7553 }, 7554 "schemes": ["http"], 7555 "consumes": ["application/json"], 7556 "produces": ["application/json"], 7557 "paths": { 7558 "/IconResURI" : { 7559 "get": { 7560 "description": "This resource describes the attributes associated with an Icon.\nRetrieves 7561 the current icon properties.\n", 7562 "parameters": [ 7563 {"$ref": "#/parameters/interface"} 7564 ], 7565 "responses": { 7566 "200": { 7567 "description" : "", 7568 "x-example": 7569 { 7570 "rt": ["oic.r.icon"], 7571


"id": "unique_example_id", 7572 "mimetype": "image/png", 7573 "width": 256, 7574 "height": 256, 7575 "media": "http://findbetter.ru/public/uploads/1481662800/2043.png" 7576 } 7577 , 7578 "schema": { "$ref": "#/definitions/Icon" } 7579 } 7580 } 7581 } 7582 } 7583 }, 7584 "parameters": { 7585 "interface" : { 7586 "in" : "query", 7587 "name" : "if", 7588 "type" : "string", 7589 "enum" : ["oic.if.r", "oic.if.baseline"] 7590 } 7591 }, 7592 "definitions": { 7593 "Icon" : 7594 { 7595 "properties": { 7596 "height": { 7597 "description": "The height in pixels", 7598 "minimum": 1, 7599 "readOnly": true, 7600 "type": "integer" 7601 }, 7602 "id": { 7603 "anyOf": [ 7604 { 7605 "maxLength": 64, 7606 "type": "string" 7607 }, 7608 { 7609 "description": "Format pattern according to IETF RFC 4122.", 7610 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-7611 9]{12}$", 7612 "type": "string" 7613 } 7614 ], 7615 "description": "Instance ID of this specific resource", 7616 "readOnly": true 7617 }, 7618 "if": { 7619 "description": "The interface set supported by this resource", 7620 "items": { 7621 "enum": [ 7622 "oic.if.baseline", 7623 "oic.if.ll", 7624 "oic.if.b", 7625 "oic.if.lb", 7626 "oic.if.rw", 7627 "oic.if.r", 7628 "oic.if.a", 7629 "oic.if.s" 7630 ], 7631 "type": "string" 7632 }, 7633 "minItems": 1, 7634 "readOnly": true, 7635 "type": "array" 7636 }, 7637 "media": { 7638 "description": "Specifies the URI to the icon", 7639 "format": "uri", 7640 "maxLength": 256, 7641 "readOnly": true, 7642


"type": "string" 7643 }, 7644 "mimetype": { 7645 "description": "The format of the MIME Type", 7646 "maxLength": 64, 7647 "readOnly": true, 7648 "type": "string" 7649 }, 7650 "n": { 7651 "description": "Friendly name of the resource", 7652 "maxLength": 64, 7653 "readOnly": true, 7654 "type": "string" 7655 }, 7656 "rt": { 7657 "description": "Resource Type of the Resource", 7658 "items": { 7659 "maxLength": 64, 7660 "type": "string" 7661 }, 7662 "minItems": 1, 7663 "readOnly": true, 7664 "type": "array" 7665 }, 7666 "width": { 7667 "description": "The width in pixels", 7668 "minimum": 1, 7669 "readOnly": true, 7670 "type": "integer" 7671 } 7672 }, 7673 "required": [ 7674 "mimetype", 7675 "width", 7676 "height", 7677 "media" 7678 ] 7679 } 7680 7681 } 7682 } 7683 7684

F.1.5 Property Definition 7685

Property name Value type Mandatory Access mode Description if array: see

schema Read Only The interface set

supported by this resource

width integer yes Read Only The width in pixels


Read Only Resource Type of the Resource

id multiple types: see schema

Read Only Instance ID of this specific resource

media string yes Read Only Specifies the URI to the icon

height integer yes Read Only The height in pixels

n string Read Only Friendly name of the resource

mimetype string yes Read Only The format of the MIME Type


F.1.6 CRUDN behavior 7686

Resource Create Read Update Delete Notify /IconResURI get

F.2 Introspection Resource 7687


This resource provides the means to get the device introspection data specifiying all the endpoints 7689 of the device. 7690 The url hosted by this resource is either a local or an external url. 7691 7692


/IntrospectionResURI 7694


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


{ 7698 "swagger": "2.0", 7699 "info": { 7700 "title": "Introspection Resource", 7701 "version": "v1.0.0-20160707", 7702 "license": { 7703 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 7704 "x-description": "Redistribution and use in source and binary forms, with or without 7705 modification, are permitted provided that the following conditions are met:\n 1. 7706 Redistributions of source code must retain the above copyright notice, this list of conditions and 7707 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 7708 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 7709 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 7710 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 7711 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 7712 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 7713 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 7714 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 7715 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 7716 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 7717 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 7718 OF SUCH DAMAGE.\n" 7719 } 7720 }, 7721 "schemes": ["http"], 7722 "consumes": ["application/json"], 7723 "produces": ["application/json"], 7724 "paths": { 7725 "/IntrospectionResURI" : { 7726 "get": { 7727 "description": "This resource provides the means to get the device introspection data 7728 specifiying all the endpoints of the device.\nThe url hosted by this resource is either a local or 7729 an external url.\n", 7730 "parameters": [ 7731 {"$ref": "#/parameters/interface"} 7732 ], 7733 "responses": { 7734 "200": { 7735 "description" : "", 7736 "x-example": 7737 { 7738 "rt" : ["oic.wk.introspection"], 7739 "urlInfo" : [ 7740 { 7741 "content-type" : "application/cbor", 7742 "protocol" : "coap", 7743


"url" : "coap://[fe80::1]:1234/IntrospectionExampleURI" 7744 } 7745 ] 7746 } 7747 , 7748 "schema": { "$ref": "#/definitions/oic.wk.introspectionInfo" } 7749 } 7750 } 7751 } 7752 } 7753 }, 7754 "parameters": { 7755 "interface" : { 7756 "in" : "query", 7757 "name" : "if", 7758 "type" : "string", 7759 "enum" : ["oic.if.r", "oic.if.baseline"] 7760 } 7761 }, 7762 "definitions": { 7763 "oic.wk.introspectionInfo" : 7764 { 7765 "properties": { 7766 "id": { 7767 "anyOf": [ 7768 { 7769 "maxLength": 64, 7770 "type": "string" 7771 }, 7772 { 7773 "description": "Format pattern according to IETF RFC 4122.", 7774 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-7775 9]{12}$", 7776 "type": "string" 7777 } 7778 ], 7779 "description": "Instance ID of this specific resource", 7780 "readOnly": true 7781 }, 7782 "if": { 7783 "description": "The interface set supported by this resource", 7784 "items": { 7785 "enum": [ 7786 "oic.if.baseline", 7787 "oic.if.ll", 7788 "oic.if.b", 7789 "oic.if.lb", 7790 "oic.if.rw", 7791 "oic.if.r", 7792 "oic.if.a", 7793 "oic.if.s" 7794 ], 7795 "type": "string" 7796 }, 7797 "minItems": 1, 7798 "readOnly": true, 7799 "type": "array" 7800 }, 7801 "n": { 7802 "description": "Friendly name of the resource", 7803 "maxLength": 64, 7804 "readOnly": true, 7805 "type": "string" 7806 }, 7807 "rt": { 7808 "description": "Resource Type of the Resource", 7809 "items": { 7810 "maxLength": 64, 7811 "type": "string" 7812 }, 7813 "minItems": 1, 7814


"readOnly": true, 7815 "type": "array" 7816 }, 7817 "urlInfo": { 7818 "description": "Information on the location of the introspection data.", 7819 "items": { 7820 "properties": { 7821 "content-type": { 7822 "default": "application/cbor", 7823 "description": "content-type of the introspection data", 7824 "enum": [ 7825 "application/json", 7826 "application/cbor" 7827 ], 7828 "type": "string" 7829 }, 7830 "protocol": { 7831 "description": "Identifier for the protocol to be used to obtain the 7832 introspection information", 7833 "enum": [ 7834 "coap", 7835 "coaps", 7836 "http", 7837 "https", 7838 "coap+tcp", 7839 "coaps+tcp" 7840 ], 7841 "type": "string" 7842 }, 7843 "url": { 7844 "description": "The URL of the introspection information.", 7845 "format": "uri", 7846 "type": "string" 7847 }, 7848 "version": { 7849 "default": 1, 7850 "description": "The version of the introspection data that can be downloaded", 7851 "enum": [ 7852 1 7853 ], 7854 "type": "integer" 7855 } 7856 }, 7857 "required": [ 7858 "url", 7859 "protocol" 7860 ], 7861 "type": "object" 7862 }, 7863 "minItems": 1, 7864 "readOnly": true, 7865 "type": "array" 7866 } 7867 }, 7868 "required": [ 7869 "urlInfo" 7870 ], 7871 "type": "object" 7872 } 7873 7874 } 7875 } 7876 7877


Property name Value type Mandatory Access mode Description n string Read Only Friendly name of

the resource




urlInfo array: see schema

yes Read Only Information on the location of the introspection data.


Read Only The interface set supported by this resource




Resource Create Read Update Delete Notify /IntrospectionResURI get

F.3 OCF Collection 7880


OCF Collection Resource Type contains properties and links. 7882 The oic.if.baseline interface exposes a representation of 7883 the links and the properties of the collection resource itself 7884 Retrieve on Baseline Interface 7885 7886




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


{ 7892 "swagger": "2.0", 7893 "info": { 7894 "title": "OCF Collection", 7895 "version": "1.0", 7896 "license": { 7897 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 7898 "x-description": "Redistribution and use in source and binary forms, with or without 7899 modification, are permitted provided that the following conditions are met:\n 1. 7900 Redistributions of source code must retain the above copyright notice, this list of conditions and 7901 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 7902 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 7903 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 7904 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 7905 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 7906 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 7907 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 7908 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 7909 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 7910 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 7911 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 7912 OF SUCH DAMAGE.\n" 7913 } 7914 }, 7915 "schemes": ["http"], 7916 "consumes": ["application/json"], 7917 "produces": ["application/json"], 7918 "paths": { 7919 "/CollectionBaselineInterfaceURI" : { 7920


"get": { 7921 "description": "OCF Collection Resource Type contains properties and links.\nThe 7922 oic.if.baseline interface exposes a representation of\nthe links and the properties of the 7923 collection resource itself\nRetrieve on Baseline Interface\n", 7924 "parameters": [ 7925 {"$ref": "#/parameters/interface-baseline"} 7926 ], 7927 "responses": { 7928 "200": { 7929 "description" : "", 7930 "x-example": 7931 { 7932 "rt": ["oic.wk.col"], 7933 "id": "unique_example_id", 7934 "rts": [ "oic.r.switch.binary", "oic.r.airflow" ], 7935 "links": [ 7936 { 7937 "href": "switch", 7938 "rt": ["oic.r.switch.binary"], 7939 "if": ["oic.if.a", "oic.if.baseline"], 7940 "eps": [ 7941 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 7942 {"ep": "coaps://[fe80::b1d6]:1122"}, 7943 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 7944 ] 7945 }, 7946 { 7947 "href": "airFlow", 7948 "rt": ["oic.r.airflow"], 7949 "if": ["oic.if.a", "oic.if.baseline"], 7950 "eps": [ 7951 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 7952 {"ep": "coaps://[fe80::b1d6]:1122"}, 7953 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 7954 ] 7955 } 7956 ] 7957 } 7958 , 7959 "schema": { "$ref": "#/definitions/sbaseline" } 7960 } 7961 } 7962 }, 7963 "post": { 7964 "description": "Update on Baseline Interface\n", 7965 "parameters": [ 7966 {"$ref": "#/parameters/interface-baseline"}, 7967 { 7968 "name": "body", 7969 "in": "body", 7970 "required": true, 7971 "schema": { "$ref": "#/definitions/sbaseline" } 7972 } 7973 ], 7974 "responses": { 7975 "200": { 7976 "description" : "", 7977 "schema": { "$ref": "#/definitions/sbaseline" } 7978 } 7979 } 7980 } 7981 }, 7982 "/CollectionBatchInterfaceURI" : { 7983 "get": { 7984 "description": "OCF Collection Resource Type contains properties and links.\nThe oic.if.b 7985 interfacce exposes a composite representation of the\nresources pointed to by the links\nRetrieve 7986 on Batch Interface\n", 7987 "parameters": [ 7988 {"$ref": "#/parameters/interface-b"} 7989 ], 7990 "responses": { 7991


"200": { 7992 "description" : "All targets returned OK status (HTTP 200 or CoAP 2.05 Content)", 7993 "x-example": 7994 [ 7995 { 7996 "href": "switch", 7997 "rep": 7998 { 7999 "value": true 8000 } 8001 }, 8002 { 8003 "href": "airFlow", 8004 "rep": 8005 { 8006 "direction": "floor", 8007 "speed": 3 8008 } 8009 } 8010 ] 8011 , 8012 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 8013 }, 8014 "404": { 8015 "description" : "One or more targets did not return an OK status, return a 8016 representation containing returned properties from the targets that returned OK", 8017 "x-example": 8018 [ 8019 { 8020 "href": "switch", 8021 "rep": 8022 { 8023 "value": true 8024 } 8025 } 8026 ] 8027 , 8028 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 8029 } 8030 } 8031 }, 8032 "post": { 8033 "description": "Update on Batch Interface\n", 8034 "parameters": [ 8035 {"$ref": "#/parameters/interface-b"}, 8036 { 8037 "name": "body", 8038 "in": "body", 8039 "required": true, 8040 "schema": { "$ref": "#/definitions/sbatch-update" }, 8041 "x-example": 8042 [ 8043 { 8044 "href": "switch", 8045 "rep": 8046 { 8047 "value": true 8048 } 8049 }, 8050 { 8051 "href": "airFlow", 8052 "rep": 8053 { 8054 "direction": "floor", 8055 "speed": 3 8056 } 8057 } 8058 ] 8059 } 8060 ], 8061 "responses": { 8062


"200": { 8063 "description" : "all targets returned OK status (HTTP 200 or CoAP 2.04 Changed) 8064 return a representation of the current state of all targets", 8065 "x-example": 8066 [ 8067 { 8068 "href": "switch", 8069 "rep": 8070 { 8071 "value": true 8072 } 8073 }, 8074 { 8075 "href": "airFlow", 8076 "rep": 8077 { 8078 "direction": "demist", 8079 "speed": 5 8080 } 8081 } 8082 ] 8083 , 8084 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 8085 }, 8086 "403": { 8087 "description" : "one or more targets did not return OK status; return a retrieve 8088 representation of the current state of all targets in the batch", 8089 "x-example": 8090 [ 8091 { 8092 "href": "switch", 8093 "rep": 8094 { 8095 "value": true 8096 } 8097 }, 8098 { 8099 "href": "airFlow", 8100 "rep": 8101 { 8102 "direction": "floor", 8103 "speed": 3 8104 } 8105 } 8106 ] 8107 , 8108 "schema": { "$ref": "#/definitions/sbatch-retrieve" } 8109 } 8110 } 8111 } 8112 }, 8113 "/CollectionLinkListInterfaceURI" : { 8114 "get": { 8115 "description": "OCF Collection Resource Type contains properties and links.\nThe oic.if.ll 8116 interface exposes a representation of the links\nRetrieve on Link List Interface\n", 8117 "parameters": [ 8118 {"$ref": "#/parameters/interface-ll"} 8119 ], 8120 "responses": { 8121 "200": { 8122 "description" : "", 8123 "x-example": 8124 [ 8125 { 8126 "href": "switch", 8127 "rt": ["oic.r.switch.binary"], 8128 "if": ["oic.if.a", "oic.if.baseline"], 8129 "eps": [ 8130 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 8131 {"ep": "coaps://[fe80::b1d6]:1122"}, 8132 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 8133


] 8134 }, 8135 { 8136 "href": "airFlow", 8137 "rt": ["oic.r.airflow"], 8138 "if": ["oic.if.a", "oic.if.baseline"], 8139 "eps": [ 8140 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 8141 {"ep": "coaps://[fe80::b1d6]:1122"}, 8142 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 8143 ] 8144 } 8145 ] 8146 , 8147 "schema": { "$ref": "#/definitions/slinks" } 8148 } 8149 } 8150 } 8151 } 8152 }, 8153 "parameters": { 8154 "interface-ll" : { 8155 "in" : "query", 8156 "name" : "if", 8157 "type" : "string", 8158 "enum" : ["oic.if.ll"] 8159 }, 8160 "interface-b" : { 8161 "in" : "query", 8162 "name" : "if", 8163 "type" : "string", 8164 "enum" : ["oic.if.b"] 8165 }, 8166 "interface-baseline" : { 8167 "in" : "query", 8168 "name" : "if", 8169 "type" : "string", 8170 "enum" : ["oic.if.baseline"] 8171 }, 8172 "interface-all" : { 8173 "in" : "query", 8174 "name" : "if", 8175 "type" : "string", 8176 "enum" : ["oic.if.ll", "oic.if.baseline", "oic.if.b"] 8177 } 8178 }, 8179 "definitions": { 8180 "sbaseline" : 8181 { 8182 "description": "A set of simple or individual OIC Links.", 8183 "items": { 8184 "properties": { 8185 "anchor": { 8186 "description": "This is used to override the context URI e.g. override the URI of the 8187 containing collection.", 8188 "format": "uri", 8189 "maxLength": 256, 8190 "type": "string" 8191 }, 8192 "di": { 8193 "allOf": [ 8194 { 8195 "description": "Format pattern according to IETF RFC 4122.", 8196 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-8197 F0-9]{12}$", 8198 "type": "string" 8199 }, 8200 { 8201 "description": "The device ID" 8202 } 8203 ] 8204


}, 8205 "eps": { 8206 "description": "the Endpoint information of the target Resource", 8207 "items": { 8208 "properties": { 8209 "ep": { 8210 "description": "Transport Protocol Suite + Endpoint Locator", 8211 "format": "uri", 8212 "type": "string" 8213 }, 8214 "pri": { 8215 "description": "The priority among multiple Endpoints", 8216 "minimum": 1, 8217 "type": "integer" 8218 } 8219 }, 8220 "type": "object" 8221 }, 8222 "type": "array" 8223 }, 8224 "href": { 8225 "description": "This is the target URI, it can be specified as a Relative Reference 8226 or fully-qualified URI.", 8227 "format": "uri", 8228 "maxLength": 256, 8229 "type": "string" 8230 }, 8231 "id": { 8232 "anyOf": [ 8233 { 8234 "maxLength": 64, 8235 "type": "string" 8236 }, 8237 { 8238 "description": "Format pattern according to IETF RFC 4122.", 8239 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-8240 F0-9]{12}$", 8241 "type": "string" 8242 } 8243 ], 8244 "description": "Instance ID of this specific resource", 8245 "readOnly": true 8246 }, 8247 "if": { 8248 "description": "The interface set supported by this resource", 8249 "items": { 8250 "enum": [ 8251 "oic.if.baseline", 8252 "oic.if.ll", 8253 "oic.if.b", 8254 "oic.if.rw", 8255 "oic.if.r", 8256 "oic.if.a", 8257 "oic.if.s" 8258 ], 8259 "type": "string" 8260 }, 8261 "minItems": 1, 8262 "type": "array" 8263 }, 8264 "ins": { 8265 "description": "The instance identifier for this web link in an array of web links - 8266 used in collections", 8267 "oneOf": [ 8268 { 8269 "description": "An ordinal number that is not repeated - must be unique in the 8270 collection context.", 8271 "type": "integer" 8272 }, 8273 { 8274 "description": "A unique string", 8275


"format": "uri", 8276 "maxLength": 256, 8277 "type": "string" 8278 }, 8279 { 8280 "allOf": [ 8281 { 8282 "description": "Format pattern according to IETF RFC 4122.", 8283 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-8284 fA-F0-9]{12}$", 8285 "type": "string" 8286 }, 8287 { 8288 "description": "A UUID" 8289 } 8290 ] 8291 } 8292 ] 8293 }, 8294 "links": { 8295 "description": "All forms of links in a collection.", 8296 "oneOf": [ 8297 { 8298 "description": "A set of simple or individual OIC Links.", 8299 "items": { 8300 "properties": { 8301 "anchor": { 8302 "description": "This is used to override the context URI e.g. override the 8303 URI of the containing collection.", 8304 "format": "uri", 8305 "maxLength": 256, 8306 "type": "string" 8307 }, 8308 "di": { 8309 "allOf": [ 8310 { 8311 "description": "Format pattern according to IETF RFC 4122.", 8312 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-8313 9]{4}-[a-fA-F0-9]{12}$", 8314 "type": "string" 8315 }, 8316 { 8317 "description": "The device ID" 8318 } 8319 ] 8320 }, 8321 "eps": { 8322 "description": "the Endpoint information of the target Resource", 8323 "items": { 8324 "properties": { 8325 "ep": { 8326 "description": "Transport Protocol Suite + Endpoint Locator", 8327 "format": "uri", 8328 "type": "string" 8329 }, 8330 "pri": { 8331 "description": "The priority among multiple Endpoints", 8332 "minimum": 1, 8333 "type": "integer" 8334 } 8335 }, 8336 "type": "object" 8337 }, 8338 "type": "array" 8339 }, 8340 "href": { 8341 "description": "This is the target URI, it can be specified as a Relative 8342 Reference or fully-qualified URI.", 8343 "format": "uri", 8344 "maxLength": 256, 8345 "type": "string" 8346


}, 8347 "if": { 8348 "description": "The interface set supported by this resource", 8349 "items": { 8350 "enum": [ 8351 "oic.if.baseline", 8352 "oic.if.ll", 8353 "oic.if.b", 8354 "oic.if.rw", 8355 "oic.if.r", 8356 "oic.if.a", 8357 "oic.if.s" 8358 ], 8359 "type": "string" 8360 }, 8361 "minItems": 1, 8362 "type": "array" 8363 }, 8364 "ins": { 8365 "description": "The instance identifier for this web link in an array of 8366 web links - used in collections", 8367 "oneOf": [ 8368 { 8369 "description": "An ordinal number that is not repeated - must be unique 8370 in the collection context.", 8371 "type": "integer" 8372 }, 8373 { 8374 "description": "A unique string", 8375 "format": "uri", 8376 "maxLength": 256, 8377 "type": "string" 8378 }, 8379 { 8380 "allOf": [ 8381 { 8382 "description": "Format pattern according to IETF RFC 4122.", 8383 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-8384 9]{4}-[a-fA-F0-9]{12}$", 8385 "type": "string" 8386 }, 8387 { 8388 "description": "A UUID" 8389 } 8390 ] 8391 } 8392 ] 8393 }, 8394 "p": { 8395 "description": "Specifies the framework policies on the Resource referenced 8396 by the target URI", 8397 "properties": { 8398 "bm": { 8399 "description": "Specifies the framework policies on the Resource 8400 referenced by the target URI for e.g. observable and discoverable", 8401 "type": "integer" 8402 } 8403 }, 8404 "required": [ 8405 "bm" 8406 ], 8407 "type": "object" 8408 }, 8409 "rel": { 8410 "description": "The relation of the target URI referenced by the link to 8411 the context URI", 8412 "oneOf": [ 8413 { 8414 "default": [ 8415 "hosts" 8416 ], 8417


"items": { 8418 "maxLength": 64, 8419 "type": "string" 8420 }, 8421 "minItems": 1, 8422 "type": "array" 8423 }, 8424 { 8425 "default": "hosts", 8426 "maxLength": 64, 8427 "type": "string" 8428 } 8429 ] 8430 }, 8431 "rt": { 8432 "description": "Resource Type of the Resource", 8433 "items": { 8434 "maxLength": 64, 8435 "type": "string" 8436 }, 8437 "minItems": 1, 8438 "type": "array" 8439 }, 8440 "title": { 8441 "description": "A title for the link relation. Can be used by the UI to 8442 provide a context.", 8443 "maxLength": 64, 8444 "type": "string" 8445 }, 8446 "type": { 8447 "default": "application/cbor", 8448 "description": "A hint at the representation of the resource referenced by 8449 the target URI. This represents the media types that are used for both accepting and emitting.", 8450 "items": { 8451 "maxLength": 64, 8452 "type": "string" 8453 }, 8454 "minItems": 1, 8455 "type": "array" 8456 } 8457 }, 8458 "required": [ 8459 "href", 8460 "rt", 8461 "if" 8462 ], 8463 "type": "object" 8464 }, 8465 "type": "array" 8466 } 8467 ] 8468 }, 8469 "n": { 8470 "description": "Friendly name of the resource", 8471 "maxLength": 64, 8472 "readOnly": true, 8473 "type": "string" 8474 }, 8475 "p": { 8476 "description": "Specifies the framework policies on the Resource referenced by the 8477 target URI", 8478 "properties": { 8479 "bm": { 8480 "description": "Specifies the framework policies on the Resource referenced by 8481 the target URI for e.g. observable and discoverable", 8482 "type": "integer" 8483 } 8484 }, 8485 "required": [ 8486 "bm" 8487 ], 8488


"type": "object" 8489 }, 8490 "rel": { 8491 "description": "The relation of the target URI referenced by the link to the context 8492 URI", 8493 "oneOf": [ 8494 { 8495 "default": [ 8496 "hosts" 8497 ], 8498 "items": { 8499 "maxLength": 64, 8500 "type": "string" 8501 }, 8502 "minItems": 1, 8503 "type": "array" 8504 }, 8505 { 8506 "default": "hosts", 8507 "maxLength": 64, 8508 "type": "string" 8509 } 8510 ] 8511 }, 8512 "rt": { 8513 "description": "Resource Type of the Resource", 8514 "items": { 8515 "maxLength": 64, 8516 "type": "string" 8517 }, 8518 "minItems": 1, 8519 "type": "array" 8520 }, 8521 "rts": { 8522 "allOf": [ 8523 { 8524 "description": "Resource Type of the Resource", 8525 "items": { 8526 "maxLength": 64, 8527 "type": "string" 8528 }, 8529 "minItems": 1, 8530 "readOnly": true, 8531 "type": "array" 8532 }, 8533 { 8534 "description": "The list of allowable resource types (for Target and anchors) in 8535 links included in the collection" 8536 } 8537 ] 8538 }, 8539 "title": { 8540 "description": "A title for the link relation. Can be used by the UI to provide a 8541 context.", 8542 "maxLength": 64, 8543 "type": "string" 8544 }, 8545 "type": { 8546 "default": "application/cbor", 8547 "description": "A hint at the representation of the resource referenced by the target 8548 URI. This represents the media types that are used for both accepting and emitting.", 8549 "items": { 8550 "maxLength": 64, 8551 "type": "string" 8552 }, 8553 "minItems": 1, 8554 "type": "array" 8555 } 8556 }, 8557 "required": [ 8558 "href", 8559


"rt", 8560 "if" 8561 ], 8562 "type": "object" 8563 }, 8564 "type": "array" 8565 } 8566 8567 , 8568 "sbatch-retrieve" : 8569 { 8570 "items": { 8571 "additionalProperties": true, 8572 "properties": { 8573 "href": { 8574 "description": "URI of the target resource relative assuming the collection URI as 8575 anchor", 8576 "format": "uri", 8577 "maxLength": 256, 8578 "type": "string" 8579 }, 8580 "rep": { 8581 "oneOf": [ 8582 { 8583 "description": "The response payload from a single resource", 8584 "type": "object" 8585 }, 8586 { 8587 "description": " The response payload from a collection (batch) resource", 8588 "type": "array" 8589 } 8590 ] 8591 } 8592 }, 8593 "required": [ 8594 "href", 8595 "rep" 8596 ], 8597 "type": "object" 8598 }, 8599 "minItems": 1, 8600 "type": "array" 8601 } 8602 8603 , 8604 "sbatch-update" : 8605 { 8606 "description": "array of resource representations to apply to the batch collection, using 8607 href to indicate which resource(s) in the batch to update. If the href property is empty, 8608 effectively making the URI reference to the collection itself, the representation is to be applied 8609 to all resources in the batch", 8610 "items": { 8611 "additionalProperties": true, 8612 "properties": { 8613 "href": { 8614 "description": "URI of the target resource relative assuming the collection URI as 8615 anchor", 8616 "format": "uri", 8617 "maxLength": 256, 8618 "type": "string" 8619 }, 8620 "rep": { 8621 "oneOf": [ 8622 { 8623 "description": "The response payload from a single resource", 8624 "type": "object" 8625 }, 8626 { 8627 "description": " The response payload from a collection (batch) resource", 8628 "type": "array" 8629 } 8630


] 8631 } 8632 }, 8633 "required": [ 8634 "href", 8635 "rep" 8636 ], 8637 "type": "object" 8638 }, 8639 "minItems": 1, 8640 "type": "array" 8641 } 8642 8643 , 8644 "slinks" : 8645 { 8646 "description": "All forms of links in a collection.", 8647 "oneOf": [ 8648 { 8649 "description": "A set of simple or individual OIC Links.", 8650 "items": { 8651 "properties": { 8652 "anchor": { 8653 "description": "This is used to override the context URI e.g. override the URI of 8654 the containing collection.", 8655 "format": "uri", 8656 "maxLength": 256, 8657 "type": "string" 8658 }, 8659 "di": { 8660 "allOf": [ 8661 { 8662 "description": "Format pattern according to IETF RFC 4122.", 8663 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-8664 fA-F0-9]{12}$", 8665 "type": "string" 8666 }, 8667 { 8668 "description": "The device ID" 8669 } 8670 ] 8671 }, 8672 "eps": { 8673 "description": "the Endpoint information of the target Resource", 8674 "items": { 8675 "properties": { 8676 "ep": { 8677 "description": "Transport Protocol Suite + Endpoint Locator", 8678 "format": "uri", 8679 "type": "string" 8680 }, 8681 "pri": { 8682 "description": "The priority among multiple Endpoints", 8683 "minimum": 1, 8684 "type": "integer" 8685 } 8686 }, 8687 "type": "object" 8688 }, 8689 "type": "array" 8690 }, 8691 "href": { 8692 "description": "This is the target URI, it can be specified as a Relative 8693 Reference or fully-qualified URI.", 8694 "format": "uri", 8695 "maxLength": 256, 8696 "type": "string" 8697 }, 8698 "if": { 8699 "description": "The interface set supported by this resource", 8700 "items": { 8701


"enum": [ 8702 "oic.if.baseline", 8703 "oic.if.ll", 8704 "oic.if.b", 8705 "oic.if.rw", 8706 "oic.if.r", 8707 "oic.if.a", 8708 "oic.if.s" 8709 ], 8710 "type": "string" 8711 }, 8712 "minItems": 1, 8713 "type": "array" 8714 }, 8715 "ins": { 8716 "description": "The instance identifier for this web link in an array of web 8717 links - used in collections", 8718 "oneOf": [ 8719 { 8720 "description": "An ordinal number that is not repeated - must be unique in 8721 the collection context.", 8722 "type": "integer" 8723 }, 8724 { 8725 "description": "A unique string", 8726 "format": "uri", 8727 "maxLength": 256, 8728 "type": "string" 8729 }, 8730 { 8731 "allOf": [ 8732 { 8733 "description": "Format pattern according to IETF RFC 4122.", 8734 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-8735 [a-fA-F0-9]{12}$", 8736 "type": "string" 8737 }, 8738 { 8739 "description": "A UUID" 8740 } 8741 ] 8742 } 8743 ] 8744 }, 8745 "p": { 8746 "description": "Specifies the framework policies on the Resource referenced by 8747 the target URI", 8748 "properties": { 8749 "bm": { 8750 "description": "Specifies the framework policies on the Resource referenced 8751 by the target URI for e.g. observable and discoverable", 8752 "type": "integer" 8753 } 8754 }, 8755 "required": [ 8756 "bm" 8757 ], 8758 "type": "object" 8759 }, 8760 "rel": { 8761 "description": "The relation of the target URI referenced by the link to the 8762 context URI", 8763 "oneOf": [ 8764 { 8765 "default": [ 8766 "hosts" 8767 ], 8768 "items": { 8769 "maxLength": 64, 8770 "type": "string" 8771 }, 8772


"minItems": 1, 8773 "type": "array" 8774 }, 8775 { 8776 "default": "hosts", 8777 "maxLength": 64, 8778 "type": "string" 8779 } 8780 ] 8781 }, 8782 "rt": { 8783 "description": "Resource Type of the Resource", 8784 "items": { 8785 "maxLength": 64, 8786 "type": "string" 8787 }, 8788 "minItems": 1, 8789 "type": "array" 8790 }, 8791 "title": { 8792 "description": "A title for the link relation. Can be used by the UI to provide a 8793 context.", 8794 "maxLength": 64, 8795 "type": "string" 8796 }, 8797 "type": { 8798 "default": "application/cbor", 8799 "description": "A hint at the representation of the resource referenced by the 8800 target URI. This represents the media types that are used for both accepting and emitting.", 8801 "items": { 8802 "maxLength": 64, 8803 "type": "string" 8804 }, 8805 "minItems": 1, 8806 "type": "array" 8807 } 8808 }, 8809 "required": [ 8810 "href", 8811 "rt", 8812 "if" 8813 ], 8814 "type": "object" 8815 }, 8816 "type": "array" 8817 } 8818 ] 8819 } 8820 8821 } 8822 } 8823 8824


Property name Value type Mandatory Access mode Description href string yes This is the target

URI, it can be specified as a Relative Reference or fully-qualified URI.

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


of the containing collection.


Specifies the framework policies on the Resource referenced by the target URI


yes The interface set supported by this resource


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


title string A title for the link relation. Can be used by the UI to provide a context.


The instance identifier for this web link in an array of web links - used in collections


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 of the Resource


the Endpoint information of the target Resource

links multiple types: see schema

All forms of links in a collection.







href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI.




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














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

rep multiple types: see schema

yes

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

rep multiple types: see schema

yes



F.4 Platform Configuration 8827


Resource that allows for platform specific information to be configured. 8829 Retrieves the current platform configuration settings 8830 8831


/example/PlatformConfigurationResURI 8833


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


{ 8837 "swagger": "2.0", 8838 "info": { 8839 "title": "Platform Configuration", 8840 "version": "v1-20160622", 8841 "license": { 8842 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 8843 "x-description": "Redistribution and use in source and binary forms, with or without 8844 modification, are permitted provided that the following conditions are met:\n 1. 8845 Redistributions of source code must retain the above copyright notice, this list of conditions and 8846 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 8847 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 8848 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 8849 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 8850 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 8851 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 8852 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 8853 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 8854 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 8855 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 8856 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 8857 OF SUCH DAMAGE.\n" 8858 } 8859 }, 8860 "schemes": ["http"], 8861 "consumes": ["application/json"], 8862 "produces": ["application/json"], 8863 "paths": { 8864 "/example/PlatformConfigurationResURI" : { 8865


"get": { 8866 "description": "Resource that allows for platform specific information to be 8867 configured.\nRetrieves the current platform configuration settings\n", 8868 "parameters": [ 8869 {"$ref": "#/parameters/interface-all"} 8870 ], 8871 "responses": { 8872 "200": { 8873 "description" : "", 8874 "x-example": 8875 { 8876 "rt": ["oic.wk.con.p"], 8877 "mnpn": [ { "language": "en", "value": "My Friendly Device Name" } ] 8878 } 8879 , 8880 "schema": { "$ref": "#/definitions/Conf_Platform" } 8881 } 8882 } 8883 }, 8884 "post": { 8885 "description": "Update the information about the platform\n", 8886 "parameters": [ 8887 {"$ref": "#/parameters/interface-rw"}, 8888 { 8889 "name": "body", 8890 "in": "body", 8891 "required": true, 8892 "schema": { "$ref": "#/definitions/Update_Platform" }, 8893 "x-example": 8894 { 8895 "n": "Nuevo nombre", 8896 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 8897 } 8898 } 8899 ], 8900 "responses": { 8901 "200": { 8902 "description" : "", 8903 "x-example": 8904 { 8905 "n": "Nuevo nombre", 8906 "mnpn": [ { "language": "es", "value": "Nuevo nombre de Plataforma Amigable" } ] 8907 } 8908 , 8909 "schema": { "$ref": "#/definitions/Update_Platform" } 8910 } 8911 } 8912 } 8913 } 8914 }, 8915 "parameters": { 8916 "interface-rw" : { 8917 "in" : "query", 8918 "name" : "if", 8919 "type" : "string", 8920 "enum" : ["oic.if.rw"] 8921 }, 8922 "interface-all" : { 8923 "in" : "query", 8924 "name" : "if", 8925 "type" : "string", 8926 "enum" : ["oic.if.rw", "oic.if.baseline"] 8927 } 8928 }, 8929 "definitions": { 8930 "Conf_Platform" : 8931 { 8932 "properties": { 8933 "id": { 8934 "anyOf": [ 8935 { 8936


"maxLength": 64, 8937 "type": "string" 8938 }, 8939 { 8940 "description": "Format pattern according to IETF RFC 4122.", 8941 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-8942 9]{12}$", 8943 "type": "string" 8944 } 8945 ], 8946 "description": "Instance ID of this specific resource", 8947 "readOnly": true 8948 }, 8949 "if": { 8950 "description": "The interface set supported by this resource", 8951 "items": { 8952 "enum": [ 8953 "oic.if.baseline", 8954 "oic.if.ll", 8955 "oic.if.b", 8956 "oic.if.lb", 8957 "oic.if.rw", 8958 "oic.if.r", 8959 "oic.if.a", 8960 "oic.if.s" 8961 ], 8962 "type": "string" 8963 }, 8964 "minItems": 1, 8965 "readOnly": true, 8966 "type": "array" 8967 }, 8968 "mnpn": { 8969 "description": "Platform names", 8970 "items": { 8971 "properties": { 8972 "language": { 8973 "allOf": [ 8974 { 8975 "description": "Format pattern according to IETF RFC 5646 (language tag).", 8976 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 8977 "type": "string" 8978 }, 8979 { 8980 "description": "An RFC 5646 language tag." 8981 } 8982 ] 8983 }, 8984 "value": { 8985 "description": "The Platform description in the indicated language.", 8986 "maxLength": 64, 8987 "type": "string" 8988 } 8989 }, 8990 "type": "object" 8991 }, 8992 "minItems": 1, 8993 "type": "array" 8994 }, 8995 "n": { 8996 "description": "Friendly name of the resource", 8997 "maxLength": 64, 8998 "readOnly": true, 8999 "type": "string" 9000 }, 9001 "rt": { 9002 "description": "Resource Type of the Resource", 9003 "items": { 9004 "maxLength": 64, 9005 "type": "string" 9006 }, 9007


"minItems": 1, 9008 "readOnly": true, 9009 "type": "array" 9010 } 9011 }, 9012 "type": "object" 9013 } 9014 9015 , 9016 "Update_Platform" : 9017 { 9018 "properties": { 9019 "id": { 9020 "anyOf": [ 9021 { 9022 "maxLength": 64, 9023 "type": "string" 9024 }, 9025 { 9026 "description": "Format pattern according to IETF RFC 4122.", 9027 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9028 9]{12}$", 9029 "type": "string" 9030 } 9031 ], 9032 "description": "Instance ID of this specific resource", 9033 "readOnly": true 9034 }, 9035 "if": { 9036 "description": "The interface set supported by this resource", 9037 "items": { 9038 "enum": [ 9039 "oic.if.baseline", 9040 "oic.if.ll", 9041 "oic.if.b", 9042 "oic.if.lb", 9043 "oic.if.rw", 9044 "oic.if.r", 9045 "oic.if.a", 9046 "oic.if.s" 9047 ], 9048 "type": "string" 9049 }, 9050 "minItems": 1, 9051 "readOnly": true, 9052 "type": "array" 9053 }, 9054 "mnpn": { 9055 "description": "Platform names", 9056 "items": { 9057 "properties": { 9058 "language": { 9059 "allOf": [ 9060 { 9061 "description": "Format pattern according to IETF RFC 5646 (language tag).", 9062 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 9063 "type": "string" 9064 }, 9065 { 9066 "description": "An RFC 5646 language tag." 9067 } 9068 ] 9069 }, 9070 "value": { 9071 "description": "The Platform description in the indicated language.", 9072 "maxLength": 64, 9073 "type": "string" 9074 } 9075 }, 9076 "type": "object" 9077 }, 9078


"minItems": 1, 9079 "type": "array" 9080 }, 9081 "n": { 9082 "description": "Friendly name of the resource", 9083 "maxLength": 64, 9084 "type": "string" 9085 }, 9086 "rt": { 9087 "description": "Resource Type of the Resource", 9088 "items": { 9089 "maxLength": 64, 9090 "type": "string" 9091 }, 9092 "minItems": 1, 9093 "readOnly": true, 9094 "type": "array" 9095 } 9096 }, 9097 "required": [ 9098 "mnpn" 9099 ], 9100 "type": "object" 9101 } 9102 9103 } 9104 } 9105 9106



schema Read Only Resource Type

of the Resource if array: see






mnpn array: see schema

Platform names





n string Friendly name of the resource



mnpn array: see schema

yes Platform names


Resource Create Read Update Delete Notify /example/PlatformConfigurationResURI get post


F.5 Device Configuration 9109


Resource that allows for Device specific information to be configured. 9111 Retrieves the current Device configuration settings 9112 9113


/example/DeviceConfigurationResURI 9115


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


{ 9119 "swagger": "2.0", 9120 "info": { 9121 "title": "Device Configuration", 9122 "version": "v1-20160622", 9123 "license": { 9124 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 9125 "x-description": "Redistribution and use in source and binary forms, with or without 9126 modification, are permitted provided that the following conditions are met:\n 1. 9127 Redistributions of source code must retain the above copyright notice, this list of conditions and 9128 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 9129 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 9130 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 9131 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 9132 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 9133 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 9134 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 9135 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 9136 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 9137 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 9138 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 9139 OF SUCH DAMAGE.\n" 9140 } 9141 }, 9142 "schemes": ["http"], 9143 "consumes": ["application/json"], 9144 "produces": ["application/json"], 9145 "paths": { 9146 "/example/DeviceConfigurationResURI" : { 9147 "get": { 9148 "description": "Resource that allows for Device specific information to be 9149 configured.\nRetrieves the current Device configuration settings\n", 9150 "parameters": [ 9151 {"$ref": "#/parameters/interface-all"} 9152 ], 9153 "responses": { 9154 "200": { 9155 "description" : "", 9156 "x-example": 9157 { 9158 "n": "My Friendly Device Name", 9159 "rt": ["oic.wk.con"], 9160 "loc": [32.777,-96.797], 9161 "locn": "My Location Name", 9162 "c": "USD", 9163 "r": "MyRegion", 9164 "dl": "en" 9165 } 9166 , 9167 "schema": { "$ref": "#/definitions/Configuration" } 9168 } 9169 } 9170 }, 9171


"post": { 9172 "description": "Update the information about the Device\n", 9173 "parameters": [ 9174 {"$ref": "#/parameters/interface-rw"}, 9175 { 9176 "name": "body", 9177 "in": "body", 9178 "required": true, 9179 "schema": { "$ref": "#/definitions/Update" }, 9180 "x-example": 9181 { 9182 "n": "Nuevo Nombre Amistoso", 9183 "r": "MyNewRegion", 9184 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 9185 "dl": "es" 9186 } 9187 } 9188 ], 9189 "responses": { 9190 "200": { 9191 "description" : "", 9192 "x-example": 9193 { 9194 "n": "Nuevo Nombre Amistoso", 9195 "r": "MyNewRegion", 9196 "ln": [ { "language": "es", "value": "Nuevo Nombre Amistoso" } ], 9197 "dl": "es" 9198 } 9199 , 9200 "schema": { "$ref": "#/definitions/Update" } 9201 } 9202 } 9203 } 9204 } 9205 }, 9206 "parameters": { 9207 "interface-rw" : { 9208 "in" : "query", 9209 "name" : "if", 9210 "type" : "string", 9211 "enum" : ["oic.if.rw"] 9212 }, 9213 "interface-all" : { 9214 "in" : "query", 9215 "name" : "if", 9216 "type" : "string", 9217 "enum" : ["oic.if.rw", "oic.if.baseline"] 9218 } 9219 }, 9220 "definitions": { 9221 "Configuration" : 9222 { 9223 "properties": { 9224 "c": { 9225 "description": "Currency", 9226 "maxLength": 64, 9227 "type": "string" 9228 }, 9229 "dl": { 9230 "allOf": [ 9231 { 9232 "description": "Format pattern according to IETF RFC 5646 (language tag).", 9233 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 9234 "type": "string" 9235 }, 9236 { 9237 "description": "Default Language as an RFC 5646 language tag." 9238 } 9239 ] 9240 }, 9241 "id": { 9242


"anyOf": [ 9243 { 9244 "maxLength": 64, 9245 "type": "string" 9246 }, 9247 { 9248 "description": "Format pattern according to IETF RFC 4122.", 9249 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9250 9]{12}$", 9251 "type": "string" 9252 } 9253 ], 9254 "description": "Instance ID of this specific resource", 9255 "readOnly": true 9256 }, 9257 "if": { 9258 "description": "The interface set supported by this resource", 9259 "items": { 9260 "enum": [ 9261 "oic.if.baseline", 9262 "oic.if.ll", 9263 "oic.if.b", 9264 "oic.if.lb", 9265 "oic.if.rw", 9266 "oic.if.r", 9267 "oic.if.a", 9268 "oic.if.s" 9269 ], 9270 "type": "string" 9271 }, 9272 "minItems": 1, 9273 "readOnly": true, 9274 "type": "array" 9275 }, 9276 "ln": { 9277 "description": "Localized names", 9278 "items": { 9279 "properties": { 9280 "language": { 9281 "allOf": [ 9282 { 9283 "description": "Format pattern according to IETF RFC 5646 (language tag).", 9284 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 9285 "type": "string" 9286 }, 9287 { 9288 "description": "An RFC 5646 language tag." 9289 } 9290 ] 9291 }, 9292 "value": { 9293 "description": "The Device name in the indicated language.", 9294 "maxLength": 64, 9295 "type": "string" 9296 } 9297 }, 9298 "type": "object" 9299 }, 9300 "minItems": 1, 9301 "type": "array" 9302 }, 9303 "loc": { 9304 "description": "Location information (lat, long)", 9305 "items": { 9306 "type": "number" 9307 }, 9308 "maxItems": 2, 9309 "minItems": 2, 9310 "type": "array" 9311 }, 9312 "locn": { 9313


"description": "Human Friendly Name for location", 9314 "maxLength": 64, 9315 "type": "string" 9316 }, 9317 "n": { 9318 "description": "Friendly name of the resource", 9319 "maxLength": 64, 9320 "readOnly": true, 9321 "type": "string" 9322 }, 9323 "r": { 9324 "description": "Region", 9325 "maxLength": 64, 9326 "type": "string" 9327 }, 9328 "rt": { 9329 "description": "Resource Type of the Resource", 9330 "items": { 9331 "maxLength": 64, 9332 "type": "string" 9333 }, 9334 "minItems": 1, 9335 "readOnly": true, 9336 "type": "array" 9337 } 9338 }, 9339 "required": [ 9340 "n" 9341 ], 9342 "type": "object" 9343 } 9344 9345 , 9346 "Update" : 9347 { 9348 "properties": { 9349 "c": { 9350 "description": "Currency", 9351 "maxLength": 64, 9352 "type": "string" 9353 }, 9354 "dl": { 9355 "allOf": [ 9356 { 9357 "description": "Format pattern according to IETF RFC 5646 (language tag).", 9358 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 9359 "type": "string" 9360 }, 9361 { 9362 "description": "Default Language as an RFC 5646 language tag." 9363 } 9364 ] 9365 }, 9366 "id": { 9367 "anyOf": [ 9368 { 9369 "maxLength": 64, 9370 "type": "string" 9371 }, 9372 { 9373 "description": "Format pattern according to IETF RFC 4122.", 9374 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9375 9]{12}$", 9376 "type": "string" 9377 } 9378 ], 9379 "description": "Instance ID of this specific resource", 9380 "readOnly": true 9381 }, 9382 "if": { 9383 "description": "The interface set supported by this resource", 9384


"items": { 9385 "enum": [ 9386 "oic.if.baseline", 9387 "oic.if.ll", 9388 "oic.if.b", 9389 "oic.if.lb", 9390 "oic.if.rw", 9391 "oic.if.r", 9392 "oic.if.a", 9393 "oic.if.s" 9394 ], 9395 "type": "string" 9396 }, 9397 "minItems": 1, 9398 "readOnly": true, 9399 "type": "array" 9400 }, 9401 "ln": { 9402 "description": "Localized names", 9403 "items": { 9404 "properties": { 9405 "language": { 9406 "allOf": [ 9407 { 9408 "description": "Format pattern according to IETF RFC 5646 (language tag).", 9409 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 9410 "type": "string" 9411 }, 9412 { 9413 "description": "An RFC 5646 language tag." 9414 } 9415 ] 9416 }, 9417 "value": { 9418 "description": "The Device name in the indicated language.", 9419 "maxLength": 64, 9420 "type": "string" 9421 } 9422 }, 9423 "type": "object" 9424 }, 9425 "minItems": 1, 9426 "type": "array" 9427 }, 9428 "loc": { 9429 "description": "Location information (lat, long)", 9430 "items": { 9431 "type": "number" 9432 }, 9433 "maxItems": 2, 9434 "minItems": 2, 9435 "type": "array" 9436 }, 9437 "locn": { 9438 "description": "Human Friendly Name for location", 9439 "maxLength": 64, 9440 "type": "string" 9441 }, 9442 "n": { 9443 "description": "Friendly name of the resource", 9444 "maxLength": 64, 9445 "type": "string" 9446 }, 9447 "r": { 9448 "description": "Region", 9449 "maxLength": 64, 9450 "type": "string" 9451 }, 9452 "rt": { 9453 "description": "Resource Type of the Resource", 9454 "items": { 9455


"maxLength": 64, 9456 "type": "string" 9457 }, 9458 "minItems": 1, 9459 "readOnly": true, 9460 "type": "array" 9461 } 9462 }, 9463 "required": [ 9464 "n" 9465 ], 9466 "type": "object" 9467 } 9468 9469 } 9470 } 9471 9472


Property name Value type Mandatory Access mode Description loc array: see

schema Location

information (lat, long)

c string Currency rt array: see


of the Resource id multiple types:

see schema Read Only Instance ID of

this specific resource



r string Region ln array: see

schema Localized names

locn string Human Friendly Name for location

n string yes Friendly name of the resource


loc array: see schema

Location information (lat, long)

c string Currency rt array: see


of the Resource id multiple types:





r string Region ln array: see

schema Localized names


locn string Human Friendly Name for location

n string yes Read Only Friendly name of the resource



Resource Create Read Update Delete Notify /example/DeviceConfigurationResURI get post

F.6 Device 9475


Known resource that is hosted by every Server. 9477 Allows for logical device specific information to be discovered. 9478 Retrieve the information about the Device 9479 9480


/oic/d 9482


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


{ 9486 "swagger": "2.0", 9487 "info": { 9488 "title": "Device", 9489 "version": "v1-20160622", 9490 "license": { 9491 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 9492 "x-description": "Redistribution and use in source and binary forms, with or without 9493 modification, are permitted provided that the following conditions are met:\n 1. 9494 Redistributions of source code must retain the above copyright notice, this list of conditions and 9495 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 9496 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 9497 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 9498 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 9499 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 9500 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 9501 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 9502 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 9503 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 9504 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 9505 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 9506 OF SUCH DAMAGE.\n" 9507 } 9508 }, 9509 "schemes": ["http"], 9510 "consumes": ["application/json"], 9511 "produces": ["application/json"], 9512 "paths": { 9513 "/oic/d" : { 9514 "get": { 9515 "description": "Known resource that is hosted by every Server.\nAllows for logical device 9516 specific information to be discovered.\nRetrieve the information about the Device\n", 9517 "parameters": [ 9518 {"$ref": "#/parameters/interface"} 9519 ], 9520 "responses": { 9521 "200": { 9522


"description" : "", 9523 "x-example": 9524 { 9525 "n": "Device 1", 9526 "rt": ["oic.wk.d"], 9527 "di": "54919CA5-4101-4AE4-595B-353C51AA983C", 9528 "icv": "ocf.1.0.0", 9529 "dmv": "ocf.res.1.0.0, ocf.sh.1.0.0", 9530 "piid": "6F0AAC04-2BB0-468D-B57C-16570A26AE48" 9531 } 9532 , 9533 "schema": { "$ref": "#/definitions/Device" } 9534 } 9535 } 9536 } 9537 } 9538 }, 9539 "parameters": { 9540 "interface" : { 9541 "in" : "query", 9542 "name" : "if", 9543 "type" : "string", 9544 "enum" : ["oic.if.r", "oic.if.baseline"] 9545 } 9546 }, 9547 "definitions": { 9548 "Device" : 9549 { 9550 "properties": { 9551 "di": { 9552 "allOf": [ 9553 { 9554 "description": "Format pattern according to IETF RFC 4122.", 9555 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9556 9]{12}$", 9557 "type": "string" 9558 }, 9559 { 9560 "description": "Unique identifier for device", 9561 "readOnly": true 9562 } 9563 ] 9564 }, 9565 "dmn": { 9566 "description": "Manufacturer Name.", 9567 "items": { 9568 "properties": { 9569 "language": { 9570 "allOf": [ 9571 { 9572 "description": "Format pattern according to IETF RFC 5646 (language tag).", 9573 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 9574 "type": "string" 9575 }, 9576 { 9577 "description": "An RFC 5646 language tag.", 9578 "readOnly": true 9579 } 9580 ] 9581 }, 9582 "value": { 9583 "description": "Manufacturer name in the indicated language.", 9584 "maxLength": 64, 9585 "readOnly": true, 9586 "type": "string" 9587 } 9588 }, 9589 "type": "object" 9590 }, 9591 "minItems": 1, 9592 "readOnly": true, 9593


"type": "array" 9594 }, 9595 "dmno": { 9596 "description": "Model number as designated by manufacturer.", 9597 "maxLength": 64, 9598 "readOnly": true, 9599 "type": "string" 9600 }, 9601 "dmv": { 9602 "description": "Spec versions of the Resource and Device Specifications to which this 9603 device data model is implemented", 9604 "maxLength": 256, 9605 "readOnly": true, 9606 "type": "string" 9607 }, 9608 "icv": { 9609 "description": "The version of the OIC Server", 9610 "maxLength": 64, 9611 "readOnly": true, 9612 "type": "string" 9613 }, 9614 "id": { 9615 "anyOf": [ 9616 { 9617 "maxLength": 64, 9618 "type": "string" 9619 }, 9620 { 9621 "description": "Format pattern according to IETF RFC 4122.", 9622 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9623 9]{12}$", 9624 "type": "string" 9625 } 9626 ], 9627 "description": "Instance ID of this specific resource", 9628 "readOnly": true 9629 }, 9630 "if": { 9631 "description": "The interface set supported by this resource", 9632 "items": { 9633 "enum": [ 9634 "oic.if.baseline", 9635 "oic.if.ll", 9636 "oic.if.b", 9637 "oic.if.lb", 9638 "oic.if.rw", 9639 "oic.if.r", 9640 "oic.if.a", 9641 "oic.if.s" 9642 ], 9643 "type": "string" 9644 }, 9645 "minItems": 1, 9646 "readOnly": true, 9647 "type": "array" 9648 }, 9649 "ld": { 9650 "description": "Localized Descriptions.", 9651 "items": { 9652 "properties": { 9653 "language": { 9654 "allOf": [ 9655 { 9656 "description": "Format pattern according to IETF RFC 5646 (language tag).", 9657 "pattern": "^[A-Za-z]{1,8}(-[A-Za-z0-9]{1,8})*$", 9658 "type": "string" 9659 }, 9660 { 9661 "description": "An RFC 5646 language tag.", 9662 "readOnly": true 9663 } 9664


] 9665 }, 9666 "value": { 9667 "description": "Device description in the indicated language.", 9668 "maxLength": 64, 9669 "readOnly": true, 9670 "type": "string" 9671 } 9672 }, 9673 "type": "object" 9674 }, 9675 "minItems": 1, 9676 "readOnly": true, 9677 "type": "array" 9678 }, 9679 "n": { 9680 "description": "Friendly name of the resource", 9681 "maxLength": 64, 9682 "readOnly": true, 9683 "type": "string" 9684 }, 9685 "piid": { 9686 "allOf": [ 9687 { 9688 "description": "Format pattern according to IETF RFC 4122.", 9689 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9690 9]{12}$", 9691 "type": "string" 9692 }, 9693 { 9694 "description": "Protocol independent unique identifier for device that is 9695 immutable.", 9696 "readOnly": true 9697 } 9698 ] 9699 }, 9700 "rt": { 9701 "description": "Resource Type of the Resource", 9702 "items": { 9703 "maxLength": 64, 9704 "type": "string" 9705 }, 9706 "minItems": 1, 9707 "readOnly": true, 9708 "type": "array" 9709 }, 9710 "sv": { 9711 "description": "Software version.", 9712 "maxLength": 64, 9713 "readOnly": true, 9714 "type": "string" 9715 } 9716 }, 9717 "required": [ 9718 "n", 9719 "di", 9720 "icv", 9721 "dmv", 9722 "piid" 9723 ], 9724 "type": "object" 9725 } 9726 9727 } 9728 } 9729 9730


Property name Value type Mandatory Access mode Description


n string yes Read Only Friendly name of the resource

sv string Read Only Software version.

dmn array: see schema

Read Only Manufacturer Name.



dmno string Read Only Model number as designated by manufacturer.

ld array: see schema

Read Only Localized Descriptions.



piid multiple types: see schema

yes

icv string yes Read Only The version of the OIC Server


yes

dmv string yes Read Only Spec versions of the Resource and Device Specifications to which this device data model is implemented




Resource Create Read Update Delete Notify /oic/d get

F.7 Maintenance 9733


The resource through which a Device is maintained and can be used for diagnostic purposes. 9735 fr (Factory Reset) is a boolean. 9736 The value 0 means No action (Default), the value 1 means Start Factory Reset 9737 After factory reset, this value shall be changed back to the default value 9738 rb (Reboot) is a boolean. 9739 The value 0 means No action (Default), the value 1 means Start Reboot 9740 After Reboot, this value shall be changed back to the default value 9741 Retrieve the maintenance action status 9742


/oic/mnt 9744


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



{ 9748 "swagger": "2.0", 9749 "info": { 9750 "title": "Maintenance", 9751 "version": "v1-20160622", 9752 "license": { 9753 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 9754 "x-description": "Redistribution and use in source and binary forms, with or without 9755 modification, are permitted provided that the following conditions are met:\n 1. 9756 Redistributions of source code must retain the above copyright notice, this list of conditions and 9757 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 9758 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 9759 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 9760 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 9761 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 9762 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 9763 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 9764 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 9765 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 9766 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 9767 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 9768 OF SUCH DAMAGE.\n" 9769 } 9770 }, 9771 "schemes": ["http"], 9772 "consumes": ["application/json"], 9773 "produces": ["application/json"], 9774 "paths": { 9775 "/oic/mnt" : { 9776 "get": { 9777 "description": "The resource through which a Device is maintained and can be used for 9778 diagnostic purposes.\nfr (Factory Reset) is a boolean.\n The value 0 means No action (Default), 9779 the value 1 means Start Factory Reset\nAfter factory reset, this value shall be changed back to the 9780 default value\nrb (Reboot) is a boolean.\n The value 0 means No action (Default), the value 1 9781 means Start Reboot\nAfter Reboot, this value shall be changed back to the default value\nRetrieve 9782 the maintenance action status", 9783 "parameters": [ 9784 {"$ref": "#/parameters/interface-all"} 9785 ], 9786 "responses": { 9787 "200": { 9788 "description" : "", 9789 "x-example": 9790 { 9791 "rt": ["oic.wk.mnt"], 9792 "fr": false, 9793 "rb": false 9794 } 9795 , 9796 "schema": { "$ref": "#/definitions/MNT" } 9797 } 9798 } 9799 }, 9800 "post": { 9801 "description": "Set the maintenance action(s)\n", 9802 "parameters": [ 9803 {"$ref": "#/parameters/interface-rw"}, 9804 { 9805 "name": "body", 9806 "in": "body", 9807 "required": true, 9808 "schema": { "$ref": "#/definitions/MNT" }, 9809 "x-example": 9810 { 9811 "fr": false, 9812 "rb": false 9813 } 9814 } 9815 ], 9816


"responses": { 9817 "200": { 9818 "description" : "", 9819 "x-example": 9820 { 9821 "fr": false, 9822 "rb": false 9823 } 9824 , 9825 "schema": { "$ref": "#/definitions/MNT" } 9826 } 9827 } 9828 } 9829 } 9830 }, 9831 "parameters": { 9832 "interface-rw" : { 9833 "in" : "query", 9834 "name" : "if", 9835 "type" : "string", 9836 "enum" : ["oic.if.rw", "oic.if.baseline"] 9837 }, 9838 "interface-all" : { 9839 "in" : "query", 9840 "name" : "if", 9841 "type" : "string", 9842 "enum" : ["oic.if.rw", "oic.if.r", "oic.if.baseline"] 9843 } 9844 }, 9845 "definitions": { 9846 "MNT" : 9847 { 9848 "anyOf": [ 9849 { 9850 "required": [ 9851 "fr" 9852 ] 9853 }, 9854 { 9855 "required": [ 9856 "rb" 9857 ] 9858 } 9859 ], 9860 "properties": { 9861 "fr": { 9862 "description": "Factory Reset", 9863 "type": "boolean" 9864 }, 9865 "id": { 9866 "anyOf": [ 9867 { 9868 "maxLength": 64, 9869 "type": "string" 9870 }, 9871 { 9872 "description": "Format pattern according to IETF RFC 4122.", 9873 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9874 9]{12}$", 9875 "type": "string" 9876 } 9877 ], 9878 "description": "Instance ID of this specific resource", 9879 "readOnly": true 9880 }, 9881 "if": { 9882 "description": "The interface set supported by this resource", 9883 "items": { 9884 "enum": [ 9885 "oic.if.baseline", 9886 "oic.if.ll", 9887


"oic.if.b", 9888 "oic.if.lb", 9889 "oic.if.rw", 9890 "oic.if.r", 9891 "oic.if.a", 9892 "oic.if.s" 9893 ], 9894 "type": "string" 9895 }, 9896 "minItems": 1, 9897 "readOnly": true, 9898 "type": "array" 9899 }, 9900 "n": { 9901 "description": "Friendly name of the resource", 9902 "maxLength": 64, 9903 "readOnly": true, 9904 "type": "string" 9905 }, 9906 "rb": { 9907 "description": "Reboot Action", 9908 "type": "boolean" 9909 }, 9910 "rt": { 9911 "description": "Resource Type of the Resource", 9912 "items": { 9913 "maxLength": 64, 9914 "type": "string" 9915 }, 9916 "minItems": 1, 9917 "readOnly": true, 9918 "type": "array" 9919 } 9920 }, 9921 "type": "object" 9922 } 9923 9924 } 9925 } 9926 9927


Property name Value type Mandatory Access mode Description fr boolean Factory Reset rb boolean yes Reboot Action n string Read Only Friendly name of

the resource rt array: see








Resource Create Read Update Delete Notify /oic/mnt get post


F.8 Platform 9930


Known resource that is defines the platform on which an Server is hosted. 9932 Allows for platform specific information to be discovered. 9933 Retrieve the information about the Platform 9934 9935


/oic/p 9937


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


{ 9941 "swagger": "2.0", 9942 "info": { 9943 "title": "Platform", 9944 "version": "v1-20160622", 9945 "license": { 9946 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 9947 "x-description": "Redistribution and use in source and binary forms, with or without 9948 modification, are permitted provided that the following conditions are met:\n 1. 9949 Redistributions of source code must retain the above copyright notice, this list of conditions and 9950 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 9951 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 9952 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 9953 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 9954 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 9955 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 9956 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 9957 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 9958 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 9959 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 9960 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 9961 OF SUCH DAMAGE.\n" 9962 } 9963 }, 9964 "schemes": ["http"], 9965 "consumes": ["application/json"], 9966 "produces": ["application/json"], 9967 "paths": { 9968 "/oic/p" : { 9969 "get": { 9970 "description": "Known resource that is defines the platform on which an Server is 9971 hosted.\nAllows for platform specific information to be discovered.\nRetrieve the information about 9972 the Platform\n", 9973 "parameters": [ 9974 {"$ref": "#/parameters/interface"} 9975 ], 9976 "responses": { 9977 "200": { 9978 "description" : "", 9979 "x-example": 9980 { 9981 "pi": "54919CA5-4101-4AE4-595B-353C51AA983C", 9982 "rt": ["oic.wk.p"], 9983 "mnmn": "Acme, Inc" 9984 } 9985 , 9986 "schema": { "$ref": "#/definitions/Platform" } 9987 } 9988 } 9989 } 9990 } 9991 }, 9992


"parameters": { 9993 "interface" : { 9994 "in" : "query", 9995 "name" : "if", 9996 "type" : "string", 9997 "enum" : ["oic.if.r", "oic.if.baseline"] 9998 } 9999 }, 10000 "definitions": { 10001 "Platform" : 10002 { 10003 "properties": { 10004 "id": { 10005 "anyOf": [ 10006 { 10007 "maxLength": 64, 10008 "type": "string" 10009 }, 10010 { 10011 "description": "Format pattern according to IETF RFC 4122.", 10012 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10013 9]{12}$", 10014 "type": "string" 10015 } 10016 ], 10017 "description": "Instance ID of this specific resource", 10018 "readOnly": true 10019 }, 10020 "if": { 10021 "description": "The interface set supported by this resource", 10022 "items": { 10023 "enum": [ 10024 "oic.if.baseline", 10025 "oic.if.ll", 10026 "oic.if.b", 10027 "oic.if.lb", 10028 "oic.if.rw", 10029 "oic.if.r", 10030 "oic.if.a", 10031 "oic.if.s" 10032 ], 10033 "type": "string" 10034 }, 10035 "minItems": 1, 10036 "readOnly": true, 10037 "type": "array" 10038 }, 10039 "mndt": { 10040 "allOf": [ 10041 { 10042 "description": "Format pattern as defined in ISO 8601. The format is [yyyy]-[mm]-10043 [dd].", 10044 "pattern": "^([0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|2[0-9]|1[0-9]|0[1-9])$", 10045 "type": "string" 10046 }, 10047 { 10048 "description": "Manufacturing Date in ISO8601 format.", 10049 "readOnly": true 10050 } 10051 ] 10052 }, 10053 "mnfv": { 10054 "description": "Manufacturer's firmware version", 10055 "maxLength": 64, 10056 "readOnly": true, 10057 "type": "string" 10058 }, 10059 "mnhw": { 10060 "description": "Platform Hardware Version", 10061 "maxLength": 64, 10062 "readOnly": true, 10063


"type": "string" 10064 }, 10065 "mnml": { 10066 "description": "Manufacturer's URL", 10067 "format": "uri", 10068 "maxLength": 256, 10069 "readOnly": true, 10070 "type": "string" 10071 }, 10072 "mnmn": { 10073 "description": "Manufacturer Name", 10074 "maxLength": 64, 10075 "readOnly": true, 10076 "type": "string" 10077 }, 10078 "mnmo": { 10079 "description": "Model number as designated by the manufacturer", 10080 "maxLength": 64, 10081 "readOnly": true, 10082 "type": "string" 10083 }, 10084 "mnos": { 10085 "description": "Platform Resident OS Version", 10086 "maxLength": 64, 10087 "readOnly": true, 10088 "type": "string" 10089 }, 10090 "mnpv": { 10091 "description": "Platform Version", 10092 "maxLength": 64, 10093 "readOnly": true, 10094 "type": "string" 10095 }, 10096 "mnsl": { 10097 "description": "Manufacturer's Support Information URL", 10098 "format": "uri", 10099 "maxLength": 256, 10100 "readOnly": true, 10101 "type": "string" 10102 }, 10103 "n": { 10104 "description": "Friendly name of the resource", 10105 "maxLength": 64, 10106 "readOnly": true, 10107 "type": "string" 10108 }, 10109 "pi": { 10110 "allOf": [ 10111 { 10112 "description": "Format pattern according to IETF RFC 4122.", 10113 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10114 9]{12}$", 10115 "type": "string" 10116 }, 10117 { 10118 "description": "Platform Identifier", 10119 "readOnly": true 10120 } 10121 ] 10122 }, 10123 "rt": { 10124 "description": "Resource Type of the Resource", 10125 "items": { 10126 "maxLength": 64, 10127 "type": "string" 10128 }, 10129 "minItems": 1, 10130 "readOnly": true, 10131 "type": "array" 10132 }, 10133 "st": { 10134


"description": "Reference time for the device in ISO8601 format.", 10135 "format": "date-time", 10136 "readOnly": true, 10137 "type": "string" 10138 }, 10139 "vid": { 10140 "description": "Manufacturer's defined information for the platform. The content is 10141 freeform, with population rules up to the manufacturer", 10142 "maxLength": 64, 10143 "readOnly": true, 10144 "type": "string" 10145 } 10146 }, 10147 "required": [ 10148 "pi", 10149 "mnmn" 10150 ], 10151 "type": "object" 10152 } 10153 10154 } 10155 } 10156 10157







st string Read Only Reference time for the device in ISO8601 format.

mnmn string yes Read Only Manufacturer Name

mnos string Read Only Platform Resident OS Version

vid string Read Only Manufacturer's defined information for the platform. The content is freeform, with population rules up to the manufacturer



pi multiple types: see schema

yes

mnhw string Read Only Platform Hardware Version

mnml string Read Only Manufacturer's URL

mnfv string Read Only Manufacturer's firmware version


mnsl string Read Only Manufacturer's Support Information URL

mnpv string Read Only Platform Version n string Read Only Friendly name of

the resource mndt multiple types:

see schema

mnmo string Read Only Model number as designated by the manufacturer


Resource Create Read Update Delete Notify /oic/p get

F.9 Resource directory resource 10160


Resource to be exposed by any Device that can act as a Resource Directory. 10162 1) Provides selector criteria (e.g., integer) with GET request 10163 2) Publish or Update a Link in /oic/res with POST request 10164 3) Delete a Link in /oic/res with DELETE request 10165 Get the attributes of the Resource Directory for selection purposes. 10166 10167


/oic/rd 10169


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


{ 10173 "swagger": "2.0", 10174 "info": { 10175 "title": "Resource directory resource", 10176 "version": "v1-20160622", 10177 "license": { 10178 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 10179 "x-description": "Redistribution and use in source and binary forms, with or without 10180 modification, are permitted provided that the following conditions are met:\n 1. 10181 Redistributions of source code must retain the above copyright notice, this list of conditions and 10182 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 10183 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 10184 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 10185 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 10186 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 10187 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 10188 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 10189 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 10190 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 10191 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 10192 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 10193 OF SUCH DAMAGE.\n" 10194 } 10195 }, 10196 "schemes": ["http"], 10197 "consumes": ["application/json"], 10198 "produces": ["application/json"], 10199 "paths": { 10200 "/oic/rd" : { 10201


"get": { 10202 "description": "Resource to be exposed by any Device that can act as a Resource 10203 Directory.\n1) Provides selector criteria (e.g., integer) with GET request\n2) Publish or Update a 10204 Link in /oic/res with POST request\n3) Delete a Link in /oic/res with DELETE request\nGet the 10205 attributes of the Resource Directory for selection purposes.\n", 10206 "parameters": [ 10207 {"$ref": "#/parameters/rdgetinterface"} 10208 ], 10209 "responses": { 10210 "200": { 10211 "description" : "Respond with the selector criteria - either the set of attributes or 10212 the bias factor\n", 10213 "x-example": 10214 { 10215 "rt": ["oic.wk.rd"], 10216 "if": ["oic.if.baseline"], 10217 "sel": 50 10218 } 10219 , 10220 "schema": { "$ref": "#/definitions/rdSelection" } 10221 } 10222 } 10223 }, 10224 "post": { 10225 "description": "Publish the resource information for the first time or Update the existing 10226 one in /oic/res.\nAppropriates parts of the information, i.e., Links of the published Resources 10227 will be discovered through /oic/res.\n1) When a Device first publishes a Link, the request payload 10228 to RD may include the Links without \"ins\" Parameter.\n2) Upon granting the request, the RD 10229 assigns a unique instance value identifying the Link among all the Links it advertises\n and 10230 sends back the instance value in \"ins\" Parameter in the Link to the publishing Device.\n3) When 10231 later the publishing Device updates the existing Link, i.e., changing its Endpoint information,\n 10232 the request payload to RD needs to include the instance value in \"ins\" Parameter to identify the 10233 Link to update.\n", 10234 "parameters": [ 10235 {"$ref": "#/parameters/rdpostinterface"}, 10236 { 10237 "name": "body", 10238 "in": "body", 10239 "required": true, 10240 "schema": { "$ref": "#/definitions/rdPublish" }, 10241 "x-example": 10242 { 10243 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 10244 "links": [ 10245 { 10246 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 10247 "href": "/myLightSwitch", 10248 "rt": ["oic.r.switch.binary"], 10249 "if": ["oic.if.a", "oic.if.baseline"], 10250 "p": {"bm": 3}, 10251 "eps": [ 10252 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 10253 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 10254 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 10255 ] 10256 }, 10257 { 10258 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 10259 "href": "/myLightBrightness", 10260 "rt": ["oic.r.brightness"], 10261 "if": ["oic.if.a", "oic.if.baseline"], 10262 "p": {"bm": 3}, 10263 "eps": [ 10264 {"ep": "coaps://[[2001:db8:a::123]:2222"} 10265 ] 10266 } 10267 ], 10268 "ttl": 600 10269 } 10270 } 10271 ], 10272


"responses": { 10273 "200": { 10274 "description" : "Respond with the same schema as publish but, when a Link is first 10275 published,\nwith the additional \"ins\" Parameter in the Link.\nThis value is used by the receiver 10276 to manage that OCF Link instance.\n", 10277 "x-example": 10278 { 10279 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 10280 "links": [ 10281 { 10282 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 10283 "href": "/myLightSwitch", 10284 "rt": ["oic.r.switch.binary"], 10285 "if": ["oic.if.a", "oic.if.baseline"], 10286 "p": {"bm": 3}, 10287 "eps": [ 10288 {"ep": "coaps://[2001:db8:a::b1d6]:1111", "pri": 2}, 10289 {"ep": "coaps://[2001:db8:a::b1d6]:1122"}, 10290 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 10291 ], 10292 "ins": "11235" 10293 }, 10294 { 10295 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 10296 "href": "/myLightBrightness", 10297 "rt": ["oic.r.brightness"], 10298 "if": ["oic.if.a", "oic.if.baseline"], 10299 "p": {"bm": 3}, 10300 "eps": [ 10301 {"ep": "coaps://[2001:db8:a::123]:2222"} 10302 ], 10303 "ins": "112358" 10304 } 10305 ], 10306 "ttl": 600 10307 } 10308 , 10309 "schema": { "$ref": "#/definitions/rdPublish" } 10310 } 10311 } 10312 }, 10313 "delete": { 10314 "description": "Delete a particular OIC Link - the link may be a simple link or a link in a 10315 tagged set.\n", 10316 "parameters": [ 10317 {"$ref": "#/parameters/rddelete-di"}, 10318 {"$ref": "#/parameters/rddelete-ins"} 10319 ], 10320 "responses": { 10321 "200": { 10322 "description" : "The delete succeeded", 10323 "x-example": 10324 {} 10325 } 10326 } 10327 } 10328 } 10329 }, 10330 "parameters": { 10331 "rddelete-di" : { 10332 "in" : "query", 10333 "name" : "di", 10334 "type" : "string", 10335 "description" : "description" 10336 }, 10337 "rddelete-ins" : { 10338 "in" : "query", 10339 "name" : "ins", 10340 "type" : "string", 10341 "description" : "description" 10342 }, 10343


"rdgetinterface" : { 10344 "in" : "query", 10345 "name" : "if", 10346 "type" : "string", 10347 "enum" : ["oic.if.baseline"], 10348 "description" : "enumdescription" 10349 }, 10350 "rdpostinterface" : { 10351 "in" : "query", 10352 "name" : "if", 10353 "type" : "string", 10354 "enum" : ["oic.if.baseline"], 10355 "description" : "enumdescription" 10356 } 10357 }, 10358 "definitions": { 10359 "rdSelection" : 10360 { 10361 "properties": { 10362 "id": { 10363 "anyOf": [ 10364 { 10365 "maxLength": 64, 10366 "type": "string" 10367 }, 10368 { 10369 "description": "Format pattern according to IETF RFC 4122.", 10370 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10371 9]{12}$", 10372 "type": "string" 10373 } 10374 ], 10375 "description": "Instance ID of this specific resource", 10376 "readOnly": true 10377 }, 10378 "if": { 10379 "description": "The interface set supported by this resource", 10380 "items": { 10381 "enum": [ 10382 "oic.if.baseline", 10383 "oic.if.ll", 10384 "oic.if.b", 10385 "oic.if.lb", 10386 "oic.if.rw", 10387 "oic.if.r", 10388 "oic.if.a", 10389 "oic.if.s" 10390 ], 10391 "type": "string" 10392 }, 10393 "minItems": 1, 10394 "readOnly": true, 10395 "type": "array" 10396 }, 10397 "n": { 10398 "description": "Friendly name of the resource", 10399 "maxLength": 64, 10400 "readOnly": true, 10401 "type": "string" 10402 }, 10403 "rt": { 10404 "description": "Resource Type of the Resource", 10405 "items": { 10406 "maxLength": 64, 10407 "type": "string" 10408 }, 10409 "minItems": 1, 10410 "readOnly": true, 10411 "type": "array" 10412 }, 10413 "sel": { 10414


"description": "A bias factor calculated by the Resource directory", 10415 "maximum": 100, 10416 "minimum": 0, 10417 "type": "integer" 10418 } 10419 }, 10420 "required": [ 10421 "sel" 10422 ], 10423 "type": "object" 10424 } 10425 10426 , 10427 "rdPublish" : 10428 { 10429 "description": "Publishes resources as OIC Links into the resource directory", 10430 "properties": { 10431 "di": { 10432 "allOf": [ 10433 { 10434 "description": "Format pattern according to IETF RFC 4122.", 10435 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10436 9]{12}$", 10437 "type": "string" 10438 }, 10439 { 10440 "description": "A UUID that is the identifier for the publishing Device" 10441 } 10442 ] 10443 }, 10444 "id": { 10445 "anyOf": [ 10446 { 10447 "maxLength": 64, 10448 "type": "string" 10449 }, 10450 { 10451 "description": "Format pattern according to IETF RFC 4122.", 10452 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-10453 9]{12}$", 10454 "type": "string" 10455 } 10456 ], 10457 "description": "Instance ID of this specific resource", 10458 "readOnly": true 10459 }, 10460 "if": { 10461 "description": "The interface set supported by this resource", 10462 "items": { 10463 "enum": [ 10464 "oic.if.baseline", 10465 "oic.if.ll", 10466 "oic.if.b", 10467 "oic.if.lb", 10468 "oic.if.rw", 10469 "oic.if.r", 10470 "oic.if.a", 10471 "oic.if.s" 10472 ], 10473 "type": "string" 10474 }, 10475 "minItems": 1, 10476 "readOnly": true, 10477 "type": "array" 10478 }, 10479 "links": { 10480 "description": "A set of simple or individual OIC Links.", 10481 "items": { 10482 "properties": { 10483 "anchor": { 10484 "description": "This is used to override the context URI e.g. override the URI of 10485


the containing collection.", 10486 "format": "uri", 10487 "maxLength": 256, 10488 "type": "string" 10489 }, 10490 "di": { 10491 "allOf": [ 10492 { 10493 "description": "Format pattern according to IETF RFC 4122.", 10494 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-10495 fA-F0-9]{12}$", 10496 "type": "string" 10497 }, 10498 { 10499 "description": "The device ID" 10500 } 10501 ] 10502 }, 10503 "eps": { 10504 "description": "the Endpoint information of the target Resource", 10505 "items": { 10506 "properties": { 10507 "ep": { 10508 "description": "Transport Protocol Suite + Endpoint Locator", 10509 "format": "uri", 10510 "type": "string" 10511 }, 10512 "pri": { 10513 "description": "The priority among multiple Endpoints", 10514 "minimum": 1, 10515 "type": "integer" 10516 } 10517 }, 10518 "type": "object" 10519 }, 10520 "type": "array" 10521 }, 10522 "href": { 10523 "description": "This is the target URI, it can be specified as a Relative 10524 Reference or fully-qualified URI.", 10525 "format": "uri", 10526 "maxLength": 256, 10527 "type": "string" 10528 }, 10529 "if": { 10530 "description": "The interface set supported by this resource", 10531 "items": { 10532 "enum": [ 10533 "oic.if.baseline", 10534 "oic.if.ll", 10535 "oic.if.b", 10536 "oic.if.rw", 10537 "oic.if.r", 10538 "oic.if.a", 10539 "oic.if.s" 10540 ], 10541 "type": "string" 10542 }, 10543 "minItems": 1, 10544 "type": "array" 10545 }, 10546 "ins": { 10547 "description": "The instance identifier for this web link in an array of web 10548 links - used in collections", 10549 "oneOf": [ 10550 { 10551 "description": "An ordinal number that is not repeated - must be unique in 10552 the collection context.", 10553 "type": "integer" 10554 }, 10555 { 10556


"description": "A unique string", 10557 "format": "uri", 10558 "maxLength": 256, 10559 "type": "string" 10560 }, 10561 { 10562 "allOf": [ 10563 { 10564 "description": "Format pattern according to IETF RFC 4122.", 10565 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-10566 [a-fA-F0-9]{12}$", 10567 "type": "string" 10568 }, 10569 { 10570 "description": "A UUID" 10571 } 10572 ] 10573 } 10574 ] 10575 }, 10576 "p": { 10577 "description": "Specifies the framework policies on the Resource referenced by 10578 the target URI", 10579 "properties": { 10580 "bm": { 10581 "description": "Specifies the framework policies on the Resource referenced 10582 by the target URI for e.g. observable and discoverable", 10583 "type": "integer" 10584 } 10585 }, 10586 "required": [ 10587 "bm" 10588 ], 10589 "type": "object" 10590 }, 10591 "rel": { 10592 "description": "The relation of the target URI referenced by the link to the 10593 context URI", 10594 "oneOf": [ 10595 { 10596 "default": [ 10597 "hosts" 10598 ], 10599 "items": { 10600 "maxLength": 64, 10601 "type": "string" 10602 }, 10603 "minItems": 1, 10604 "type": "array" 10605 }, 10606 { 10607 "default": "hosts", 10608 "maxLength": 64, 10609 "type": "string" 10610 } 10611 ] 10612 }, 10613 "rt": { 10614 "description": "Resource Type of the Resource", 10615 "items": { 10616 "maxLength": 64, 10617 "type": "string" 10618 }, 10619 "minItems": 1, 10620 "type": "array" 10621 }, 10622 "title": { 10623 "description": "A title for the link relation. Can be used by the UI to provide a 10624 context.", 10625 "maxLength": 64, 10626 "type": "string" 10627


}, 10628 "type": { 10629 "default": "application/cbor", 10630 "description": "A hint at the representation of the resource referenced by the 10631 target URI. This represents the media types that are used for both accepting and emitting.", 10632 "items": { 10633 "maxLength": 64, 10634 "type": "string" 10635 }, 10636 "minItems": 1, 10637 "type": "array" 10638 } 10639 }, 10640 "required": [ 10641 "href", 10642 "rt", 10643 "if" 10644 ], 10645 "type": "object" 10646 }, 10647 "type": "array" 10648 }, 10649 "n": { 10650 "description": "Friendly name of the resource", 10651 "maxLength": 64, 10652 "readOnly": true, 10653 "type": "string" 10654 }, 10655 "rt": { 10656 "description": "Resource Type of the Resource", 10657 "items": { 10658 "maxLength": 64, 10659 "type": "string" 10660 }, 10661 "minItems": 1, 10662 "readOnly": true, 10663 "type": "array" 10664 }, 10665 "ttl": { 10666 "description": "Time to indicate a RD, i.e. how long to keep this published item.", 10667 "type": "integer" 10668 } 10669 } 10670 } 10671 10672 } 10673 } 10674 10675





schema yes Read Only The interface set







A set of simple or individual OIC Links.


ttl integer Time to indicate a RD, i.e. how long to keep this published item.





sel integer yes A bias factor calculated by the Resource directory





Resource Create Read Update Delete Notify /oic/rd get post delete

F.10 Discoverable Resources 10678


Link list representation of /oic/res; list of discoverable resources 10680 Retrieve the discoverable resource set, link list interface 10681 10682


/oic-res-llInterfaceURI 10684



{ 10687 "swagger": "2.0", 10688 "info": { 10689 "title": "Discoverable Resources Baseline Interface", 10690 "version": "v1-20160622", 10691 "license": { 10692 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 10693 "x-description": "Redistribution and use in source and binary forms, with or without 10694 modification, are permitted provided that the following conditions are met:\n 1. 10695 Redistributions of source code must retain the above copyright notice, this list of conditions and 10696 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 10697 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 10698 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 10699 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 10700 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 10701 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 10702 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 10703 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 10704 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 10705 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 10706 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 10707 OF SUCH DAMAGE.\n" 10708 } 10709 }, 10710 "schemes": ["http"], 10711 "consumes": ["application/json"], 10712


"produces": ["application/json"], 10713 "paths": { 10714 "/oic-res-BaselineInterfaceURI" : { 10715 "get": { 10716 "description": "Baseline representation of /oic/res; list of discoverable 10717 resources\nRetrieve the discoverable resource set, baseline interface\n", 10718 "parameters": [ 10719 {"$ref": "#/parameters/interface-baseline"} 10720 ], 10721 "responses": { 10722 "200": { 10723 "description" : "", 10724 "x-example": 10725 [ 10726 { 10727 "rt": ["oic.wk.res"], 10728 "if": ["oic.if.baseline", "oic.if.ll" ], 10729 "links": 10730 [ 10731 { 10732 "href": "/humidity", 10733 "rt": ["oic.r.humidity"], 10734 "if": ["oic.if.s"], 10735 "p": {"bm": 3}, 10736 "eps": [ 10737 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 10738 {"ep": "coaps://[fe80::b1d6]:1122"}, 10739 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 10740 ] 10741 }, 10742 { 10743 "href": "/temperature", 10744 "rt": ["oic.r.temperature"], 10745 "if": ["oic.if.s"], 10746 "p": {"bm": 3}, 10747 "eps": [ 10748 {"ep": "coaps://[[2001:db8:a::123]:2222"} 10749 ] 10750 } 10751 ] 10752 } 10753 ] 10754 , 10755 "schema": { "$ref": "#/definitions/sbaseline" } 10756 } 10757 } 10758 } 10759 }, 10760 "/oic-res-llInterfaceURI" : { 10761 "get": { 10762 "description": "Link list representation of /oic/res; list of discoverable 10763 resources\nRetrieve the discoverable resource set, link list interface\n", 10764 "parameters": [ 10765 {"$ref": "#/parameters/interface-ll"} 10766 ], 10767 "responses": { 10768 "200": { 10769 "description" : "", 10770 "x-example": 10771 [ 10772 { 10773 "href": "/humidity", 10774 "rt": ["oic.r.humidity"], 10775 "if": ["oic.if.s"], 10776 "p": {"bm": 3}, 10777 "eps": [ 10778 {"ep": "coaps://[fe80::b1d6]:1111", "pri": 2}, 10779 {"ep": "coaps://[fe80::b1d6]:1122"}, 10780 {"ep": "coaps+tcp://[2001:db8:a::123]:2222", "pri": 3} 10781 ] 10782 }, 10783


{ 10784 "href": "/temperature", 10785 "rt": ["oic.r.temperature"], 10786 "if": ["oic.if.s"], 10787 "p": {"bm": 3}, 10788 "eps": [ 10789 {"ep": "coaps://[[2001:db8:a::123]:2222"} 10790 ] 10791 } 10792 ] 10793 , 10794 "schema": { "$ref": "#/definitions/slinklist" } 10795 } 10796 } 10797 } 10798 } 10799 }, 10800 "parameters": { 10801 "interface-ll" : { 10802 "in" : "query", 10803 "name" : "if", 10804 "type" : "string", 10805 "enum" : ["oic.if.ll"] 10806 }, 10807 "interface-baseline" : { 10808 "in" : "query", 10809 "name" : "if", 10810 "type" : "string", 10811 "enum" : ["oic.if.baseline"] 10812 }, 10813 "interface-all" : { 10814 "in" : "query", 10815 "name" : "if", 10816 "type" : "string", 10817 "enum" : ["oic.if.ll", "oic.if.baseline"] 10818 } 10819 }, 10820 "definitions": { 10821 "sbaseline" : 10822 { 10823 "properties": { 10824 "if": { 10825 "description": "The interface set supported by this resource", 10826 "items": { 10827 "enum": [ 10828 "oic.if.baseline", 10829 "oic.if.ll" 10830 ], 10831 "type": "string" 10832 }, 10833 "minItems": 1, 10834 "readOnly": true, 10835 "type": "array" 10836 }, 10837 "links": { 10838 "items": { 10839 "properties": { 10840 "anchor": { 10841 "description": "This is used to override the context URI e.g. override the URI of 10842 the containing collection.", 10843 "format": "uri", 10844 "maxLength": 256, 10845 "type": "string" 10846 }, 10847 "di": { 10848 "allOf": [ 10849 { 10850 "description": "Format pattern according to IETF RFC 4122.", 10851 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-10852 fA-F0-9]{12}$", 10853 "type": "string" 10854


}, 10855 { 10856 "description": "The device ID" 10857 } 10858 ] 10859 }, 10860 "eps": { 10861 "description": "the Endpoint information of the target Resource", 10862 "items": { 10863 "properties": { 10864 "ep": { 10865 "description": "Transport Protocol Suite + Endpoint Locator", 10866 "format": "uri", 10867 "type": "string" 10868 }, 10869 "pri": { 10870 "description": "The priority among multiple Endpoints", 10871 "minimum": 1, 10872 "type": "integer" 10873 } 10874 }, 10875 "type": "object" 10876 }, 10877 "type": "array" 10878 }, 10879 "href": { 10880 "description": "This is the target URI, it can be specified as a Relative 10881 Reference or fully-qualified URI.", 10882 "format": "uri", 10883 "maxLength": 256, 10884 "type": "string" 10885 }, 10886 "if": { 10887 "description": "The interface set supported by this resource", 10888 "items": { 10889 "enum": [ 10890 "oic.if.baseline", 10891 "oic.if.ll", 10892 "oic.if.b", 10893 "oic.if.rw", 10894 "oic.if.r", 10895 "oic.if.a", 10896 "oic.if.s" 10897 ], 10898 "type": "string" 10899 }, 10900 "minItems": 1, 10901 "type": "array" 10902 }, 10903 "ins": { 10904 "description": "The instance identifier for this web link in an array of web 10905 links - used in collections", 10906 "oneOf": [ 10907 { 10908 "description": "An ordinal number that is not repeated - must be unique in 10909 the collection context.", 10910 "type": "integer" 10911 }, 10912 { 10913 "description": "A unique string", 10914 "format": "uri", 10915 "maxLength": 256, 10916 "type": "string" 10917 }, 10918 { 10919 "allOf": [ 10920 { 10921 "description": "Format pattern according to IETF RFC 4122.", 10922 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-10923 [a-fA-F0-9]{12}$", 10924 "type": "string" 10925


}, 10926 { 10927 "description": "A UUID" 10928 } 10929 ] 10930 } 10931 ] 10932 }, 10933 "p": { 10934 "description": "Specifies the framework policies on the Resource referenced by 10935 the target URI", 10936 "properties": { 10937 "bm": { 10938 "description": "Specifies the framework policies on the Resource referenced 10939 by the target URI for e.g. observable and discoverable", 10940 "type": "integer" 10941 } 10942 }, 10943 "required": [ 10944 "bm" 10945 ], 10946 "type": "object" 10947 }, 10948 "rel": { 10949 "description": "The relation of the target URI referenced by the link to the 10950 context URI", 10951 "oneOf": [ 10952 { 10953 "default": [ 10954 "hosts" 10955 ], 10956 "items": { 10957 "maxLength": 64, 10958 "type": "string" 10959 }, 10960 "minItems": 1, 10961 "type": "array" 10962 }, 10963 { 10964 "default": "hosts", 10965 "maxLength": 64, 10966 "type": "string" 10967 } 10968 ] 10969 }, 10970 "rt": { 10971 "description": "Resource Type of the Resource", 10972 "items": { 10973 "maxLength": 64, 10974 "type": "string" 10975 }, 10976 "minItems": 1, 10977 "type": "array" 10978 }, 10979 "title": { 10980 "description": "A title for the link relation. Can be used by the UI to provide a 10981 context.", 10982 "maxLength": 64, 10983 "type": "string" 10984 }, 10985 "type": { 10986 "default": "application/cbor", 10987 "description": "A hint at the representation of the resource referenced by the 10988 target URI. This represents the media types that are used for both accepting and emitting.", 10989 "items": { 10990 "maxLength": 64, 10991 "type": "string" 10992 }, 10993 "minItems": 1, 10994 "type": "array" 10995 } 10996


}, 10997 "required": [ 10998 "href", 10999 "rt", 11000 "if" 11001 ], 11002 "type": "object" 11003 }, 11004 "type": "array" 11005 }, 11006 "mpro": { 11007 "description": "Supported messaging protocols", 11008 "maxLength": 64, 11009 "readOnly": true, 11010 "type": "string" 11011 }, 11012 "n": { 11013 "description": "Human friendly name", 11014 "maxLength": 64, 11015 "readOnly": true, 11016 "type": "string" 11017 }, 11018 "rt": { 11019 "description": "Resource Type of the Resource", 11020 "items": { 11021 "maxLength": 64, 11022 "type": "string" 11023 }, 11024 "minItems": 1, 11025 "readOnly": true, 11026 "type": "array" 11027 } 11028 }, 11029 "required": [ 11030 "rt", 11031 "if", 11032 "links" 11033 ], 11034 "type": "object" 11035 } 11036 11037 , 11038 "slinklist" : 11039 { 11040 "properties": { 11041 "anchor": { 11042 "description": "This is used to override the context URI e.g. override the URI of the 11043 containing collection.", 11044 "format": "uri", 11045 "maxLength": 256, 11046 "type": "string" 11047 }, 11048 "di": { 11049 "allOf": [ 11050 { 11051 "description": "Format pattern according to IETF RFC 4122.", 11052 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-11053 9]{12}$", 11054 "type": "string" 11055 }, 11056 { 11057 "description": "The device ID" 11058 } 11059 ] 11060 }, 11061 "eps": { 11062 "description": "the Endpoint information of the target Resource", 11063 "items": { 11064 "properties": { 11065 "ep": { 11066 "description": "Transport Protocol Suite + Endpoint Locator", 11067


"format": "uri", 11068 "type": "string" 11069 }, 11070 "pri": { 11071 "description": "The priority among multiple Endpoints", 11072 "minimum": 1, 11073 "type": "integer" 11074 } 11075 }, 11076 "type": "object" 11077 }, 11078 "type": "array" 11079 }, 11080 "href": { 11081 "description": "This is the target URI, it can be specified as a Relative Reference or 11082 fully-qualified URI.", 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 links - 11106 used in collections", 11107 "oneOf": [ 11108 { 11109 "description": "An ordinal number that is not repeated - must be unique in the 11110 collection context.", 11111 "type": "integer" 11112 }, 11113 { 11114 "description": "A unique string", 11115 "format": "uri", 11116 "maxLength": 256, 11117 "type": "string" 11118 }, 11119 { 11120 "allOf": [ 11121 { 11122 "description": "Format pattern according to IETF RFC 4122.", 11123 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-11124 F0-9]{12}$", 11125 "type": "string" 11126 }, 11127 { 11128 "description": "A UUID" 11129 } 11130 ] 11131 } 11132 ] 11133 }, 11134 "p": { 11135 "description": "Specifies the framework policies on the Resource referenced by the 11136 target URI", 11137 "properties": { 11138


"bm": { 11139 "description": "Specifies the framework policies on the Resource referenced by the 11140 target URI for e.g. observable and discoverable", 11141 "type": "integer" 11142 } 11143 }, 11144 "required": [ 11145 "bm" 11146 ], 11147 "type": "object" 11148 }, 11149 "rel": { 11150 "description": "The relation of the target URI referenced by the link to the context 11151 URI", 11152 "oneOf": [ 11153 { 11154 "default": [ 11155 "hosts" 11156 ], 11157 "items": { 11158 "maxLength": 64, 11159 "type": "string" 11160 }, 11161 "minItems": 1, 11162 "type": "array" 11163 }, 11164 { 11165 "default": "hosts", 11166 "maxLength": 64, 11167 "type": "string" 11168 } 11169 ] 11170 }, 11171 "rt": { 11172 "description": "Resource Type of the Resource", 11173 "items": { 11174 "maxLength": 64, 11175 "type": "string" 11176 }, 11177 "minItems": 1, 11178 "type": "array" 11179 }, 11180 "title": { 11181 "description": "A title for the link relation. Can be used by the UI to provide a 11182 context.", 11183 "maxLength": 64, 11184 "type": "string" 11185 }, 11186 "type": { 11187 "default": "application/cbor", 11188 "description": "A hint at the representation of the resource referenced by the target 11189 URI. This represents the media types that are used for both accepting and emitting.", 11190 "items": { 11191 "maxLength": 64, 11192 "type": "string" 11193 }, 11194 "minItems": 1, 11195 "type": "array" 11196 } 11197 }, 11198 "required": [ 11199 "href", 11200 "rt", 11201 "if" 11202 ], 11203 "type": "object" 11204 } 11205 11206 } 11207 } 11208 11209



Property name Value type Mandatory Access mode Description di multiple types:

see schema

















href string yes This is the target URI, it can be specified as a Relative


Reference or fully-qualified URI.



yes Read Only Resource Type of the Resource



n string Read Only Human friendly name


yes


Resource Create Read Update Delete Notify /oic-res-llInterfaceURI

get

F.11 Scenes 11212


Toplevel Scene resource. 11214 This resource is a generic collection resource. 11215 The rts value shall contain oic.wk.scenecollection resource types. 11216 Provides the current list of web links pointing to scenes 11217 11218


/SceneListResURI 11220


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


{ 11224 "swagger": "2.0", 11225 "info": { 11226 "title": "Scenes (Top level)", 11227 "version": "v1-20160622", 11228 "license": { 11229 "name": "copyright 2016-2017 Open Connectivity Foundation, Inc. All rights reserved.", 11230 "x-description": "Redistribution and use in source and binary forms, with or without 11231 modification, are permitted provided that the following conditions are met:\n 1. 11232 Redistributions of source code must retain the above copyright notice, this list of conditions and 11233 the following disclaimer.\n 2. Redistributions in binary form must reproduce the above 11234 copyright notice, this list of conditions and the following disclaimer in the documentation and/or 11235 other materials provided with the distribution.\n\n THIS SOFTWARE IS PROVIDED BY THE Open 11236 Connectivity Foundation, INC. \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 11237 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR 11238 WARRANTIES OF NON-INFRINGEMENT, ARE DISCLAIMED.\n IN NO EVENT SHALL THE Open Connectivity 11239 Foundation, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 11240 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 11241 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n HOWEVER CAUSED AND 11242 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 11243 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 11244 OF SUCH DAMAGE.\n" 11245 } 11246 }, 11247


"schemes": ["http"], 11248 "consumes": ["application/json"], 11249 "produces": ["application/json"], 11250 "paths": { 11251 "/SceneListResURI" : { 11252 "get": { 11253 "description": "Toplevel Scene resource.\nThis resource is a generic collection 11254 resource.\nThe rts value shall contain oic.wk.scenecollection resource types.\nProvides the current 11255 list of web links pointing to scenes\n", 11256 "parameters": [ 11257 ], 11258 "responses": { 11259 "200": { 11260 "description" : "", 11261 "x-example": 11262 { 11263 "rt": ["oic.wk.scenelist"], 11264 "n": "list of scene Collections", 11265 "rts": ["oic.wk.scenecollection"], 11266 "links": [ 11267 ] 11268 } 11269 , 11270 "schema": { "$ref": "#/definitions/Collection" } 11271 } 11272 } 11273 } 11274 }, 11275 "/SceneMemberResURI" : { 11276 "get": { 11277 "description": "Collection that models a scene member.\nProvides the scene member\n", 11278 "parameters": [ 11279 ], 11280 "responses": { 11281 "200": { 11282 "description" : "", 11283 "x-example": 11284 { 11285 "rt": ["oic.wk.scenemember"], 11286 "id": "0685B960-FFFF-46F7-BEC0-9E6234671ADC1", 11287 "n": "my binary switch (for light bulb) mappings", 11288 "link": { 11289 "href": "binarySwitch", 11290 "rt": ["oic.r.switch.binary"], 11291 "if": ["oic.if.a", "oic.if.baseline"], 11292 "eps": [ 11293 {"ep": "coap://[fe80::b1d6]:1111", "pri": 2}, 11294 {"ep": "coaps://[fe80::b1d6]:1122"}, 11295 {"ep": "coap+tcp://[2001:db8:a::123]:2222", "pri": 3} 11296 ] 11297 }, 11298 "sceneMappings": [ 11299 { 11300 "scene": "off", 11301 "memberProperty": "value", 11302 "memberValue": true 11303 }, 11304 { 11305 "scene": "Reading", 11306 "memberProperty": "value", 11307 "memberValue": false 11308 }, 11309 { 11310 "scene": "TVWatching", 11311 "memberProperty": "value", 11312 "memberValue": true 11313 } 11314 ] 11315 } 11316 , 11317 "schema": { "$ref": "#/definitions/SceneMember" } 11318


} 11319 } 11320 } 11321 }, 11322 "/SceneCollectionResURI" : { 11323 "get": { 11324 "description": "Collection that models a set of Scenes.\nThis resource is a generic 11325 collection resource with additional parameters.\nThe rts value shall contain oic.scenemember 11326 resource types.\nThe additional parameters are\n lastScene, this is the scene value last set by 11327 any OCF Client\n sceneValues, this is the list of available scenes\n lastScene shall be listed in 11328 sceneValues.\nProvides the current list of web links pointing to scenes\n", 11329 "parameters": [ 11330 ], 11331 "responses": { 11332 "200": { 11333 "description" : "", 11334 "x-example": 11335 { 11336 "lastScene": "off", 11337 "sceneValues": ["off","Reading","TVWatching"], 11338 "rt": ["oic.wk.scenecollection"], 11339 "n": "My Scenes for my living room", 11340 "id": "0685B960-736F-46F7-BEC0-9E6CBD671ADC1", 11341 "rts": ["oic.wk.scenemember"], 11342 "links": [ 11343 ] 11344 } 11345 , 11346 "schema": { "$ref": "#/definitions/SceneCollection" } 11347 } 11348 } 11349 }, 11350 "post": { 11351 "description": "Provides the action to change the last set scene selection.\nCalling this 11352 method shall update all scene members to the prescribed membervalue.\nWhen this method is called 11353 with the same value as the current lastScene value\nthen all scene members shall be updated.\n", 11354 "parameters": [ 11355 { 11356 "name": "body", 11357 "in": "body", 11358 "required": true, 11359 "schema": { "$ref": "#/definitions/SceneCollectionUpdate" }, 11360 "x-example": 11361 { 11362 "lastScene": "Reading" 11363 } 11364 } 11365 ], 11366 "responses": { 11367 "200": { 11368 "description" : "Indicates that the value is changed.\nThe changed properties are 11369 provided in the response.\n", 11370 "x-example": 11371 { 11372 "lastScene": "Reading" 11373 } 11374 , 11375 "schema": { "$ref": "#/definitions/SceneCollectionUpdate" } 11376 } 11377 } 11378 } 11379 } 11380 }, 11381 "parameters": { 11382 "interface" : { 11383 "in" : "query", 11384 "name" : "if", 11385 "type" : "string", 11386 "enum" : ["oic.if.a", "oic.if.ll", "oic.if.baseline"] 11387 } 11388 }, 11389


"definitions": { 11390 "Collection" : 11391 { 11392 "description": "A set of simple or individual OIC Links.", 11393 "items": { 11394 "properties": { 11395 "anchor": { 11396 "description": "This is used to override the context URI e.g. override the URI of the 11397 containing collection.", 11398 "format": "uri", 11399 "maxLength": 256, 11400 "type": "string" 11401 }, 11402 "di": { 11403 "allOf": [ 11404 { 11405 "description": "Format pattern according to IETF RFC 4122.", 11406 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-11407 F0-9]{12}$", 11408 "type": "string" 11409 }, 11410 { 11411 "description": "The device ID" 11412 } 11413 ] 11414 }, 11415 "eps": { 11416 "description": "the Endpoint information of the target Resource", 11417 "items": { 11418 "properties": { 11419 "ep": { 11420 "description": "Transport Protocol Suite + Endpoint Locator", 11421 "format": "uri", 11422 "type": "string" 11423 }, 11424 "pri": { 11425 "description": "The priority among multiple Endpoints", 11426 "minimum": 1, 11427 "type": "integer" 11428 } 11429 }, 11430 "type": "object" 11431 }, 11432 "type": "array" 11433 }, 11434 "href": { 11435 "description": "This is the target URI, it can be specified as a Relative Reference 11436 or fully-qualified URI.", 11437 "format": "uri", 11438 "maxLength": 256, 11439 "type": "string" 11440 }, 11441 "id": { 11442 "anyOf": [ 11443 { 11444 "maxLength": 64, 11445 "type": "string" 11446 }, 11447 { 11448 "description": "Format pattern according to IETF RFC 4122.", 11449 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-11450 F0-9]{12}$", 11451 "type": "string" 11452 } 11453 ], 11454 "description": "Instance ID of this specific resource", 11455 "readOnly": true 11456 }, 11457 "if": { 11458 "description": "The interface set supported by this resource", 11459 "items": { 11460


"enum": [ 11461 "oic.if.baseline", 11462 "oic.if.ll", 11463 "oic.if.b", 11464 "oic.if.rw", 11465 "oic.if.r", 11466 "oic.if.a", 11467 "oic.if.s" 11468 ], 11469 "type": "string" 11470 }, 11471 "minItems": 1, 11472 "type": "array" 11473 }, 11474 "ins": { 11475 "description": "The instance identifier for this web link in an array of web links - 11476 used in collections", 11477 "oneOf": [ 11478 { 11479 "description": "An ordinal number that is not repeated - must be unique in the 11480 collection context.", 11481 "type": "integer" 11482 }, 11483 { 11484 "description": "A unique string", 11485 "format": "uri", 11486 "maxLength": 256, 11487 "type": "string" 11488 }, 11489 { 11490 "allOf": [ 11491 { 11492 "description": "Format pattern according to IETF RFC 4122.", 11493 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-11494 fA-F0-9]{12}$", 11495 "type": "string" 11496 }, 11497 { 11498 "description": "A UUID" 11499 } 11500 ] 11501 } 11502 ] 11503 }, 11504 "links": { 11505 "description": "All forms of links in a collection.", 11506 "oneOf": [ 11507 { 11508 "description": "A set of simple or individual OIC Links.", 11509 "items": { 11510 "properties": { 11511 "anchor": { 11512 "description": "This is used to override the context URI e.g. override the 11513 URI of the containing collection.", 11514 "format": "uri", 11515 "maxLength": 256, 11516 "type": "string" 11517 }, 11518 "di": { 11519 "allOf": [ 11520 { 11521 "description": "Format pattern according to IETF RFC 4122.", 11522 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-11523 9]{4}-[a-fA-F0-9]{12}$", 11524 "type": "string" 11525 }, 11526 { 11527 "description": "The device ID" 11528 } 11529 ] 11530 }, 11531


"eps": { 11532 "description": "the Endpoint information of the target Resource", 11533 "items": { 11534 "properties": { 11535 "ep": { 11536 "description": "Transport Protocol Suite + Endpoint Locator", 11537 "format": "uri", 11538 "type": "string" 11539 }, 11540 "pri": { 11541 "description": "The priority among multiple Endpoints", 11542 "minimum": 1, 11543 "type": "integer" 11544 } 11545 }, 11546 "type": "object" 11547 }, 11548 "type": "array" 11549 }, 11550 "href": { 11551 "description": "This is the target URI, it can be specified as a Relative 11552 Reference or fully-qualified URI.", 11553 "format": "uri", 11554 "maxLength": 256, 11555 "type": "string" 11556 }, 11557 "if": { 11558 "description": "The interface set supported by this resource", 11559 "items": { 11560 "enum": [ 11561 "oic.if.baseline", 11562 "oic.if.ll", 11563 "oic.if.b", 11564 "oic.if.rw", 11565 "oic.if.r", 11566 "oic.if.a", 11567 "oic.if.s" 11568 ], 11569 "type": "string" 11570 }, 11571 "minItems": 1, 11572 "type": "array" 11573 }, 11574 "ins": { 11575 "description": "The instance identifier for this web link in an array of 11576 web links - used in collections", 11577 "oneOf": [ 11578 { 11579 "description": "An ordinal number that is not repeated - must be unique 11580 in the collection context.", 11581 "type": "integer" 11582 }, 11583 { 11584 "description": "A unique string", 11585 "format": "uri", 11586 "maxLength": 256, 11587 "type": "string" 11588 }, 11589 { 11590 "allOf": [ 11591 { 11592 "description": "Format pattern according to IETF RFC 4122.", 11593 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-11594 9]{4}-[a-fA-F0-9]{12}$", 11595 "type": "string" 11596 }, 11597 { 11598 "description": "A UUID" 11599 } 11600 ] 11601 } 11602


] 11603 }, 11604 "p": { 11605 "description": "Specifies the framework policies on the Resource referenced 11606 by the target URI", 11607 "properties": { 11608 "bm": { 11609 "description": "Specifies the framework policies on the Resource 11610 referenced by the target URI for e.g. observable and discoverable", 11611 "type": "integer" 11612 } 11613 }, 11614 "required": [ 11615 "bm" 11616 ], 11617 "type": "object" 11618 }, 11619 "rel": { 11620 "description": "The relation of the target URI referenced by the link to 11621 the context URI", 11622 "oneOf": [ 11623 { 11624 "default": [ 11625 "hosts" 11626 ], 11627 "items": { 11628 "maxLength": 64, 11629 "type": "string" 11630 }, 11631 "minItems": 1, 11632 "type": "array" 11633 }, 11634 { 11635 "default": "hosts", 11636 "maxLength": 64, 11637 "type": "string" 11638 } 11639 ] 11640 }, 11641 "rt": { 11642 "description": "Resource Type of the Resource", 11643 "items": { 11644 "maxLength": 64, 11645 "type": "string" 11646 }, 11647 "minItems": 1, 11648 "type": "array" 11649 }, 11650 "title": { 11651 "description": "A title for the link relation. Can be used by the UI to 11652 provide a context.", 11653 "maxLength": 64, 11654 "type": "string" 11655 }, 11656 "type": { 11657 "default": "application/cbor", 11658 "description": "A hint at the representation of the resource referenced by 11659 the target URI. This represents the media types that are used for both accepting and emitting.", 11660 "items": { 11661 "maxLength": 64, 11662 "type": "string" 11663 }, 11664 "minItems": 1, 11665 "type": "array" 11666 } 11667 }, 11668 "required": [ 11669 "href", 11670 "rt", 11671 "if" 11672 ], 11673


"type": "object" 11674 }, 11675 "type": "array" 11676 } 11677 ] 11678 }, 11679 "n": { 11680 "description": "Friendly name of the resource", 11681 "maxLength": 64, 11682 "readOnly": true, 11683 "type": "string" 11684 }, 11685 "p": { 11686 "description": "Specifies the framework policies on the Resource referenced by the 11687 target URI", 11688 "properties": { 11689 "bm": { 11690 "description": "Specifies the framework policies on the Resource referenced by 11691 the target URI for e.g. observable and discoverable", 11692 "type": "integer" 11693 } 11694 }, 11695 "required": [ 11696 "bm" 11697 ], 11698 "type": "object" 11699 }, 11700 "rel": { 11701 "description": "The relation of the target URI referenced by the link to the context 11702 URI", 11703 "oneOf": [ 11704 { 11705 "default": [ 11706 "hosts" 11707 ], 11708 "items": { 11709 "maxLength": 64, 11710 "type": "string" 11711 }, 11712 "minItems": 1, 11713 "type": "array" 11714 }, 11715 { 11716 "default": "hosts", 11717 "maxLength": 64, 11718 "type": "string" 11719 } 11720 ] 11721 }, 11722 "rt": { 11723 "description": "Resource Type of the Resource", 11724 "items": { 11725 "maxLength": 64, 11726 "type": "string" 11727 }, 11728 "minItems": 1, 11729 "type": "array" 11730 }, 11731 "rts": { 11732 "allOf": [ 11733 { 11734 "description": "Resource Type of the Resource", 11735 "items": { 11736 "maxLength": 64, 11737 "type": "string" 11738 }, 11739 "minItems": 1, 11740 "readOnly": true, 11741 "type": "array" 11742 }, 11743 { 11744


"description": "The list of allowable resource types (for Target and anchors) in 11745 links included in the collection" 11746 } 11747 ] 11748 }, 11749 "title": { 11750 "description": "A title for the link relation. Can be used by the UI to provide a 11751 context.", 11752 "maxLength": 64, 11753 "type": "string" 11754 }, 11755 "type": { 11756 "default": "application/cbor", 11757 "description": "A hint at the representation of the resource referenced by the target 11758 URI. This represents the media types that are used for both accepting and emitting.", 11759 "items": { 11760 "maxLength": 64, 11761 "type": "string" 11762 }, 11763 "minItems": 1, 11764 "type": "array" 11765 } 11766 }, 11767 "required": [ 11768 "href", 11769 "rt", 11770 "if" 11771 ], 11772 "type": "object" 11773 }, 11774 "type": "array" 11775 } 11776 11777 , 11778 "SceneMember" : 11779 { 11780 "properties": { 11781 "SceneMappings": { 11782 "description": "array of mappings per scene, can be one(1)", 11783 "items": { 11784 "properties": { 11785 "memberProperty": { 11786 "description": "property name that will be mapped", 11787 "readOnly": true, 11788 "type": "string" 11789 }, 11790 "memberValue": { 11791 "description": "value of the Member Property", 11792 "readOnly": true, 11793 "type": "string" 11794 }, 11795 "scene": { 11796 "description": "Specifies a scene value that will be acted upon", 11797 "type": "string" 11798 } 11799 }, 11800 "required": [ 11801 "scene", 11802 "memberProperty", 11803 "memberValue" 11804 ], 11805 "type": "object" 11806 }, 11807 "type": "array" 11808 }, 11809 "id": { 11810 "anyOf": [ 11811 { 11812 "maxLength": 64, 11813 "type": "string" 11814 }, 11815


{ 11816 "description": "Format pattern according to IETF RFC 4122.", 11817 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-11818 9]{12}$", 11819 "type": "string" 11820 } 11821 ], 11822 "description": "Instance ID of this specific resource", 11823 "readOnly": true 11824 }, 11825 "if": { 11826 "description": "The interface set supported by this resource", 11827 "items": { 11828 "enum": [ 11829 "oic.if.baseline", 11830 "oic.if.ll", 11831 "oic.if.b", 11832 "oic.if.lb", 11833 "oic.if.rw", 11834 "oic.if.r", 11835 "oic.if.a", 11836 "oic.if.s" 11837 ], 11838 "type": "string" 11839 }, 11840 "minItems": 1, 11841 "readOnly": true, 11842 "type": "array" 11843 }, 11844 "link": { 11845 "allOf": [ 11846 { 11847 "properties": { 11848 "anchor": { 11849 "description": "This is used to override the context URI e.g. override the URI 11850 of the containing collection.", 11851 "format": "uri", 11852 "maxLength": 256, 11853 "type": "string" 11854 }, 11855 "di": { 11856 "allOf": [ 11857 { 11858 "description": "Format pattern according to IETF RFC 4122.", 11859 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-11860 [a-fA-F0-9]{12}$", 11861 "type": "string" 11862 }, 11863 { 11864 "description": "The device ID" 11865 } 11866 ] 11867 }, 11868 "eps": { 11869 "description": "the Endpoint information of the target Resource", 11870 "items": { 11871 "properties": { 11872 "ep": { 11873 "description": "Transport Protocol Suite + Endpoint Locator", 11874 "format": "uri", 11875 "type": "string" 11876 }, 11877 "pri": { 11878 "description": "The priority among multiple Endpoints", 11879 "minimum": 1, 11880 "type": "integer" 11881 } 11882 }, 11883 "type": "object" 11884 }, 11885 "type": "array" 11886


}, 11887 "href": { 11888 "description": "This is the target URI, it can be specified as a Relative 11889 Reference or fully-qualified URI.", 11890 "format": "uri", 11891 "maxLength": 256, 11892 "type": "string" 11893 }, 11894 "if": { 11895 "description": "The interface set supported by this resource", 11896 "items": { 11897 "enum": [ 11898 "oic.if.baseline", 11899 "oic.if.ll", 11900 "oic.if.b", 11901 "oic.if.rw", 11902 "oic.if.r", 11903 "oic.if.a", 11904 "oic.if.s" 11905 ], 11906 "type": "string" 11907 }, 11908 "minItems": 1, 11909 "type": "array" 11910 }, 11911 "ins": { 11912 "description": "The instance identifier for this web link in an array of web 11913 links - used in collections", 11914 "oneOf": [ 11915 { 11916 "description": "An ordinal number that is not repeated - must be unique in 11917 the collection context.", 11918 "type": "integer" 11919 }, 11920 { 11921 "description": "A unique string", 11922 "format": "uri", 11923 "maxLength": 256, 11924 "type": "string" 11925 }, 11926 { 11927 "allOf": [ 11928 { 11929 "description": "Format pattern according to IETF RFC 4122.", 11930 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-11931 9]{4}-[a-fA-F0-9]{12}$", 11932 "type": "string" 11933 }, 11934 { 11935 "description": "A UUID" 11936 } 11937 ] 11938 } 11939 ] 11940 }, 11941 "p": { 11942 "description": "Specifies the framework policies on the Resource referenced by 11943 the target URI", 11944 "properties": { 11945 "bm": { 11946 "description": "Specifies the framework policies on the Resource referenced 11947 by the target URI for e.g. observable and discoverable", 11948 "type": "integer" 11949 } 11950 }, 11951 "required": [ 11952 "bm" 11953 ], 11954 "type": "object" 11955 }, 11956 "rel": { 11957


"description": "The relation of the target URI referenced by the link to the 11958 context URI", 11959 "oneOf": [ 11960 { 11961 "default": [ 11962 "hosts" 11963 ], 11964 "items": { 11965 "maxLength": 64, 11966 "type": "string" 11967 }, 11968 "minItems": 1, 11969 "type": "array" 11970 }, 11971 { 11972 "default": "hosts", 11973 "maxLength": 64, 11974 "type": "string" 11975 } 11976 ] 11977 }, 11978 "rt": { 11979 "description": "Resource Type of the Resource", 11980 "items": { 11981 "maxLength": 64, 11982 "type": "string" 11983 }, 11984 "minItems": 1, 11985 "type": "array" 11986 }, 11987 "title": { 11988 "description": "A title for the link relation. Can be used by the UI to provide 11989 a context.", 11990 "maxLength": 64, 11991 "type": "string" 11992 }, 11993 "type": { 11994 "default": "application/cbor", 11995 "description": "A hint at the representation of the resource referenced by the 11996 target URI. This represents the media types that are used for both accepting and emitting.", 11997 "items": { 11998 "maxLength": 64, 11999 "type": "string" 12000 }, 12001 "minItems": 1, 12002 "type": "array" 12003 } 12004 }, 12005 "required": [ 12006 "href", 12007 "rt", 12008 "if" 12009 ], 12010 "type": "object" 12011 }, 12012 { 12013 "description": "OCF link that points to a resource" 12014 } 12015 ] 12016 }, 12017 "n": { 12018 "description": "Friendly name of the resource", 12019 "maxLength": 64, 12020 "readOnly": true, 12021 "type": "string" 12022 }, 12023 "rt": { 12024 "description": "Resource Type of the Resource", 12025 "items": { 12026 "maxLength": 64, 12027 "type": "string" 12028


}, 12029 "minItems": 1, 12030 "readOnly": true, 12031 "type": "array" 12032 } 12033 }, 12034 "required": [ 12035 "link" 12036 ], 12037 "type": "object" 12038 } 12039 12040 , 12041 "SceneCollection" : 12042 { 12043 "allOf": [ 12044 { 12045 "description": "A collection is a set of links along with additional properties to 12046 describe the collection itself", 12047 "properties": { 12048 "links": { 12049 "description": "All forms of links in a collection.", 12050 "oneOf": [ 12051 { 12052 "description": "A set of simple or individual OIC Links.", 12053 "items": { 12054 "properties": { 12055 "anchor": { 12056 "description": "This is used to override the context URI e.g. override 12057 the URI of the containing collection.", 12058 "format": "uri", 12059 "maxLength": 256, 12060 "type": "string" 12061 }, 12062 "di": { 12063 "allOf": [ 12064 { 12065 "description": "Format pattern according to IETF RFC 4122.", 12066 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-12067 9]{4}-[a-fA-F0-9]{12}$", 12068 "type": "string" 12069 }, 12070 { 12071 "description": "The device ID" 12072 } 12073 ] 12074 }, 12075 "eps": { 12076 "description": "the Endpoint information of the target Resource", 12077 "items": { 12078 "properties": { 12079 "ep": { 12080 "description": "Transport Protocol Suite + Endpoint Locator", 12081 "format": "uri", 12082 "type": "string" 12083 }, 12084 "pri": { 12085 "description": "The priority among multiple Endpoints", 12086 "minimum": 1, 12087 "type": "integer" 12088 } 12089 }, 12090 "type": "object" 12091 }, 12092 "type": "array" 12093 }, 12094 "href": { 12095 "description": "This is the target URI, it can be specified as a Relative 12096 Reference or fully-qualified URI.", 12097 "format": "uri", 12098 "maxLength": 256, 12099


"type": "string" 12100 }, 12101 "if": { 12102 "description": "The interface set supported by this resource", 12103 "items": { 12104 "enum": [ 12105 "oic.if.baseline", 12106 "oic.if.ll", 12107 "oic.if.b", 12108 "oic.if.rw", 12109 "oic.if.r", 12110 "oic.if.a", 12111 "oic.if.s" 12112 ], 12113 "type": "string" 12114 }, 12115 "minItems": 1, 12116 "type": "array" 12117 }, 12118 "ins": { 12119 "description": "The instance identifier for this web link in an array of 12120 web links - used in collections", 12121 "oneOf": [ 12122 { 12123 "description": "An ordinal number that is not repeated - must be 12124 unique in the collection context.", 12125 "type": "integer" 12126 }, 12127 { 12128 "description": "A unique string", 12129 "format": "uri", 12130 "maxLength": 256, 12131 "type": "string" 12132 }, 12133 { 12134 "allOf": [ 12135 { 12136 "description": "Format pattern according to IETF RFC 4122.", 12137 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-12138 F0-9]{4}-[a-fA-F0-9]{12}$", 12139 "type": "string" 12140 }, 12141 { 12142 "description": "A UUID" 12143 } 12144 ] 12145 } 12146 ] 12147 }, 12148 "p": { 12149 "description": "Specifies the framework policies on the Resource 12150 referenced by the target URI", 12151 "properties": { 12152 "bm": { 12153 "description": "Specifies the framework policies on the Resource 12154 referenced by the target URI for e.g. observable and discoverable", 12155 "type": "integer" 12156 } 12157 }, 12158 "required": [ 12159 "bm" 12160 ], 12161 "type": "object" 12162 }, 12163 "rel": { 12164 "description": "The relation of the target URI referenced by the link to 12165 the context URI", 12166 "oneOf": [ 12167 { 12168 "default": [ 12169 "hosts" 12170


], 12171 "items": { 12172 "maxLength": 64, 12173 "type": "string" 12174 }, 12175 "minItems": 1, 12176 "type": "array" 12177 }, 12178 { 12179 "default": "hosts", 12180 "maxLength": 64, 12181 "type": "string" 12182 } 12183 ] 12184 }, 12185 "rt": { 12186 "description": "Resource Type of the Resource", 12187 "items": { 12188 "maxLength": 64, 12189 "type": "string" 12190 }, 12191 "minItems": 1, 12192 "type": "array" 12193 }, 12194 "title": { 12195 "description": "A title for the link relation. Can be used by the UI to 12196 provide a context.", 12197 "maxLength": 64, 12198 "type": "string" 12199 }, 12200 "type": { 12201 "default": "application/cbor", 12202 "description": "A hint at the representation of the resource referenced 12203 by the target URI. This represents the media types that are used for both accepting and emitting.", 12204 "items": { 12205 "maxLength": 64, 12206 "type": "string" 12207 }, 12208 "minItems": 1, 12209 "type": "array" 12210 } 12211 }, 12212 "required": [ 12213 "href", 12214 "rt", 12215 "if" 12216 ], 12217 "type": "object" 12218 }, 12219 "type": "array" 12220 } 12221 ] 12222 }, 12223 "rts": { 12224 "allOf": [ 12225 { 12226 "description": "Resource Type of the Resource", 12227 "items": { 12228 "maxLength": 64, 12229 "type": "string" 12230 }, 12231 "minItems": 1, 12232 "readOnly": true, 12233 "type": "array" 12234 }, 12235 { 12236 "description": "The list of allowable resource types (for Target and anchors) 12237 in links included in the collection" 12238 } 12239 ] 12240 } 12241


}, 12242 "type": "object" 12243 }, 12244 { 12245 "properties": { 12246 "id": { 12247 "anyOf": [ 12248 { 12249 "maxLength": 64, 12250 "type": "string" 12251 }, 12252 { 12253 "description": "Format pattern according to IETF RFC 4122.", 12254 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-12255 F0-9]{12}$", 12256 "type": "string" 12257 } 12258 ], 12259 "description": "Instance ID of this specific resource", 12260 "readOnly": true 12261 }, 12262 "if": { 12263 "description": "The interface set supported by this resource", 12264 "items": { 12265 "enum": [ 12266 "oic.if.baseline", 12267 "oic.if.ll", 12268 "oic.if.b", 12269 "oic.if.lb", 12270 "oic.if.rw", 12271 "oic.if.r", 12272 "oic.if.a", 12273 "oic.if.s" 12274 ], 12275 "type": "string" 12276 }, 12277 "minItems": 1, 12278 "readOnly": true, 12279 "type": "array" 12280 }, 12281 "lastScene": { 12282 "description": "Last selected Scene from the set of sceneValues", 12283 "type": "string" 12284 }, 12285 "n": { 12286 "description": "Friendly name of the resource", 12287 "maxLength": 64, 12288 "readOnly": true, 12289 "type": "string" 12290 }, 12291 "rt": { 12292 "description": "Resource Type of the Resource", 12293 "items": { 12294 "maxLength": 64, 12295 "type": "string" 12296 }, 12297 "minItems": 1, 12298 "readOnly": true, 12299 "type": "array" 12300 }, 12301 "sceneValues": { 12302 "description": "All available scene values", 12303 "items": { 12304 "type": "string" 12305 }, 12306 "readOnly": true, 12307 "type": "array" 12308 } 12309 } 12310 } 12311 ], 12312


"required": [ 12313 "lastScene", 12314 "sceneValues", 12315 "rts", 12316 "id" 12317 ], 12318 "type": "object" 12319 } 12320 12321 , 12322 "SceneCollectionUpdate" : 12323 { 12324 "allOf": [ 12325 { 12326 "description": "A collection is a set of links along with additional properties to 12327 describe the collection itself", 12328 "properties": { 12329 "links": { 12330 "description": "All forms of links in a collection.", 12331 "oneOf": [ 12332 { 12333 "description": "A set of simple or individual OIC Links.", 12334 "items": { 12335 "properties": { 12336 "anchor": { 12337 "description": "This is used to override the context URI e.g. override 12338 the URI of the containing collection.", 12339 "format": "uri", 12340 "maxLength": 256, 12341 "type": "string" 12342 }, 12343 "di": { 12344 "allOf": [ 12345 { 12346 "description": "Format pattern according to IETF RFC 4122.", 12347 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-12348 9]{4}-[a-fA-F0-9]{12}$", 12349 "type": "string" 12350 }, 12351 { 12352 "description": "The device ID" 12353 } 12354 ] 12355 }, 12356 "eps": { 12357 "description": "the Endpoint information of the target Resource", 12358 "items": { 12359 "properties": { 12360 "ep": { 12361 "description": "Transport Protocol Suite + Endpoint Locator", 12362 "format": "uri", 12363 "type": "string" 12364 }, 12365 "pri": { 12366 "description": "The priority among multiple Endpoints", 12367 "minimum": 1, 12368 "type": "integer" 12369 } 12370 }, 12371 "type": "object" 12372 }, 12373 "type": "array" 12374 }, 12375 "href": { 12376 "description": "This is the target URI, it can be specified as a Relative 12377 Reference or fully-qualified URI.", 12378 "format": "uri", 12379 "maxLength": 256, 12380 "type": "string" 12381 }, 12382 "if": { 12383


"description": "The interface set supported by this resource", 12384 "items": { 12385 "enum": [ 12386 "oic.if.baseline", 12387 "oic.if.ll", 12388 "oic.if.b", 12389 "oic.if.rw", 12390 "oic.if.r", 12391 "oic.if.a", 12392 "oic.if.s" 12393 ], 12394 "type": "string" 12395 }, 12396 "minItems": 1, 12397 "type": "array" 12398 }, 12399 "ins": { 12400 "description": "The instance identifier for this web link in an array of 12401 web links - used in collections", 12402 "oneOf": [ 12403 { 12404 "description": "An ordinal number that is not repeated - must be 12405 unique in the collection context.", 12406 "type": "integer" 12407 }, 12408 { 12409 "description": "A unique string", 12410 "format": "uri", 12411 "maxLength": 256, 12412 "type": "string" 12413 }, 12414 { 12415 "allOf": [ 12416 { 12417 "description": "Format pattern according to IETF RFC 4122.", 12418 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-12419 F0-9]{4}-[a-fA-F0-9]{12}$", 12420 "type": "string" 12421 }, 12422 { 12423 "description": "A UUID" 12424 } 12425 ] 12426 } 12427 ] 12428 }, 12429 "p": { 12430 "description": "Specifies the framework policies on the Resource 12431 referenced by the target URI", 12432 "properties": { 12433 "bm": { 12434 "description": "Specifies the framework policies on the Resource 12435 referenced by the target URI for e.g. observable and discoverable", 12436 "type": "integer" 12437 } 12438 }, 12439 "required": [ 12440 "bm" 12441 ], 12442 "type": "object" 12443 }, 12444 "rel": { 12445 "description": "The relation of the target URI referenced by the link to 12446 the context URI", 12447 "oneOf": [ 12448 { 12449 "default": [ 12450 "hosts" 12451 ], 12452 "items": { 12453 "maxLength": 64, 12454


"type": "string" 12455 }, 12456 "minItems": 1, 12457 "type": "array" 12458 }, 12459 { 12460 "default": "hosts", 12461 "maxLength": 64, 12462 "type": "string" 12463 } 12464 ] 12465 }, 12466 "rt": { 12467 "description": "Resource Type of the Resource", 12468 "items": { 12469 "maxLength": 64, 12470 "type": "string" 12471 }, 12472 "minItems": 1, 12473 "type": "array" 12474 }, 12475 "title": { 12476 "description": "A title for the link relation. Can be used by the UI to 12477 provide a context.", 12478 "maxLength": 64, 12479 "type": "string" 12480 }, 12481 "type": { 12482 "default": "application/cbor", 12483 "description": "A hint at the representation of the resource referenced 12484 by the target URI. This represents the media types that are used for both accepting and emitting.", 12485 "items": { 12486 "maxLength": 64, 12487 "type": "string" 12488 }, 12489 "minItems": 1, 12490 "type": "array" 12491 } 12492 }, 12493 "required": [ 12494 "href", 12495 "rt", 12496 "if" 12497 ], 12498 "type": "object" 12499 }, 12500 "type": "array" 12501 } 12502 ] 12503 }, 12504 "rts": { 12505 "allOf": [ 12506 { 12507 "description": "Resource Type of the Resource", 12508 "items": { 12509 "maxLength": 64, 12510 "type": "string" 12511 }, 12512 "minItems": 1, 12513 "readOnly": true, 12514 "type": "array" 12515 }, 12516 { 12517 "description": "The list of allowable resource types (for Target and anchors) 12518 in links included in the collection" 12519 } 12520 ] 12521 } 12522 }, 12523 "type": "object" 12524 }, 12525


{ 12526 "properties": { 12527 "id": { 12528 "anyOf": [ 12529 { 12530 "maxLength": 64, 12531 "type": "string" 12532 }, 12533 { 12534 "description": "Format pattern according to IETF RFC 4122.", 12535 "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-12536 F0-9]{12}$", 12537 "type": "string" 12538 } 12539 ], 12540 "description": "Instance ID of this specific resource", 12541 "readOnly": true 12542 }, 12543 "if": { 12544 "description": "The interface set supported by this resource", 12545 "items": { 12546 "enum": [ 12547 "oic.if.baseline", 12548 "oic.if.ll", 12549 "oic.if.b", 12550 "oic.if.lb", 12551 "oic.if.rw", 12552 "oic.if.r", 12553 "oic.if.a", 12554 "oic.if.s" 12555 ], 12556 "type": "string" 12557 }, 12558 "minItems": 1, 12559 "readOnly": true, 12560 "type": "array" 12561 }, 12562 "lastScene": { 12563 "description": "Last selected Scene from the set of sceneValues", 12564 "type": "string" 12565 }, 12566 "n": { 12567 "description": "Friendly name of the resource", 12568 "maxLength": 64, 12569 "readOnly": true, 12570 "type": "string" 12571 }, 12572 "rt": { 12573 "description": "Resource Type of the Resource", 12574 "items": { 12575 "maxLength": 64, 12576 "type": "string" 12577 }, 12578 "minItems": 1, 12579 "readOnly": true, 12580 "type": "array" 12581 } 12582 } 12583 } 12584 ], 12585 "required": [ 12586 "lastScene" 12587 ], 12588 "type": "object" 12589 } 12590 12591 } 12592 } 12593 12594



Property name Value type Mandatory Access mode Description id multiple types:



link multiple types: see schema

yes




SceneMappings array: see schema

array of mappings per scene, can be one(1)




href string yes This is the target URI, it can be specified as a Relative Reference or fully-qualified URI.











The relation of the target URI


referenced by the link to the context URI










links multiple types: see schema

All forms of links in a collection.








lastScene string yes Last selected Scene from the set of sceneValues


yes Read Only Instance ID of this specific resource

lastScene string yes Last selected Scene from the set of sceneValues


sceneValues array: see schema

yes Read Only All available scene values







Resource Create Read Update Delete Notify /SceneListResURI get

12597

12598

OCF Core specification v1.3...1) 3) 7)

Documents