idnits 2.17.1 draft-lynn-t2trg-model-rest-apis-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 22, 2016) is 2986 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC7231' is defined on line 359, but no explicit reference was found in the text == Unused Reference: 'RFC7252' is defined on line 364, but no explicit reference was found in the text == Unused Reference: 'REST' is defined on line 386, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) == Outdated reference: A later version (-10) exists of draft-ietf-core-links-json-04 Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Lynn 3 Internet-Draft L. Dornin 4 Intended status: Informational Verizon Labs 5 Expires: August 25, 2016 February 22, 2016 7 Modeling RESTful APIs with JSON Hyper-Schema 8 draft-lynn-t2trg-model-rest-apis-00 10 Abstract 12 This document explores JSON Hyper-Schema as a method of modeling 13 Internet of Things (IoT) systems that follow the principles of the 14 Representational State Transfer (REST) architectural style. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on August 25, 2016. 33 Copyright Notice 35 Copyright (c) 2016 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Overview of JSON Schema and Hyper-Schema . . . . . . . . . . 3 52 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 54 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 55 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 56 Appendix A. Future Work . . . . . . . . . . . . . . . . . . . . 9 57 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 59 1. Introduction 61 The central problem in an IoT domain such as home control might be 62 characterized as "translating intention into configuration". The 63 challenge is to translate a high level goal such as "turn off all the 64 lights on the first floor", expressed in a natural language, into 65 action. An agent trying to accomplish this goal might look up 66 "light" in a semantic registry, discover instances of "light", select 67 those instances that fall within a given area, etc., and ultimately 68 transmit control packets to devices that match the given criterea. 70 A user defining such a goal should not be concerned with the under- 71 lying technology, i.e., details of the protocols or data links over 72 which the control packets are sent. Similarly, service providers or 73 developers wishing to provide home control solutions would generally 74 prefer them to be technology agnostic. As with other translation 75 tasks, this can more easily be accomplished by using one or more 76 intermediate abstraction layers. 78 Recent research in semantic interoperability in heterogeneous 79 environments has underscored the need for semantic alignment at 80 various levels [Semantic-Interop]. This document is concerned with 81 identifying a fairly primitive abstraction that sufficiently models 82 target state and behavior without overly specifying the details of 83 the underlying technology. We proprose to explore REST APIs as a 84 reasonable layer at which to abstract devices. 86 JSON Hyper-Schema [I-D.luff-json-hyper-schema] is a formalism for 87 describing RESTful APIs. It supports a description of inbound and 88 outbound data across the interface, together with link descriptions 89 that identify the URIs, link-relations, and methods that apply to 90 links. JSON Hyper-Schema therefore supports the principal of 91 Hypertext as the Engine of Application State. It may also serve as 92 input to documentation and code generation tools. 94 2. Overview of JSON Schema and Hyper-Schema 96 JSON Schema is a JSON based format for defining the structure of JSON 97 data [RFC7159][I-D.zyp-json-schema]. JSON Hyper-Schema adds 98 hyperlink- and hyper-media related keywords to JSON Schema. This 99 section simply lists features of JSON Schema and Hyper-Schema used in 100 the examples. For a detailed overview, see 101 [Understanding-JSON-Schema] 103 2.1. JSON Schema 105 JSON Schema supports: 107 - JSON data types: object, array, number, string, boolean, null 109 - $schema keyword: value identifies meta-schema and version 111 - Definitions and JSON references promote fragment reuse 113 - Schema composition keywords: oneOf, anyOf, allOf 115 - Patterns, regular expressions, more... 117 2.2. JSON Hyper-Schema 119 JSON Hyper-Schema adds Link Description Objects which include: 121 - href: URI template 123 - rel: link relation 125 - title: a title for the link 127 - targetSchema: JSON Schema describing the link target 129 - mediaType: media type describing the link target 131 - method: REST method that applies to this link 133 - encType: media type of the request 135 - schema: Schema describing the data sent with the request 137 3. Examples 139 The following examples may be validated at http://json-schema- 140 validator.herokuapp.com/. The first example may be converted to 141 markdown using the prmd tool at https://github.com/interagent/prmd. 143 3.1. Binary Switch Hyper-Schema 145 This JSON Hyper-Schema models a generic device on/off capability. 147 { 148 "$schema": "http://json-schema.org/draft-04/hyper-schema#", 149 "id": "http://example.com/schemata/switch-binary#", 150 "description": "A simple API for a device that supports on/off.", 151 "type": [ 152 "object" 153 ], 154 "definitions": { 155 "uuid": { 156 "description": "Unique identifier of the device", 157 "example": "01234567-89ab-cdef-0123-456789abcdef", 158 "format": "uuid", 159 "readOnly": true, 160 "type": [ 161 "string" 162 ] 163 }, 164 "identity": { 165 "anyOf": [ 166 { 167 "$ref": "#/definitions/uuid" 168 } 169 ] 170 }, 171 "invalidated": { 172 "description": "Time resource was invalidated", 173 "example": "2015-01-01T12:00:00Z", 174 "format": "date-time", 175 "readOnly": true, 176 "type": [ 177 "string" 178 ] 179 }, 180 "updated": { 181 "description": "Time resource was last updated", 182 "example": "2015-01-01T12:00:01Z", 183 "format": "date-time", 184 "readOnly": true, 185 "type": [ 186 "string" 187 ] 188 }, 189 "SwBinary": { 190 "title": "Binary Switch", 191 "description": "Used to control devices with On/Off capability.", 192 "stability": "prototype", 193 "type": [ 194 "object" 195 ], 196 "definitions": { 197 "SetValue": { 198 "description": "0..99 (level) or 255 (on)", 199 "example": 50, 200 "type": "number", 201 "multipleOf": 1, 202 "oneOf": [ 203 { 204 "minimum": 0, 205 "maximum": 99 206 }, 207 { 208 "enum": [ 209 255 210 ] 211 } 212 ] 213 }, 214 "GetValue": { 215 "description": "0 (off) or 255 (on)", 216 "example": 255, 217 "type": "number", 218 "multipleOf": 1, 219 "oneOf": [ 220 { 221 "enum": [ 222 0, 223 255 224 ] 225 } 226 ] 227 } 228 }, 229 "properties": { 230 "invalidated": { 231 "$ref": "#/definitions/invalidated" 232 }, 233 "updated": { 234 "$ref": "#/definitions/updated" 235 }, 236 "Value": { 237 "$ref": "#/definitions/SwBinary/definitions/GetValue" 238 } 240 }, 241 "links": [ 242 { 243 "title": "Set", 244 "description": "Update a specific Binary Switch instance.", 245 "href": "/id/{(%23%2Fdefinitions%2Fidentity)}/SwBinary/Set", 246 "method": "POST", 247 "rel": "update", 248 "schema": { 249 "type": [ 250 "object" 251 ], 252 "properties": { 253 "Value": { 254 "$ref": "#/definitions/SwBinary/definitions/SetValue" 255 } 256 }, 257 "required": [ 258 "Value" 259 ], 260 "strictProperties": true 261 } 262 }, 263 { 264 "title": "Get", 265 "description": "Read a specific Binary Switch instance.", 266 "href": "/id/{(%23%2Fdefinitions%2Fidentity)}/SwBinary/Get", 267 "method": "GET", 268 "rel": "self", 269 "targetSchema": { 270 "$ref": "#/definitions/SwBinary" 271 } 272 } 273 ] 274 } 275 }, 276 "properties": { 277 "SwBinary": { 278 "$ref": "#/definitions/SwBinary" 279 } 280 }, 281 "additionalProperties": false, 282 "links": [ 283 { 284 "href": "https:/", 285 "rel": "self" 286 }, 287 { 288 "href": "/dev-schema", 289 "method": "GET", 290 "rel": "self", 291 "targetSchema": { 292 "additionalProperties": true 293 } 294 } 295 ] 296 } 298 3.2. JSON Link-Format Document 300 With the addition of the required "rel" property to each Link 301 Description Object, the link-format example from section 2.4 of 302 [I-D.ietf-core-links-json] becomes a valid JSON Hyper-Schema 303 document. 305 [ 306 { 307 "href": "/sensors", 308 "ct": "40", 309 "title": "SensorIndex", 310 "rel": "self" 311 }, 312 { 313 "href": "/sensors/temp", 314 "rt": "temperature-c", 315 "if": "sensor", 316 "rel": "self" 317 }, 318 { 319 "href": "/sensors/light", 320 "rt": "light-lux", 321 "if": "sensor", 322 "rel": "self" 323 }, 324 { 325 "href": "http://www.example.com/sensors/t123", 326 "anchor": "/sensors/temp", 327 "rel": "describedby" 328 }, 329 { 330 "href": "/t", 331 "anchor": "/sensors/temp", 332 "rel": "alternate" 333 } 334 ] 336 4. IANA Considerations 338 This document makes no request of IANA. 340 Note to RFC Editor: this section may be removed upon publication as 341 an RFC. 343 5. Security Considerations 345 This document doesn't define new functionality and therefore doesn't 346 introduce new security concerns. However, security considerations 347 from related specifications apply: 349 o JSON security: section 12 of [RFC7159] 351 6. References 353 6.1. Normative References 355 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 356 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 357 2014, . 359 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 360 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 361 DOI 10.17487/RFC7231, June 2014, 362 . 364 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 365 Application Protocol (CoAP)", RFC 7252, 366 DOI 10.17487/RFC7252, June 2014, 367 . 369 6.2. Informative References 371 [I-D.luff-json-hyper-schema] 372 Luff, G., Zyp, K., and G. Court, "JSON Hyper-Schema: 373 Hypertext definitions for JSON Schema", draft-luff-json- 374 hyper-schema-00 (work in progress), January 2013. 376 [I-D.zyp-json-schema] 377 Galiegue, F., Zyp, K., and G. Court, "JSON Schema: core 378 definitions and terminology", draft-zyp-json-schema-04 379 (work in progress), January 2013. 381 [I-D.ietf-core-links-json] 382 Li, K., Rahman, A., and C. Bormann, "Representing CoRE 383 Formats in JSON and CBOR", draft-ietf-core-links-json-04 384 (work in progress), November 2015. 386 [REST] Fielding, R., "Architectural Styles and the Design of 387 Network-based Software Architectures", Ph.D. 388 Dissertation , University of California, Irvine , 2000, 389 . 392 [Understanding-JSON-Schema] 393 Droettboom, M., "Understanding JSON Schema, Release 1.0", 394 Space Telescope Science Institute , February 2015, 395 . 398 [Semantic-Interop] 399 Konstantinos, K. and A. Katasonov, "Semantic 400 Interoperability on the Web of Things: The Smart Gateway 401 Framework", VTT Technical Research Center Tampere, 402 Finland, DOI 10.1109/CISIS.2012.200, 2012, 403 . 407 Appendix A. Future Work 409 o Provide more examples. 411 o Discuss relationship to higher semantic layer(s). 413 Authors' Addresses 415 Kerry Lynn 416 Verizon Labs 417 50-60 Sylvan Rd 418 Waltham , MA 02451 419 USA 421 Phone: +1 781 296 9722 422 Email: kerlyn@ieee.org 423 Laird Dornin 424 Verizon Labs 425 50-60 Sylvan Rd 426 Waltham , MA 02451 427 USA 429 Phone: +1 781 466 2062 430 Email: laird.dornin@verizon.com