idnits 2.17.1 draft-ietf-vwrap-type-system-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 5, 2010) is 5044 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'Kaye2003' is defined on line 1324, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ECMA262r5' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) -- Possible downref: Non-RFC (?) normative reference: ref. 'TR15' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML2006' -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Virtual World Region Agent A. Brashears 3 Protocol M. Hamrick 4 Internet-Draft M. Lentczner 5 Intended status: Standards Track July 5, 2010 6 Expires: January 6, 2011 8 VWRAP : Abstract Type System for the Transmission of Dynamic Structured 9 Data 10 draft-ietf-vwrap-type-system-00 12 Abstract 14 This document describes the LLIDL interface description language, the 15 related LLSD abstract type system and three serialization formats for 16 LLIDL messages. LLIDL (pronounced "little") is a language-neutral 17 facility for describing transport independent message flows for 18 RESTful resource access. LLIDL itself is an abstract meta-grammar 19 for producing and recognizing valid request / response messages 20 affecting state change in application layer objects by way of RESTful 21 resource access. It may be used by protocol developers and system 22 deployers to describe the composition of application layer protocol 23 exchanges without adopting transport specific message semantics or 24 programming language specific type semantics. The type behavior of 25 individual message elements is described by the LLSD abstract type 26 system. Abstract LLIDL messages are concretized using one of three 27 defined LLSD serialization schemes. Serialization / deserialization 28 rules are provided in this document for XML, JSON and Binary schemes. 29 This abstract messaging and type system is intended to be used by 30 other specifications to describe application layer protocol 31 exchanges, independent of implementation language or message 32 transport protocol. 34 Status of this Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 6, 2011. 50 Copyright Notice 52 Copyright (c) 2010 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 6 69 2. The LLSD Abstract Type System . . . . . . . . . . . . . . . . 6 70 2.1. Simple Types . . . . . . . . . . . . . . . . . . . . . . . 6 71 2.1.1. Undefined . . . . . . . . . . . . . . . . . . . . . . 7 72 2.1.2. Boolean . . . . . . . . . . . . . . . . . . . . . . . 7 73 2.1.3. Integer . . . . . . . . . . . . . . . . . . . . . . . 7 74 2.1.4. Real . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 2.1.5. String . . . . . . . . . . . . . . . . . . . . . . . . 8 76 2.1.6. UUID (Universally Unique ID) . . . . . . . . . . . . . 9 77 2.1.7. Date . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 2.1.8. URI (Uniform Resource Identifier) . . . . . . . . . . 9 79 2.1.9. Binary . . . . . . . . . . . . . . . . . . . . . . . . 10 80 2.2. Composite Types . . . . . . . . . . . . . . . . . . . . . 10 81 2.2.1. Array . . . . . . . . . . . . . . . . . . . . . . . . 10 82 2.2.2. Map . . . . . . . . . . . . . . . . . . . . . . . . . 10 83 2.3. Converting Between Real and String Types . . . . . . . . . 11 84 2.4. Converting Between Date and String Types . . . . . . . . . 11 85 3. The LLIDL Interface Description Language . . . . . . . . . . . 11 86 3.1. Interfaces and Resources . . . . . . . . . . . . . . . . . 11 87 3.2. Simple Types . . . . . . . . . . . . . . . . . . . . . . . 12 88 3.3. Composite Types . . . . . . . . . . . . . . . . . . . . . 12 89 3.3.1. Arrays . . . . . . . . . . . . . . . . . . . . . . . . 12 90 3.3.2. Maps . . . . . . . . . . . . . . . . . . . . . . . . . 13 91 3.4. Named Types . . . . . . . . . . . . . . . . . . . . . . . 14 92 3.5. Variant Type Definitions . . . . . . . . . . . . . . . . . 15 93 4. Serialization . . . . . . . . . . . . . . . . . . . . . . . . 16 94 4.1. XML Serialization . . . . . . . . . . . . . . . . . . . . 16 95 4.1.1. Serializing Simple Types . . . . . . . . . . . . . . . 17 96 4.1.2. Serializing Composite Types . . . . . . . . . . . . . 17 97 4.1.3. Example of XML LLSD Serialization . . . . . . . . . . 18 98 4.2. JSON Serialization . . . . . . . . . . . . . . . . . . . . 18 99 4.2.1. Examples of JSON LLSD Serialization . . . . . . . . . 20 100 4.3. Binary Serialization . . . . . . . . . . . . . . . . . . . 20 101 4.3.1. Example of BINARY LLSD Serialization . . . . . . . . . 22 102 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 103 6. MIME Type Registrations . . . . . . . . . . . . . . . . . . . 25 104 6.1. MIME Type Registration for application/llidl . . . . . . . 25 105 6.2. MIME Type Registration for application/llsd+xml . . . . . 26 106 6.3. MIME Type Registration for application/llsd+json . . . . . 28 107 6.4. MIME Type Registration for application/llsd+binary . . . . 29 108 7. Security Considerations . . . . . . . . . . . . . . . . . . . 30 109 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 110 8.1. Normative References . . . . . . . . . . . . . . . . . . . 31 111 8.2. Informative References . . . . . . . . . . . . . . . . . . 32 112 Appendix A. ABNF of Real Values . . . . . . . . . . . . . . . . . 33 113 Appendix B. XML Serialization DTD . . . . . . . . . . . . . . . . 34 114 Appendix C. ABNF of LLIDL . . . . . . . . . . . . . . . . . . . . 34 115 Appendix D. Glossary . . . . . . . . . . . . . . . . . . . . . . 36 116 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 39 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 39 119 1. Introduction 121 It is characteristic of modern network services that they are 122 deployed across multiple network hosts. For performance, fault 123 tolerance, ease of deployment or organizational reasons, software and 124 systems implementing network services must now work well in a 125 distributed environment. It is generally believed that such 126 distributed services may be made more robust by making their 127 components "loosely coupled."[Kaye2003] This document describes an 128 interface description language and a related abstract type system 129 used to define interfaces to loosely coupled network services in a 130 programming language, network transport and message serialization 131 independent manner. 133 The LLIDL interface description language may be used to define 134 protocol exchanges for accessing resources exhibiting characteristics 135 of the Representational State Transfer (REST) architecture style. 136 [Fielding2000] LLIDL describes abstract interfaces intended to be 137 reified over HTTP [RFC2616] or HTTPS [RFC2817]. LLIDL resource 138 definitions describe the structure of data provided in an access 139 request, the structure of the data in the access' response and the 140 HTTP verbs which may be used to access the resource. 142 The LLSD abstract type system defines nine simple types (Undefined, 143 Boolean, Integer, Real, String, UUID, Date, URI and Binary) and two 144 composite types (Array and Map.) This system provides a programming 145 language independent framework for describing type semantics of 146 elements in LLIDL messages. Three serialization schemes are defined 147 by this document: XML, JSON and Binary. These schemes are used to 148 concretize LLSD data into octet streams for transmission over a data 149 network. Each serialization scheme has a related MIME content type 150 definition, allowing compliant applications to identify the specific 151 serialization scheme used. 153 LLIDL and LLSD form an abstract system for reasoning about 154 application layer exchanges without having to repeatedly reference 155 the details of the transport used to deliver messages. Other 156 specifications use LLIDL and LLSD to describe the content of RESTful 157 resource access. This document describes how resource accesses are 158 reified as HTTP(S) protocol exchanges. LLIDL is intended to separate 159 the semantics of application messages from the details of the 160 protocol that carries them. It gives system deployers a tool for 161 succinctly defining application layer exchanges. 163 The LLSD serialization schemes describe how simple and composite 164 types are converted into an octet stream and provides guidelines for 165 transmission across a network. It does not describe the 166 concretization of abstract LLSD messages into programming language 167 constructs. 169 1.1. Requirements Language 171 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 172 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 173 document are to be interpreted as described in RFC 2119 [RFC2119]. 175 2. The LLSD Abstract Type System 177 The LLSD abstract type system describes the semantics of data passed 178 between two network hosts. These types characterize the data when 179 serialized for transport, when stored in memory, and when accessed by 180 applications. 182 The types are designed to be common enough that native types in 183 existing serializations and programming languages will be usable 184 directly. It is anticipated that LLSD data may be serialized in 185 systems with fewer types or stored in native programming language 186 structures with less precise types, and still interoperate in a 187 predictable, reliable manner. To support this, conversions are 188 defined to govern how data received or stored as one type may be read 189 as another. 191 For example, if an application expects to read an LLSD value as an 192 Integer, but the serialization used to transport the value only 193 supported Reals, then a conversion governs how the application will 194 see the transported value. Another case would be where an 195 application wants to read an LLSD value as a URL, but the programing 196 language only supports String as a data type. Again, there is a 197 defined conversion for this case. 199 The intention is that applications will interact with LLSD data via 200 interfaces in terms of these types, even if the underlying language 201 or transports do not directly support them, while retaining as much 202 direct compatibility with those native types as possible. 204 An LLSD value is either a simple datum or a composite structure. A 205 simple data value can have one of nine simple types: Undefined, 206 Boolean, Integer, Real, String, UUID, Date, URI or Binary. Composite 207 structures can be either of the types Array or Map. 209 2.1. Simple Types 211 For each type, conversions are defined to that type. That is, if a 212 process is accessing a particular LLSD value, and treating it as a 213 particular type, but the underlying type (as transmitted, or stored 214 in memory) is different, then the indicated conversion, if defined, 215 is applied. If a conversion is not specified from a particular type, 216 then if a value of that type is accessed, the result is the default 217 value for the expected type. For example: When reading a value as an 218 integer, if the underlying value is binary, then the value read is 219 zero. 221 2.1.1. Undefined 223 Data of type Undefined has only one value, called undef. The default 224 value is undef. There are no defined conversions to Undefined. 226 The Undefined type is a placeholder for a value. 228 2.1.2. Boolean 230 Data of type Boolean can have one of only two values: true or false. 231 The default value is false. 233 Conversions: 235 Integer A zero value (0) is converted to false. All other values 236 are converted to true. 238 Real A zero value (0.0) and invalid floating point values (NaNs) are 239 converted to false. All other values are converted to true. 241 String An empty String is converted to false. Anything else is 242 converted to true. 244 2.1.3. Integer 246 Data of type Integer can have the values of natural numbers between 247 -2147483648 and 2147483647 inclusive. The default value for Integer 248 is zero (0). 250 Conversions: 252 Boolean The value true is converted to the Integer 1. The value 253 false is converted to the Integer 0. 255 Real Real are rounded to the nearest representable Integer, with 256 ties being rounded to the nearest even number. Invalid floating 257 point values (NaNs) are converted to the Integer 0. 259 String The string is first converted to type Real, see Section 2.3. 260 Then the resulting Real is converted to Integer as specified 261 above. 263 2.1.4. Real 265 Data of type contain signed floating precision numeric values from 266 the range available with IEEE 754-1985 64-bit double precision 267 values, as well as the special non-numeric values (NaNs and Infs) 268 available with that format. The default value for Real is zero 269 (0.0). 271 Conversions: 273 Boolean The value true is converted to the floating point value 1.0. 274 The value false is converted to the floating point value 0.0. 276 Integer Integers promoted to floating point values are converted to 277 the nearest representable number. 279 String See Section 2.3. 281 2.1.5. String 283 Data of type String contain a sequence of zero or more Unicode code 284 points. The default value for String is a sequence of zero code 285 points, the empty string (""). 287 The characters are restricted to the following code points: 289 U+0009, U+000A, U+000D 291 U+0020 through U+D7FF 293 U+E000 through U+FFFD 295 U+10000 through U+10FFFF 297 Strings may be normalized during transport, storage or processing. 298 When an implementation does normalize, it should use Normalization 299 Form C (NFC) described in Unicode Standard Annex #15 [TR15]. Line 300 endings may be normalized to U+000A. 302 Conversions: 304 Boolean The value true is represented as the string "true". The 305 value false is represented as the empty string (""). 307 Integer Integers converted to Strings are represented as signed 308 decimal representation. 310 Real See Section 2.3. 312 UUID UUIDs converted to Strings are represented in the 36 character, 313 8-4-4-4-12 format defined in RFC 4122 [RFC4122]. 315 Date See Section 2.4. 317 URI URIs converted to Strings are simply Unicode representations of 318 the URI. 320 2.1.6. UUID (Universally Unique ID) 322 UUIDs represent a universally unique identifier. Data of type UUID 323 is a 128 bit identifier with a structure defined in RFC 4122 324 [RFC4122]. The default UUID value is the null UUID, (00000000-0000- 325 0000-0000-000000000000). 327 Conversions: 329 String A valid 8-4-4-4-12 string representation of a UUID is 330 converted to the UUID it represents. All other values are 331 converted to the null UUID (00000000-0000-0000-0000- 332 000000000000). 334 2.1.7. Date 336 Dates represent a moment in time. Data of type Date may have the 337 value of any time in the from January 1, 1970 though at least January 338 1, 2038, to at least second accuracy. The default date is defined as 339 the beginning of the Unix(tm) epoch, midnight, January 1, 1970 in the 340 UTC time zone. 342 Conversions: 344 String See Section 2.4. 346 2.1.8. URI (Uniform Resource Identifier) 348 Data of type URI has the value of a Uniform Resource Identifier as 349 defined in RFC 3986 [RFC3986]. The default URI is an empty URI 351 Conversions: 353 String The characters of the String data are interpreted as a URI, 354 if legal. Other Strings results in the default URI. 356 2.1.9. Binary 358 Data of type Binary contains a sequence of zero or more octets. The 359 default Binary is a sequence of zero octets. 361 There are no defined conversions for Binary. 363 2.2. Composite Types 365 LLSD values can be composed of other LLSD values in two ways: Arrays 366 or Maps. In either case, the values with the composite can be any 367 heterogeneous mix of other LLSD types, both simple and composite. 369 2.2.1. Array 371 An Array is an ordered collection of zero or more values. The values 372 are considered consecutive, with no gaps. The value undef (of type 373 Undefined) may be used to indicate, within an Array, an intentionally 374 left out value. 376 Arrays are considered to have a definite length, including any 377 leading or trailing undef values in the sequence. This length can be 378 viewed by an application. Accessing beyond the end of an array acts 379 as if the value undef were stored at the accessed location. 380 Nonetheless, systems that transmit or store Arrays SHOULD NOT add or 381 remove undef values at the end of an Array value, so as to make a 382 best effort to retain the definite length as originally created. 384 2.2.2. Map 386 A Map is an unordered collection of associations between keys and 387 values. Within a given Map value, each key must be unique, each with 388 one value. Keys are String values. The associated values can be of 389 any LLSD type. 391 Maps are considered to have a definite set of keys, including keys 392 whose associated value is undef. The number of such keys, and set of 393 keys can be accessed by an application. Accessing a value for a key 394 that is not in a Map value's key set acts as if the value under were 395 stored at that key. Nonetheless, systems that transmit or store Maps 396 SHOULD NOT add or remove keys associated with undef to a Map value, 397 so as to make a best effort to retain the key set as originally 398 created. 400 Note on key equality: Two keys are considered equal if they contain 401 the same number and sequence of Unicode codepoints. Since keys are 402 String values, and String values may be normalized on transport or 403 storage, it follows that only String values that are already 404 normalized as allowed by the String type are reliable as Map keys. 405 Since the Maps are intended to be primarily used with keys set forth 406 in protocol descriptions, this not a particular problem. However, if 407 arbitrary user supplied data is to be used as key values in some 408 application, then the possibility of normalization and perhaps key 409 collision during transport must be considered. 411 2.3. Converting Between Real and String Types 413 Real values are represented using the ABNF provided in Appendix A 415 2.4. Converting Between Date and String Types 417 The textual representation of Date values is based on ISO 8601 418 [ISO8601], and further specified in RFC 3339 [RFC3339]. When Date 419 values are converted to or from String values, the character sequence 420 of the string must conform to the following production based on the 421 ABNF in RFC 3339 [RFC3339]: 422 full-date "T" partial-time "Z" 423 When converting from String values, if the sequence of characters 424 does not exactly match this production, then the result is the 425 default Date value. 427 3. The LLIDL Interface Description Language 429 3.1. Interfaces and Resources 431 A LLIDL "Interface" is comprised conceptually of collection of zero 432 or more related resources and named type definitions. The LLIDL 433 grammar defines an "Interface Definition" as being zero or more 434 comments, named type definitions or resource definitions. 436 A LLIDL "Resource" represents information or state maintained by a 437 remote system, accessed via HTTP(S). A "Resource Definition" is the 438 grammatical construction used to represent a resource. Resources are 439 partitioned into "method access classes" based on the HTTP verbs used 440 to access them. Method access classes include: "GET", "GET/PUT", 441 "GET/PUT/DELETE" and "POST". Method access classes are notated in 442 the LLIDL grammar using "Method Access Delimeters": "<<" for GET, 443 "<>" for GET/PUT, "" for GET/PUT/DELETE and POST is notated with 444 the pair of strings "->" and "<-". 446 Resource definitions also include a message body defining the 447 structure of requests and responses. GET, GET/PUT and GET/PUT/DELETE 448 resources define a single message body following the method access 449 delimiter. POST resources define two message bodies. The first 450 follows the "->" delimiter and represents the request. The second 451 follows the "<-" delimiter and represents the response. 453 A single simple type definition or "flat" map may be defined in 454 conjunction with the resource that describes the contents of 455 arguments to be placed in the query string of the request. A flat 456 map is a map containing only simple types (i.e. - it does not contain 457 arrays or maps.) 459 A resource definition has the format: 461 '%%' [ '??' ] 462 [ <- ] 464 The resource-name identifies the resource (not the URL at which it is 465 located.) Resource-names are strings that may contain alphabetic 466 characters, numbers, the slash character ('/') and the underbar 467 character ('_'). 469 3.2. Simple Types 471 LLIDL uses the nine simple types from LLSD to define the type 472 behavior of scalar elements in a resource. These types are 473 undefined, boolean, integer, real, string, UUID, URI, date and 474 binary. They are declared in LLIDL with different identifiers that 475 are (respectively): undef, bool, int, real, string, uuid, uri, date 476 and binary. Note that the undefined, boolean and integer types are 477 declared using a more compact textual description of the type. 479 3.3. Composite Types 481 Composite Types are resource elements that contain more than one 482 value. LLIDL uses the two composite types from LLSD: array and map. 484 3.3.1. Arrays 486 Arrays represent a sequence of simple types. Each element in an 487 array is accessed by an ordinal value. An array declaration begins 488 with the open bracket character ('[') and ends with the close bracket 489 character (']'). Within the definition of an array, comma delimited 490 type declarations describing the type of each element are given. 492 The format for an array declaration is: 494 '[' [ ',' ] ... ']' 496 The following example declares a five element array whose elements' 497 types are three integers, a string and a URI: 499 [ int , int , int , string , uri ] 501 LLIDL arrays may also be of indeterminate length. The ellipsis 502 trigraph ("...") appended to the end of a sequence of types in an 503 array declaration indicates the previously defined sequence of types 504 is repeated indefinitely. 506 The following examples describe (first) an arbitrary lengthed array 507 comprising of strings and (second) an arbitrary lengthed array 508 comprising of three real values followed by a string: 510 [ string , ... ] 512 [ real , real , real , string , ... ] 514 Note that the ellipsis trigraph indicates that the entire sequence is 515 repeated, not only the last element. 517 It is acceptable for an array to contain composite types like arrays 518 or maps. The following example describes an array whose elements are 519 an array of three real values and a string: 521 [ [ real , real , real ] , string, ... ] 523 3.3.2. Maps 525 Maps are collections of simple types whose elements are accessed via 526 alphanumeric strings. Maps declarations begin with the open brace 527 character ('{') and end with the close brace character ('}'). Within 528 the map declaration are a sequence of comma delimited map entries. 529 Map entries are comprised of a map entry name and a map entry type, 530 separated by a colon character (':'). Map entry names are 531 alphanumeric strings intended to be indicative of their function in 532 the resource definition. 534 The format of a map definition is: 536 '{' ':' 537 [ ',' ':' ] ... '}' 539 The following example describes a map with three elements named: 540 name, position and current_balance. The name entry is declared as a 541 string, the position entry is declared as an array with a string and 542 three real values, and the current_balance entry is declared as an 543 integer. 545 { 546 name : string, 547 position : [ string , real , real , real ], 548 current_balance : int 549 } 551 As implied by the previous example, it is perfectly acceptable for a 552 map to contain entries whose types are maps and arrays. 554 It is also possible to define a map in which map entry names that are 555 explicitly unknown at the time a resource is defined. For example, a 556 service may wish to produce or consume a map whose keys come from 557 user data such as stock ticker symbols, avatar names or the names of 558 regions in a virtual world. It is impractical to attempt to define 559 the complete set of possibilities in these cases, so LLIDL allows the 560 resource developer to specify that map names may come from data known 561 only at the time the resource is accessed. 563 The dollar character ('$') is used to specify a map whose entries' 564 names are determined after the resource is defined and deployed. A 565 map with "deferred entry names" is one in which this situation 566 occurs. Such maps are defined with a single entry whose name is the 567 dollar character and a single type. 569 The following example shows a map with "deferred entry names" whose 570 map entry types are all URIs. 572 { $ : uri } 574 At most one deferred entry name specifier (i.e. - one dollar sign) is 575 allowed in a map. A map defined with a deferred entry name specifier 576 may contain no other defined entries. 578 Deferred entry names do not signify that a later specification will 579 complete the definition of the resource, but that the map's entries' 580 names cannot be determined before the resource is accessed. 582 3.4. Named Types 584 LLIDL defines a named type feature. This feature allows a resource 585 developer to define a single alphanumeric symbol that represents a 586 complete type definition. The ampersand ('&') character is used in 587 both the definition and reference of a named type. To define a named 588 type, the following format is used: 590 '&' '=' 592 The named type symbol must be a valid alphanumeric symbol consisting 593 of upper and lower case letters, numbers, the slash character ('/') 594 or the underbar ('_'). The named type value must be a valid type 595 definition. 597 The following examples are all valid named type definitions: 599 &example = string 601 &info = { name : string, id : uuid } 603 &position = [ real, real, real ] 605 Named types are referenced using only the ampersand and a symbol. 606 The following example describes two resources whose response bodies 607 are defined using a named type: 609 &error = { errno : int, desc : string, more : uri } 611 %% session/search -> string <- &error 613 %% session/continue -> uuid <- &error 615 3.5. Variant Type Definitions 617 It may be advantageous for a resource to accept more than one form. 618 In this case, a variant type definition may be used. Variant type 619 definitions are defined using the named type feature to define a 620 named type using the same named type symbol for multiple named type 621 definitions. 623 For example, the following resource defines a response with two 624 forms. The first describes a success condition while the second an 625 error. 627 &request = { 628 name : string, 629 secret : binary 630 } 632 &response = { 633 success : true, 634 session_id : uuid 635 } 637 &response = { 638 success : false, 639 error : int, 640 next : uri 641 } 643 %% session/establish -> &request <- &response 645 In this example, the first named type (whose named type symbol is 646 'request') is a simple named type. It is later used in a resource 647 definition to represent the contents of a request to the resource. 648 The second and third named types define a variant. That is, the 649 named type symbol is used more than once. The 'response' variant 650 defined in this example indicates that the response from the resource 651 access will be one of the two 'response' forms. 653 A "selector" may be used to help determine which variant should be 654 used. A selector is a literal value included in a map entry that 655 appears in each variant. In the example above, the map entry named 656 'success' has two literal values in the two variants in which it is 657 defined. It is possible to have multiple selectors in a map variant, 658 and the same literal value may be reused. 660 4. Serialization 662 When used as part of a protocol, LLSD is serialized into a common 663 form. Three serialization schemes are currently defined: XML, JSON 664 and Binary. 666 4.1. XML Serialization 668 XML serialization of LLSD data is in common use in protocols 669 implementing virtual worlds. When used to communicate protocol data 670 with a transport that requires the use of a Type, the type 671 'application/llsd+xml' is used. 673 When serializing an instance of LLSD structured data into an XML 674 document, the DTD given in Appendix B is used. This DTD defines 675 elements for each of the defined LLSD types. Immediately subordinate 676 to the root LLSD element, XML documents representing LLSD serialized 677 data include either a single instance of an simple type (Undefined, 678 Boolean, Integer, Real, UUID, String, Date, URI or Binary) or a 679 single composite type (Array or Map). 681 When encoding binary data using RFC 4648 [RFC4648], characters 682 outside the base alphabet are explicitly allowable and should be 683 ignored. 685 4.1.1. Serializing Simple Types 687 Most simple types are serialized by placing the string representation 688 of the data between beginning and ending tags associated with the 689 value's type. This is true for undefined, boolean, integer, real, 690 UUID, string, date and URI typed values. Values of type binary are 691 serialized by placing the BASE64 encoding (defined in RFC 4648 692 [RFC4648] ) of the binary data within beginning and ending 'binary' 693 tags. It is expected that future versions of this specification may 694 allow encodings other than BASE64, so the mandatory attribute 695 'encoding' is used to identify the method used to encode the binary 696 data. 698 The following example shows an XML document representing the 699 serialization of the integer -559038737. 701 702 703 -559038737 704 706 While this example shows the serialization of a binary array of 707 octets containing the values 222, 173, 190 and 239. 709 710 711 3q2+7w== 712 714 4.1.2. Serializing Composite Types 716 Composite types in the XML serialization scheme are represented with 717 'array' and 'map' elements. Both of these elements may contain 718 elements enclosing simple types or other composite types. Array 719 elements, which represent a collection of values indexed by position, 720 contain a simple list of typed values. Map elements represent a 721 collection of values indexed by a string identifier. They contain a 722 list of key-value pairs where the 'key' element describes the 723 indexing identifier while the value (which follows the 'key' element) 724 is its XML representation. 726 Note that elements of an array may be of differing types. Also note 727 that composite types may contain other composite types; it is not an 728 error for an array or map to contain another array, map or simple 729 type. 731 4.1.3. Example of XML LLSD Serialization 733 This example shows the XML serialization of an array which contains 734 an integer, a UUID and a map. 736 737 738 739 42 740 6bad258e-06f0-4a87-a659-493117c9c162 741 742 hot 743 cold 744 higgs_boson_rest_mass 745 746 info_page 747 https://example.org/r/6bad258e-06f0-4a87-a659-493117c9c162 748 status_report_due_by 749 2008-10-13T19:00.00Z 750 751 752 754 4.2. JSON Serialization 756 LLSD may also be serialized using the JSON [ECMA262r5] subset of the 757 JavaScript programming language. When serializing LLSD data using 758 JSON, the 'application/llsd+json' media type is used. The grammar of 759 LLSD objects serialized using the JSON serialization MUST conform to 760 the JSONText production. 762 The following table lists type conversions between LLSD and JSON: 764 Undefined LLSD 'Undefined' values are represented by the JSON non- 765 terminal 'JSONNullLiteral'. 767 Boolean LLSD 'Boolean' values are represented by the JSON non- 768 terminal 'JSONBooleanLiteral'. 770 Integer LLSD 'Integer' values are represented by the JSON non- 771 terminal 'JSONNumberLiteral'. 773 Real LLSD 'Real' values are represented by the JSON non-terminal 774 'JSONNumberLiteral'. 776 String LLSD 'String' values are represented by the JSON 'JSONString' 777 non-terminal. Note that this specification inherits JSON's 778 behavior of requiring control characters, reverse solidus and 779 quotation mark characters to be escaped. 781 UUID LLSD 'UUID' values are represented by a JSON string, and are 782 rendered in the common 8-4-4-4-12 format defined by the 'UUID' 783 non-terminal in RFC 4122 [RFC4122]. 785 Date LLSD 'Date' values are represented by the JSON 'string' non- 786 terminal, the contents of which is a valid ISO 8601 value with 787 years, months, days, hours, seconds and time zone indicator. 789 URI LLSD 'URI' values are represented by the JSON 'string' non- 790 terminal, the contents of which is a valid URI as defined by RFC 791 3986 [RFC3986]. 793 Binary LLSD 'Binary' values are represented as a JSON 'JSONArray'. 794 That is, they follow the ECMA-262 [ECMA262r5] 'JSONArray' non- 795 terminal whose members are integer numbers representing each 796 octet of the binary array. 798 Array LLSD 'Array' values are represented by the JSON 'JSONArray' 799 non-terminal. 801 Map LLSD 'Map' values are represented by the JSON 'JSONObject' non- 802 terminal. Each key-value pair of the map is represented by the 803 JSON 'JSONMember' non-terminal where the LLSD map key is the 804 'JSONString' prior to the name separator terminal (':') and the 805 LLSD map value is the 'JSONValue' after the name separator. 807 LLSD defines additional types over those defined by JSON. The LLSD 808 types UUID, Date and URI are serialized as JSON strings whose 809 contents are generated using the to String conversion defined 810 in Abstract Type System section above. 812 4.2.1. Examples of JSON LLSD Serialization 814 Example 1. The following example shows the JSON encoding of the 815 integer 42. 817 42 819 Example 2. The following example shows the JSON encoding of the 820 example given in the section above on XML serialization 821 (Section 4.1.2). 823 [ 824 42, 825 "6bad258e-06f0-4a87-a659-493117c9c162", 826 { 827 "hot": "cold", 828 "higgs_boson_rest_mass": null, 829 "info_page": 830 "https://example.org/r/6bad258e-06f0-4a87-a659-493117c9c162", 831 "status_report_due_by": "2008-10-13T19:00.00Z" 832 } 833 ] 835 4.3. Binary Serialization 837 The LLSD Binary Serialization is an encoding syntax appropriate for 838 situations where high message entropy is required or limiting 839 processing power for parsing messages is available. 841 Encoding LLSD structured data using the binary serialization scheme 842 involves generating tag, (optional) size values, and serialization of 843 simple values. Composite types are serialized by iterating across 844 all members of the collection, serializing each simple or composite 845 member in turn, and adding a closing tag. For each element in an 846 LLSD structured data object, the following process is used to 847 generate a binary output stream of serialized data: 849 o A one octet type tag is emitted to the output stream. See the 850 table below for tag octets. 852 o If the size of the element being serialized is variable (as it 853 will be for strings, URIs, arrays and maps), the size or length of 854 the element is output to the stream as a network-order 32 bit 855 value. Elements of types with fixed lengths such as undefined 856 values, booleans, integers, reals, UUIDs and dates will not 857 include size information in the output stream. 859 o Finally, the binary representation of the element is appended to 860 the output stream. 862 Undefined Undefined values are serialized with a single exclamation 863 point character ('!'). Undefined values append neither size 864 information or data to the output stream. 866 Boolean True values are serialized with a single '1' character. 867 False values are serialized with a single '0' character. 868 Booleans append neither size information or data to the output 869 stream. 871 Integer Integer values are serialized by emitting the 'i' character 872 to the output stream followed by the four octets representing the 873 integer's 32 bits in network order. 875 Real Real values are serialized by emitting the 'r' character to the 876 output stream followed by the eight octets representing the real 877 value's 64 bits in network order. 879 String String values are serialized by emitting the 's' character to 880 the output stream followed by the string's length in octets 881 represented as a network-order 32 bit integer, followed by the 882 string's UTF-8 encoding. 884 UUID UUID values are serialized by emitting the 'u' character to the 885 output stream followed by the sixteen octets representing the 886 UUID's 128 bits, with the most significant byte coming first. 888 Date Date values are serialized by emitting the 'd' character to the 889 output stream followed by the number of seconds since the start 890 of the epoch, represented as a 64-bit real value. 892 URI URI values are serialized by emitting the 'l' character to the 893 output stream followed by the URI's length in octets represented 894 as a network-order 32 bit integer, followed by the binary 895 representation of the URI. 897 Binary Binary values are serialized by emitting the 'b' character to 898 the output stream followed by the binary array's length in octets 899 represented as a network-order 32 bit integer, followed by the 900 octets of the binary array. 902 Array Arrays are serialized by emitting the left square bracket 903 ('[') character, followed by the count of objects in the array 904 represented as a network-order 32 bit integer, followed by each 905 array element in order. Note that compliant implementations MUST 906 preserve the order of array elements. Following the elements in 907 the array, a single octet closing tag is appended to the 908 enclosing. The closing tag for arrays is a single right square 909 bracket (']'). 911 Map Maps are serialized by emitting the left curly brace ('{') 912 character, followed by the count of objects in the map 913 represented as a network-order 32 bit integer, followed by each 914 key-value element. Map keys are represented as strings except 915 that they use the character 'k' instead of the character 's' as a 916 tag. Note that preserving the order of maps is not REQUIRED. 917 Following the elements in the map, a single octet closing tag is 918 appended to the enclosing. The closing tag for arrays is a 919 single right curly brace ('}'). 921 4.3.1. Example of BINARY LLSD Serialization 922 The LLSD object given as an example in the section above on XML 923 serialization (Section 4.1.2) would look as follows would it have 924 been serialized using the binary scheme. The following example 925 encodes octets as hexadecimal values. 927 Offset Hex Data Char Data 928 -------- ------------------------- ----------- 929 00000000 5B '[' 930 00000001 00 00 00 03 '....' 931 00000005 69 'i' 932 00000006 00 00 00 2A '...*' 933 0000000A 75 'u' 934 0000000B 6B AD 25 8E 06 F0 4A 87 'k.%...J.' 935 00000013 A6 59 49 31 17 C9 C1 62 '.YI1...b' 936 0000001B 7B '{' 937 0000001C 00 00 00 04 '....' 938 00000020 6B 'k' 939 00000021 00 00 00 03 '....' 940 00000025 68 6F 74 'hot' 941 00000028 73 's' 942 00000029 00 00 00 04 '....' 943 0000002D 63 6F 6C 64 'cold' 944 00000031 6B 'k' 945 00000032 00 00 00 13 '....' 946 00000036 68 69 67 67 73 5F 62 6F 'higgs_bo' 947 0000003E 73 6F 6E 5F 72 65 73 74 'son_rest' 948 00000046 5f 6d 61 73 73 '_mass' 949 0000004B 21 '!' 950 0000004C 68 'k' 951 0000004D 00 00 00 09 '....' 952 00000051 69 6E 66 6F 5F 70 61 67 'info_pag' 953 00000059 65 'e' 954 0000005A 6C 'l' 955 0000005B 00 00 00 3A '...:' 956 0000005F 68 74 74 70 73 3A 2f 2F 'https://' 957 00000067 65 78 61 6D 70 6C 65 2E 'example.' 958 0000006F 6F 72 67 2F 72 2F 36 62 'org/r/6b' 959 00000077 61 64 32 35 38 65 2D 30 'ad258e-0' 960 0000007F 36 66 30 2D 34 61 38 37 '6f0-4a87' 961 00000087 2D 61 36 35 39 2D 34 39 '-a659-49' 962 0000008F 33 31 31 37 63 39 63 31 '3117c9c1' 963 00000097 36 32 '62' 964 00000099 68 'k' 965 0000009A 00 00 00 14 '....' 966 0000009E 73 74 61 74 75 73 5F 72 'status_r' 967 000000A7 65 70 6F 72 74 5F 64 75 'eport_du' 968 000000AF 65 5F 62 79 'e_by' 969 000000B3 00 00 00 08 '....' 970 000000B7 64 'd' 971 000000B8 41 D2 3C E6 AC 00 00 00 'A.<.....' 973 5. IANA Considerations 975 In accordance with [RFC5226], this document registers the following 976 mime types: 978 application/llidl 980 application/llsd+xml 982 application/llsd+json 984 application/llsd+binary 986 See the MIME Type Registrations section (Section 6) below for 987 detailed information on MIME Type registrations. 989 6. MIME Type Registrations 991 This section provides media-type registration applications (as per 992 RFC 4288 [RFC4288].) 994 6.1. MIME Type Registration for application/llidl 996 To: ietf-types@iana.org 998 Subject: Registration of media type application/llidl 1000 Type name: application 1002 Subtype name: llidl 1004 Required Parameters: none 1006 Optional Parameters: none 1008 Encoding Considerations: LLIDL may be used with any character set 1009 that encodes character points identical to ASCII for the first 1010 127 characters. Compliant systems SHOULD use UTF-8 and if no 1011 character set is indicated, UTF-8 MUST be assumed. 1013 Security Considerations: LLIDL interface descriptions contain 1014 "plain" text and generally poses no immediate risk to system 1015 security of either the sender or the receiver. Still, it is 1016 possible for a malicious adversary to include arbitrary binary 1017 data in an attempt to exploit specific vulnerabilities (if they 1018 exist.) It is the obligation of the receiver to ensure such 1019 vulnerabilities are mitigated in a timely fashion 1020 In the unlikely event that sensitive information is to be 1021 expressed as an LLIDL interface, it is the responsibility of the 1022 transport, network or link layers to ensure the confidentiality, 1023 message integrity and origin integrity of the message. 1025 Interoperability Considerations: While it is possible for compliant 1026 implementations to specify the use of character sets other than 1027 UTF-8, such systems MUST accept UTF-8 input and SHOULD generate 1028 UTF-8 output. 1030 Published specification: The grammar of LLIDL is defined in the 1031 internet draft draft-ietf-vwrap-type-system-00 1032 [I-D.ietf-vwrap-type-system]. 1034 Applications that use this media type: Virtual world, tele-presence 1035 and content management systems related to "virtual reality" 1036 systems. 1038 Additional Information: 1040 Magic Number(s): none 1042 File Extension: llidl 1044 Macintosh File Type Code(s): TEXT 1046 Person & email address to contact for further information: Meadhbh 1047 Hamrick 1049 Intended Usage: COMMON 1051 Author: IESG 1053 Change Controller: IESG 1055 6.2. MIME Type Registration for application/llsd+xml 1057 To: ietf-types@iana.org 1059 Subject: Registration of media type application/llsd+xml 1061 Type name: application 1063 Subtype name: llsd+xml 1064 Required Parameters: none 1066 Optional Parameters: none 1068 Encoding Considerations: The Extensible Markup Language (XML) 1069 specification allows for the use of multiple character sets. The 1070 character set used to encode the body of the message is defined 1071 as part of the XML header. If no character set is indicated in 1072 the XML header, compliant systems MUST assume UTF-8. 1074 Security Considerations: LLSD XML serialized data contains "plain" 1075 text and generally poses no immediate risk to system security of 1076 either the sender or the receiver. Still, it is possible for a 1077 malicious adversary to include arbitrary binary data in an 1078 attempt to exploit specific vulnerabilities (if they exist.) It 1079 is the obligation of the receiver of LLSD XML serialized messages 1080 to ensure such vulnerabilities are mitigated in a timely fashion. 1082 If sensitive information is to be encoded into a LLSD XML 1083 serialized message, it is the responsibility of the transport, 1084 network or link layers to ensure the confidentiality, message 1085 integrity and origin integrity of the message. 1087 Interoperability Considerations: While it is possible for compliant 1088 implementations to specify the use of character sets other than 1089 UTF-8, such systems MUST accept UTF-8 input and SHOULD generate 1090 UTF-8 output. 1092 Published specification: The LLSD XML Serialization is defined in 1093 the internet draft draft-ietf-vwrap-type-system-00 1094 [I-D.ietf-vwrap-type-system]. 1096 Applications that use this media type: Virtual world, tele-presence 1097 and content management systems related to "virtual reality" 1098 systems. 1100 Additional Information: 1102 Magic Number(s): none 1104 File Extension: lsdx 1106 Macintosh File Type Code(s): TEXT 1108 Person & email address to contact for further information: Meadhbh 1109 Hamrick 1111 Intended Usage: COMMON 1113 Author: IESG 1115 Change Controller: IESG 1117 6.3. MIME Type Registration for application/llsd+json 1119 To: ietf-types@iana.org 1121 Subject: Registration of media type application/llsd+json 1123 Type name: application 1125 Subtype name: llsd+json 1127 Required Parameters: none 1129 Optional Parameters: none 1131 Encoding Considerations: This specification requires that LLSD 1132 objects encoded using the JSON serialization scheme encode their 1133 data using Unicode. It is assumed that the transport will carry 1134 meta-data describing the character encoding used (UTF-8, UTF-16, 1135 UTF-32, etc.) The UTF-8 character encoding is assumed if a 1136 character encoding is not specified. 1138 Security Considerations: The contents of messages identified with 1139 this media type are expected to be passed into ECMAScript's 1140 'parse()' function. RFC 4627 [RFC4627] provides a regular 1141 expression to ensure that only "safe" characters (i.e. - 1142 characters used to describe JSON tokens) are included outside 1143 string literal definitions. Users of the application/llsd+json 1144 media type are strongly encouraged to use this (or similar) tests 1145 to ensure message safety. 1147 If sensitive information is to be encoded into a LLSD JSON 1148 serialized message, it is the responsibility of the transport, 1149 network or link layers to ensure the confidentiality, message 1150 integrity and origin integrity of the message. 1152 Interoperability Considerations: none 1153 Published specification: This specification. 1155 Applications that use this media type: Virtual world, tele-presence 1156 and content management systems related to "virtual reality" 1157 systems. 1159 Additional Information: 1161 Magic Number(s): none 1163 File Extension: lsdj 1165 Macintosh File Type Code(s): TEXT 1167 Person & email address to contact for further information: Meadhbh 1168 Hamrick 1170 Intended Usage: COMMON 1172 Author: IESG 1174 Change Controller: IESG 1176 6.4. MIME Type Registration for application/llsd+binary 1178 To: ietf-types@iana.org 1180 Subject: Registration of media type application/llsd+binary 1182 Type name: application 1184 Subtype name: llsd+binary 1186 Required Parameters: none 1188 Optional Parameters: none 1190 Encoding Considerations: LLSD Binary Serialization REQUIRES the use 1191 of binary content-transfer-encoding Section 5 of RFC 2045 [RFC2045] 1192 describes the binary Content-Transfer-Encoding header field. 1193 This specification REQUIRES the use of this header to alert 1194 intermediary systems that information being included in the 1195 message should be interpreted as binary data with no end-of-line 1196 semantics which could be considerably longer than allowed in an 1197 RFC 821 transport. 1199 Security Considerations: This serialization format defines the use 1200 of tagged binary fields with embedded length information. In the 1201 past, similar binary encoding systems have fallen prey to 1202 exploits when parsing implementations fail to check for 1203 nonsensical lengths. Implementers are therefore strongly 1204 encouraged to consider all failure modes of such a system. 1206 If sensitive information is to be encoded into a LLSD JSON 1207 serialized message, it is the responsibility of the transport, 1208 network or link layers to ensure the confidentiality, message 1209 integrity and origin integrity of the message. 1211 Interoperability Considerations: none 1213 Published specification: The LLSD binary serialization is defined in 1214 the internet draft draft-hamrick-llsd-01 1215 [I-D.ietf-vwrap-type-system]. 1217 Applications that use this media type: Virtual world, tele-presence 1218 and content management systems related to "virtual reality" 1219 systems. 1221 Additional Information: 1223 Magic Number(s): none 1225 File Extension: lsdb 1227 Macintosh File Type Code(s): LSDB 1229 Person & email address to contact for further information: Meadhbh 1230 Hamrick 1232 Intended Usage: COMMON 1234 Author: IESG 1236 Change Controller: IESG 1238 7. Security Considerations 1240 Security considerations for this specification are, fortunately, 1241 either simple or beyond the scope of this document. RFC 3552 1242 [RFC3552] describes several aspects to use when evaluating the 1243 security of a specification or implementation. We believe most 1244 common security concerns users of this specification will encounter 1245 are more appropriately considered as transport, network or link layer 1246 issues. Or, as higher level "application security" issues. 1248 This document specifies the content, media type identifiers and 1249 content encoding requirements for LLSD. It does not specify 1250 mechanisms to transmit LLSD messages between network peers. We 1251 believe that many communication security considerations such as 1252 confidentiality, data integrity and peer entity authentication are 1253 more appropriately the domain of message, transport, network or link 1254 layer protocols. Users of this protocol should seriously consider 1255 the use Secure MIME, Transport Layer Security (TLS), IPSec or related 1256 technologies. 1258 8. References 1260 8.1. Normative References 1262 [ECMA262r5] 1263 ECMA International, "Standard ECMA-262, 5th Edition : 1264 ECMAScript Language Specification", December 2009, . 1268 [I-D.ietf-vwrap-type-system] 1269 Brashears, A., Hamrick, M., and M. Lentczner, "VWRAP : 1270 Abstract Type System for the Transmission of Dynamic 1271 Structured Data", July 2010. 1273 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1274 Extensions (MIME) Part One: Format of Internet Message 1275 Bodies", RFC 2045, November 1996. 1277 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1278 Requirement Levels", BCP 14, RFC 2119, March 1997. 1280 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1281 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1282 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1284 [RFC2817] Khare, R. and S. Lawrence, "Upgrading to TLS Within 1285 HTTP/1.1", RFC 2817, May 2000. 1287 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 1288 Internet: Timestamps", RFC 3339, July 2002. 1290 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1291 Resource Identifier (URI): Generic Syntax", STD 66, 1292 RFC 3986, January 2005. 1294 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1295 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1296 July 2005. 1298 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 1299 Registration Procedures", BCP 13, RFC 4288, December 2005. 1301 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1302 Encodings", RFC 4648, October 2006. 1304 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1305 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1307 [TR15] Davis, M. and M. Durst, "Unicode Standard Annex #15 : 1308 UNICODE NORMALIZATION FORMS", 2008, 1309 . 1311 [XML2006] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and 1312 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth 1313 Edition)", 2006. 1315 8.2. Informative References 1317 [Fielding2000] 1318 University of California, Irvine, "Architectural Styles 1319 and the Design of Network-based Software Architectures", 1320 2000. 1322 [ISO8601] "ISO 8601 - Date and Time Formats". 1324 [Kaye2003] 1325 The Conversations Network, "Loosely Coupled : The Missing 1326 Pieces of Web Services", 2003. 1328 [RFC3552] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 1329 Text on Security Considerations", BCP 72, RFC 3552, 1330 July 2003. 1332 [RFC4627] Crockford, D., "The application/json Media Type for 1333 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1335 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1336 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1337 May 2008. 1339 Appendix A. ABNF of Real Values 1341 The following is the Augmented Backus-Naur Form (ABNF) of valid Real 1342 values for the purposes of converting strings into real values. ABNF 1343 is described in RFC 5234 [RFC5234]. 1344 real = zero 1345 real =/ negative-infinity 1346 real =/ negative-zero 1347 real =/ positive-zero 1348 real =/ positive-infinity 1349 real =/ signaling-nan 1350 real =/ quiet-nan 1351 real =/ realnumber 1353 negative-infinity = %x2D.49.6E.66.69,6E.69.74.79 ; "-Infinity" 1354 negative-zero = %x2D.5A.65.72.6F ; "-Zero" 1355 zero = %x30.2E.30 ; "0.0" 1356 positive-zero = %x2B.5A.65.72.6F ; "+Zero" 1357 positive-infinity = %x2B.49.6E.66.69,6E.69.74.79 ; "+Infinity" 1358 signaling-nan = %4E.61.4E.53 ; "NaNS" 1359 quiet-nan = %4E.61.4E.51 ; "NaNQ" 1361 realnumber = mantissa exponent 1363 mantissa = ( positive-number [ "." *decimal-digit ]) 1364 mantissa =/ ( "0." *("0") positive-number ) 1366 exponent = "E" ( "0" / ( [ "-" ] positive-number ) ) 1368 positive-number = non-zero-digit *decimal-digit 1370 decimal-digit = %x30-39 1371 non-zero-digit = %x31-39 1373 Appendix B. XML Serialization DTD 1375 The following Document Type Definition (DTD) describes the format of 1376 LLSD XML Serialization. DTDs are described in the Extensible Markup 1377 Language (XML) 1.0 (Fourth Edition) [XML2006] specification. 1379 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1392 1395 1397 1398 1400 Appendix C. ABNF of LLIDL 1402 The following is the Augmented Backus-Naur Form (ABNF) of the LLIDL 1403 Interface Description Language. ABNF is described in RFC 5234 1404 [RFC5234]. 1406 llidl = *( s / resource-def / variant-def ) 1408 resource-def = res-name s res-transaction 1409 res-name = "%%" s name 1410 res-transaction = res-get / res-getput / res-getputdel / res-post 1411 res-get = "<<" s value 1412 res-getput = "<>" s value 1413 res-getputdel = "" s value 1414 res-post = res-request s res-response 1415 res-request = "->" s value 1416 res-response = "<-" s value 1418 variant-def = "&" name s "=" s value 1419 value = type / array / map / selector / variant 1421 type = %x75.6E.64.65.66 ; "undef" 1422 type =/ %x73.74.72.69.6E.67 ; "string" 1423 type =/ %x62.6F.6F.6C ; "bool" 1424 type =/ %x69.6E.74 ; "int" 1425 type =/ %x72.65.61.6C ; "real" 1426 type =/ %x64.61.74.65 ; "date" 1427 type =/ %x75.72.69 ; "uri" 1428 type =/ %x75.75.69.64 ; "uuid" 1429 type =/ %x62.69.6E.61.72.79 ; "binary" 1431 array = "[" s value-list s "]" 1432 array =/ "[" s value-list s "..." s "]" 1434 map = "{" s member-list s "}" 1435 map =/ "{" s "$" s ":" s value s "}" 1437 value-list = value [ s "," [ s value-list ] ] 1439 member-list = member [ s "," [ s member-list ] ] 1440 member = name s ":" s value 1442 selector = quote name quote 1443 selector =/ %x74.72.75.65 ; "true" 1444 selector =/ %x66.61.6C.73.65 ; "false" 1445 selector =/ 1*digit 1447 variant = "&" name 1449 s = *( tab / newline / sp / comment ) 1450 comment = ";" *char newline 1451 newline = lf / cr / (cr lf) 1453 tab = %x0009 1454 lf = %x000A 1455 cr = %x000D 1456 sp = %x0020 1457 quote = %x0022 1458 digit = %x0030-0039 1459 char = %x09 / %x20-D7FF / %xE000-FFFD / %x10000-10FFFF 1461 name = name_start *name_continue 1462 name_start = id_start / "_" 1463 name_continue = id_continue / "_" / "/" 1464 id_start = %x0041-005A / %x0061-007A ; ALPHA 1465 id_continue = id_start / %x0030-0039 ; DIGIT 1467 Appendix D. Glossary 1469 Access See Resource Access. 1471 Array An array is a collection in which elements are accessed by 1472 numeric index. By default arrays are fixed length, but a 1473 trailing ellipsis in an array definition denotes an array of 1474 indeterminate length. 1476 Array Definition An array definition is a feature of the LLIDL 1477 grammar used to denote arrays of fixed or indeterminate size. An 1478 array definition is a comma delimited sequence of type 1479 definitions describing the type of each array element. 1481 Composite Type A composite type in LLIDL and LLSD is an abstract 1482 representation of an array or a map. 1484 Deferred Entry Name A map defined with a single "Deferred Entry Name 1485 Specifier" (i.e. - the dollar sign), signifies that the map 1486 entry's names will be determined at the time the resource is 1487 accessed, not when the resource is defined. 1489 Defined Type A defined type is a feature of the LLIDL grammar used 1490 to represent one of the eleven (11) predefined types. Defined 1491 types are in contrast to literals and map variants. The eleven 1492 predefined types are: undefined, boolean, integer, real, date, 1493 uuid, uri, string, binary, array and map. 1495 GET (Method Access) The GET method access, denoted in LLIDL with the 1496 double less-than digraph ("<<") indicates a given resource should 1497 be accessed via the HTTP GET verb. In LLIDL, a single message 1498 body definition comes after the double less-than digraph and 1499 indicates the composition of the message the client should expect 1500 from the server. 1502 GET/PUT (Method Access) The GET/PUT method access, denoted in LLIDL 1503 with the less-than / greater-than digraph ("<>") indicates a 1504 given resource should be accessed via either the HTTP GET or HTTP 1505 PUT verbs. In LLIDL, a single message body definition comes 1506 after the less-than / greater-than digraph and indicates the 1507 composition of the message the client should expect from the 1508 server (if the GET HTTP verb is used) or the composition of the 1509 message the server should expect from the client (if the PUT HTTP 1510 verb is used.) 1512 GET/PUT/DELETE (Method Access) The GET/PUT/DELETE method access, 1513 denoted in LLIDL with the less-than / x / greater-than trigraph 1514 ("") indicates a given resource should be accessed via either 1515 the HTTP GET, HTTP PUT or HTTP DELETE verbs. In LLIDL, a single 1516 message body definition comes after the less-than / x / greater- 1517 than trigraph and indicates the composition of the message the 1518 client should expect from the server (if the GET HTTP verb is 1519 used) or the composition of the message the server should expect 1520 from the client (if the PUT HTTP verb is used.) 1522 Interface An LLIDL Interface is a collection of zero or more 1523 resources and any variant record definitions they reference. 1525 Literal Values in LLIDL resource definitions usually represent 1526 types. A literal value may be used when an element in a message 1527 body is to be fixed to a particular value. Literals are in 1528 contrast to defined types or map variants. 1530 LLIDL LLIDL is an interface description language for describing 1531 RESTful resources accessed via HTTP or HTTPS. 1533 LLSD LLSD is an abstract type system used to describe the structure 1534 of data in LLIDL Resource Definitions. 1536 Map A map is a collection in which elements are accessed by a string 1537 key. 1539 Map Definition A map definition is a feature of the LLIDL grammar 1540 used to denote maps. Map definitions are comprised of zero or 1541 more comma delimited map entries. 1543 Map Entry A map entry is a component of a map definition and is 1544 composed of a key name and a type definition separated by a 1545 colon. 1547 Map Variant See Variant Map. 1549 Method Access A method access is a feature of the LLIDL grammar used 1550 to describe which set HTTP verbs a client should use to access a 1551 resource. Method access classes include 'GET', 'GET/PUT', 'GET/ 1552 PUT/DELETE' and 'POST'. 1554 Message Body A message body is a feature of the LLIDL grammar that 1555 describes the contents of a message flowing between a client and 1556 a server. A message body is the type definition that describes 1557 completely the structure of a message flowing between systems. 1559 Named Type A named type is a developer declared name for a type, 1560 array or map definition. 1562 POST (Method Access) The POST method access, denoted in LLIDL with 1563 the hyphen / greater-than ("->") and less-than / hyphen ("<-") 1564 digraphs, indicates a given resource should be accessed via the 1565 HTTP POST verb. In LLIDL, a message body definition comes after 1566 both digraphs. The message body definition following the first 1567 digraph indicates the composition of the message the client 1568 should POST to the resource's URL while the second message body 1569 definition describes the response the client should expect from 1570 the server. 1572 Resource A Resource is an abstract representation of information or 1573 state maintained by a remote process, potentially on a remote 1574 host. LLIDL may be used to describe the structure of a resource 1575 and resources may be accessed by sending and receiving messages 1576 serialized using one of the three serialization schemes via 1577 HTTP(S). 1579 Resource Access The act of accessing a RESTful resource. 1581 Resource Definition An LLIDL Resource Definition is a statement in 1582 the LLIDL language describing a single RESTful resource exported 1583 by a remote service. Resource definitions include a resource 1584 class, optional query parameters, a method access indicating 1585 which HTTP verbs are acceptable to the service, the structure of 1586 the resource access' request and/or the structure of the resource 1587 access' response. Resource definitions may be used along with a 1588 serialization scheme to format or parse a resource request or 1589 response. 1591 Resource Class A Resource Class is the textual identifier associated 1592 with a resource. It is used to uniquely identify a resource in 1593 an interface. 1595 Selector See Variant Selector. 1597 Selector Literal A literal used to identify which variant in a map 1598 variant should be expected is a "selector literal." 1600 Serialization Scheme A serialization scheme defines rules used to 1601 convert a data structure into an octet stream suitable for 1602 transmission across a network. Three schemes are defined in this 1603 document: XML, JSON and Binary. 1605 Simple Type In LLSD and LLIDL, a "simple type" is a defined type 1606 that is not a collection. It is one of: undefined, boolean, 1607 integer, real, date, uuid, uri, string or binary. 1609 Type Definition A type definition is a feature of the LLIDL grammar 1610 used to declare the type of a data element in a message body. It 1611 may be a literal, a defined type or a variant map. 1613 Variant Definition A map used as one of several options in a variant 1614 map. 1616 Variant Map A variant type definition in which a map is used for one 1617 of the variants. Variant maps may include a selector to assist 1618 in matching the most appropriate variant. 1620 Variant Selector A map entry whose value is set as a literal. Used 1621 to determine which variant definition of a variant map is to be 1622 used. 1624 Variant Type Definition A type definition comprised of more than one 1625 definition. Variant type definitions are defined using the named 1626 type feature of LLIDL. 1628 Appendix E. Acknowledgements 1630 The authors gratefully acknowledge the contributions of: Lora Baines, 1631 Alan Bradley, Suzy Deffeyes, Morgaine Dinova, Kevin Flynn, Valentyn 1632 Gatsuk, Walter Gibbs, John Hurliman, Dave Huseby, Charles Krinke, 1633 Jennifer Leech, David Levine, Steven Lisberger, Dan Olivares, 1634 Catherine Pfeffer, Jon Watte and Ryan Williams. 1636 Authors' Addresses 1638 Aaron Brashears 1640 Meadhbh Siobhan Hamrick 1641 P.O. Box 783 1642 Boulder Creek, CA 95006 1643 US 1645 Phone: +1 650 283 0344 1646 Email: OhMeadhbh@gmail.com 1647 Mark Lentczner