idnits 2.17.1 draft-ietf-calext-eventpub-extensions-06.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 is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. ** The abstract seems to contain references ([RFC5545]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. -- The draft header indicates that this document updates RFC5545, but the abstract doesn't seem to directly say this. It does mention RFC5545 though, so this could be OK. -- The draft header indicates that this document updates RFC5546, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC5545, updated by this document, for RFC5378 checks: 2005-10-26) (Using the creation date from RFC5546, updated by this document, for RFC5378 checks: 2005-10-21) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 5, 2018) is 2183 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) No issues found here. Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Douglass 3 Internet-Draft Spherical Cow Group 4 Updates: 5545,5546 (if approved) May 5, 2018 5 Intended status: Standards Track 6 Expires: November 6, 2018 8 Event Publishing Extensions to iCalendar 9 draft-ietf-calext-eventpub-extensions-06 11 Abstract 13 This specification introduces a number of new iCalendar properties 14 and components which are of particular use for event publishers and 15 in social networking. 17 This specification also defines a new STRUCTURED-DATA property for 18 iCalendar [RFC5545] to allow for data that is directly pertinent to 19 an event or task to be included with the calendar data. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on November 6, 2018. 38 Copyright Notice 40 Copyright (c) 2018 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 57 2. Components and properties . . . . . . . . . . . . . . . . . . 4 58 3. Typed References . . . . . . . . . . . . . . . . . . . . . . 4 59 3.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 5 60 3.1.1. Piano Concert Performance . . . . . . . . . . . . . . 5 61 3.1.2. Itineraries . . . . . . . . . . . . . . . . . . . . . 6 62 3.1.2.1. Reserving facilities . . . . . . . . . . . . . . 6 63 4. Modifications to Calendar Components . . . . . . . . . . . . 6 64 5. New Property Parameters . . . . . . . . . . . . . . . . . . . 7 65 5.1. Loctype . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 5.2. Restype . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 5.3. Order . . . . . . . . . . . . . . . . . . . . . . . . . . 8 68 5.4. Schema . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 6. Redefined Property SOURCE . . . . . . . . . . . . . . . . . . 10 70 7. New Properties . . . . . . . . . . . . . . . . . . . . . . . 11 71 7.1. Participant Type . . . . . . . . . . . . . . . . . . . . 11 72 7.2. Calendar Address . . . . . . . . . . . . . . . . . . . . 12 73 7.3. Styled-Description . . . . . . . . . . . . . . . . . . . 12 74 7.4. Structured-Location . . . . . . . . . . . . . . . . . . . 14 75 7.5. Structured-Resource . . . . . . . . . . . . . . . . . . . 16 76 7.6. Structured-Data . . . . . . . . . . . . . . . . . . . . . 17 77 8. New Components . . . . . . . . . . . . . . . . . . . . . . . 19 78 8.1. Participant . . . . . . . . . . . . . . . . . . . . . . . 20 79 8.2. Schedulable Participant . . . . . . . . . . . . . . . . . 22 80 9. Participant Types . . . . . . . . . . . . . . . . . . . . . . 22 81 10. Resource Types . . . . . . . . . . . . . . . . . . . . . . . 23 82 11. Extended examples . . . . . . . . . . . . . . . . . . . . . . 23 83 11.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . 24 84 11.2. Example 2 . . . . . . . . . . . . . . . . . . . . . . . 24 85 12. Security Considerations . . . . . . . . . . . . . . . . . . . 25 86 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 25 87 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 88 14.1. Additional iCalendar Registrations . . . . . . . . . . . 26 89 14.1.1. Property Registrations . . . . . . . . . . . . . . . 26 90 14.1.2. Parameter Registrations . . . . . . . . . . . . . . 26 91 14.1.3. Component Registrations . . . . . . . . . . . . . . 26 92 14.2. New Registration Tables . . . . . . . . . . . . . . . . 27 93 14.2.1. Participant Types Registry . . . . . . . . . . . . . 27 94 14.2.2. Resource Types Registry . . . . . . . . . . . . . . 27 95 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 96 16. Normative References . . . . . . . . . . . . . . . . . . . . 28 97 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 28 98 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 29 99 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31 101 1. Introduction 103 The currently existing iCalendar standard [RFC5545] lacks useful 104 methods for referencing additional, external information relating to 105 calendar components. Additionally there is no standard way to 106 provide rich text descriptions or meta-data associated with the 107 event. 109 Current practice is to embed this information as links in the 110 description or to add x-properties. 112 This document defines a number of properties and a component 113 referencing such external information that can provide additional 114 information about an iCalendar component. The intent is to allow 115 interchange of such information between applications or systems 116 (e.g., between clients, between client and server, and between 117 servers). Formats such as VCARD are likely to be most useful to the 118 receivers of such events as they may be used in other applications - 119 such as address books. 121 This specification defines a new PARTICIPANT component. Many people 122 or groups may participate in an event. This component provides 123 detailed information. Such participants may act as attendees to the 124 event (or derived events) or may just provide a reference - perhaps 125 for mailing lists. 127 The following properties are defined in this specification 129 STYLED-DESCRIPTION: Supports HTML descriptions. Event publishers 130 typically wish to provide more and better formatted information 131 about the event. 133 STRUCTURED-LOCATION: There may be a number of locations associated 134 with an event. This provides detailed information about the 135 location. 137 STRUCTURED-RESOURCE: Events need resources such as rooms, 138 projectors, conferencing capabilities. 140 STRUCTURED-DATA: The existing properties in iCalendar cover key 141 elements of events and tasks such as start time, end time, 142 location, summary, etc. However, different types of events often 143 have other specific "fields" that it is useful to include in the 144 calendar data. For example, an event representing an airline 145 flight could include the airline, flight number, departure and 146 arrival airport codes, check-in and gate-closing times etc. As 147 another example, a sporting event might contain information about 148 the type of sport, the home and away teams, the league the teams 149 are in, information about nearby parking, etc. 151 PARTICIPANT-TYPE: Used in the PARTICIPANT component to define the 152 type. 154 CALENDAR-ADDRESS: Used in the PARTICIPANT component to provide the 155 calendar address of the participant. 157 In addition the SOURCE property defined in [RFC7986] is redefined to 158 allow VALUE=TEXT and broaden its usage. 160 1.1. Conventions Used in This Document 162 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 163 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 164 "OPTIONAL" in this document are to be interpreted as described in 165 [RFC2119]. 167 2. Components and properties 169 Previous extensions to the calendaring standards have been largely 170 restricted to the addition of properties or parameters. This is 171 partly because iCalendar libraries had trouble handling components 172 nested deeper than those defined in [RFC5545] 174 In a break with this 'tradition' this specification introduces one of 175 these extensions as a component rather than a property. This is a 176 better match for the way XML and JSON handles such structures and 177 allows richer definitions. 179 It also allows for the addition of extra properties inside the 180 component and resolves some of the problems of trying to add detailed 181 information as a parameter. 183 3. Typed References 185 The properties defined here can all reference external meta-data 186 which may be used by applications to provide enhanced value to users. 187 By providing type information as parameters, clients and servers are 188 able to discover interesting references and make use of them, perhaps 189 for indexing or the presentation of additional related information 190 for the user. 192 The [RFC5545] LOCATION property provides only an unstructured single 193 text value for specifying the location where an event (or task) will 194 occur. This is inadequate for use cases where structured location 195 information (e.g. address, region, country, postal code) is required 196 or preferred, and limits widespread adoption of iCalendar in those 197 settings. 199 Using STRUCTURED-LOCATION, information about a number of interesting 200 locations can be communicated, for example, parking, restaurants and 201 the venue. Servers and clients can retrieve the objects when storing 202 the event and use them to index by geographic location. 204 When a calendar client receives a calendar component it can search 205 the set of supplied properties looking for those of particular 206 interest. The TYPE and FMTTYPE parameters, if supplied, can be used 207 to help the selection. 209 The PARTICIPANT component is designed to handle common use cases in 210 event publication. It is generally important to provide information 211 about the organizers of such events. Sponsors wish to be referenced 212 in a prominent manner. In social calendaring it is often important 213 to identify the active participants in the event, for example a 214 school sports team, and the inactive participants, for example the 215 parents. 217 The PARTICIPANT component can also be used to provide useful extra 218 data about an attendee. For example a LOCATION property inside the 219 PARTICIPANT gives the actual location of a remote attendee. 221 3.1. Use Cases 223 The main motivation for these properties has been event publication 224 but there are opportunities for use elsewhere. The following use 225 cases will describe some possible scenarios. 227 3.1.1. Piano Concert Performance 229 In putting together a concert there are many participants: piano 230 tuner, performer, stage hands etc. In addition there are sponsors 231 and various contacts to be provided. There will also be a number of 232 related locations. A number of events can be created, all of which 233 relate to the performance in different ways. 235 There may be an iTip [RFC5546] meeting request for the piano tuner 236 who will arrive before the performance. Other members of staff may 237 also receive meeting requests. 239 An event can also be created for publication which will have a 240 PARTICIPANT component for the pianist providing a reference to vcard 241 information about the performer. This event would also hold 242 information about parking, local subway stations and the venue 243 itself. In addition, there will be sponsorship information for 244 sponsors of the event and perhaps paid sponsorship properties 245 essentially advertising local establishments. 247 3.1.2. Itineraries 249 These additions also provide opportunities for the travel industry. 250 When booking a flight the PARTICIPANT component can be used to 251 provide references to businesses at the airports and to car hire 252 businesses at the destination. 254 The embedded location information can guide the traveller at the 255 airport or to their final destination. The contact information can 256 provide detailed information about the booking agent, the airlines 257 and car hire companies and the hotel. 259 3.1.2.1. Reserving facilities 261 For a meeting, the size of a room and the equipment needed depends to 262 some extent on the number of attendees actually in the room. 264 A meeting may have 10 attendees non of which are co-located. The 265 current ATTENDEE property dos not allow for the additon of such meta- 266 data. The PARTICIPANT property allows attendees to specify their 267 location. 269 4. Modifications to Calendar Components 271 The following changes to the syntax defined in iCalendar [RFC5545] 272 are made here. New elements are defined in subsequent sections. 274 eventc = "BEGIN" ":" "VEVENT" CRLF 275 eventprop *alarmc *participantc 276 "END" ":" "VEVENT" CRLF 278 eventprop =/ *( 279 ; 280 ; The following are OPTIONAL, 281 ; and MAY occur more than once. 282 ; 283 styleddescription / strucloc / strucres / sdataprop 284 ; 285 ) 287 todoc = "BEGIN" ":" "VTODO" CRLF 288 todoprop *alarmc *participantc 289 "END" ":" "VTODO" CRLF 291 todoprop =/ *( 292 ; 293 ; The following are OPTIONAL, 294 ; and MAY occur more than once. 295 ; 296 styleddescription / strucloc / strucres / sdataprop 297 ; 298 ) 300 journalc = "BEGIN" ":" "VJOURNAL" CRLF 301 jourprop *participantc 302 "END" ":" "VJOURNAL" CRLF 304 jourprop =/ *( 305 ; 306 ; The following are OPTIONAL, 307 ; and MAY occur more than once. 308 ; 309 styleddescription / sdataprop 310 ; 311 ) 313 5. New Property Parameters 315 This specification makes use of the LABEL property parameter which is 316 defined in [RFC7986] 318 5.1. Loctype 320 Parameter name: LOCTYPE 322 Purpose: To specify the type of location. 324 Format Definition: 326 This parameter is defined by the following notation: 328 loctypeparam = "LOCTYPE" "=" param-value 330 Description: This parameter MAY be specified on STRUCTURED-LOCATION 331 and provides a way to differentiate multiple properties. For 332 example, it allows event producers to provide location information 333 for the venue and the parking. 335 Values for this parameter are taken from the values defined in 336 [RFC4589]. New location types SHOULD be registered in the manner 337 laid down in that specification 339 5.2. Restype 341 Parameter name: RESTYPE 343 Purpose: To specify the type of resource. 345 Format Definition: 347 This parameter is defined by the following notation: 349 restypeparam = "RESTYPE" "=" param-value 351 Description: This parameter MAY be specified on STRUCTURED-RESOURCE 352 and provides a way to differentiate multiple properties. 354 The allowable values are defined in Section 10 New resource types 355 SHOULD be registered in the manner laid down in this specification 357 5.3. Order 359 Parameter name: ORDER 361 Purpose: To define ordering for the associated property. 363 Format Definition: 365 This parameter is defined by the following notation: 367 orderparam = "ORDER" "=" integer ;Must be greater than or equal to 1 369 Description: The ORDER parameter is OPTIONAL and is used to indicate 370 the relative ordering of the corresponding instance of a property. 371 Its value MUST be an integer greater than or equal to 1 that 372 quantifies the order with 1 being the first in the ordering. 374 When the parameter is absent, the default MUST be to interpret the 375 property instance as being at the lowest level of ordering, that 376 is, the property will appear after any other instances of the same 377 property with any value of ORDER. 379 Note that the value of this parameter is to be interpreted only in 380 relation to values assigned to other corresponding instances of 381 the same property in the same entity. A given value, or the 382 absence of a value, MUST NOT be interpreted on its own. 384 This parameter MAY be applied to any property that allows multiple 385 instances. 387 5.4. Schema 389 Parameter Name: SCHEMA 391 Purpose: To specify the schema used for the content of a 392 "STRUCTURED-DATA" property value. 394 Format Definition: 396 This parameter is defined by the following notation: 398 schemaparam = "SCHEMA" "=" DQUOTE uri DQUOTE 400 Description: This property parameter SHOULD be specified on 401 "STRUCTURED-DATA" properties. When present it provides 402 identifying information about the nature of the content of the 403 corresponding "STRUCTURED-DATA" property value. This can be used 404 to supplement the media type information provided by the "FMTTYPE" 405 parameter on the corresponding property. 407 Example: 409 STRUCTURED-DATA;FMTTYPE=application/ld+json; 410 SCHEMA="https://schema.org/FlightReservation"; 411 ENCODING=BASE64;VALUE=BINARY:Zm9vYmFy 413 6. Redefined Property SOURCE 415 The SOURCE property defined in [RFC7986] is redefined to allow 416 VALUE=TEXT and broaden its usage to any component. 418 Property name: SOURCE 420 Purpose: This property provides a reference to information about a 421 component such as a participant possibly as a vcard or optionally 422 a plain text typed value. 424 Value type: The default value type for this property is URI. The 425 value type can also be set to TEXT to indicate plain text content. 427 Property Parameters: Non-standard or format type parameters can be 428 specified on this property. 430 Conformance: This property MAY be appear in any iCalendar component. 432 Description: This property provides information about the component 433 in which it appears. 435 In a resource or participant it may provide a reference to a vcard 436 giving directory information. 438 In a VCALENDAR component this property identifies a location where 439 a client can retrieve updated data for the calendar. Clients 440 SHOULD honor any specified "REFRESH-INTERVAL" value when 441 periodically retrieving data. Note that this property differs 442 from the "URL" property in that "URL" is meant to provide an 443 alternative representation of the calendar data rather than the 444 original location of the data. 446 In a calendar entity component such as an event the SOURCE 447 property may provide a reference to the original source of the 448 event. This may be used by aggregators to provide a link back. 450 Format Definition: 452 This property is defined by the following notation: 454 source = "SOURCE" sourceparam 455 ( 456 ( 457 ";" "VALUE" "=" "URI" 458 ":" uri 459 ) / 460 ( 461 ";" "VALUE" "=" "TEXT" 462 ":" text 463 ) 464 ) 465 CRLF 467 sourceparam = *( 468 ; 469 ; the following are OPTIONAL 470 ; but MUST NOT occur more than once 471 ; 472 (";" fmttypeparam) / 473 ; 474 ; the following is OPTIONAL 475 ; and MAY occur more than once 476 ; 477 (";" other-param) 478 ; 479 ) 481 Example: 483 The following is an example referring to a VCARD. 485 SOURCE;FMTTYPE=text/vcard;VALUE=URL: 486 http://dir.example.com/vcard/contacts/contact1.vcf 488 7. New Properties 490 7.1. Participant Type 492 Property name: PARTICIPANT-TYPE 494 Purpose: To specify the type of participant. 496 Value type: The value type for this property is TEXT. The allowable 497 values are defined in Section 9. 499 Property Parameters: Non-standard parameters can be specified on 500 this property. 502 Conformance: This property MUST be specified within a PARTICIPANT 503 component. 505 Description: This property defines the type of participation in 506 events or tasks. Participants can be individuals or 507 organizations, for example a soccer team, the spectators, or the 508 musicians. 510 Format Definition: 512 This parameter is defined by the following notation: 514 participanttype = "PARTICIPANT-TYPE" "=" iana-token 516 7.2. Calendar Address 518 Property name: CALENDAR-ADDRESS 520 Purpose: To specify the calendar address for a participant. 522 Value type: CAL-ADDRESS 524 Property Parameters: IANA or non-standard property parameters can be 525 specified on this property. 527 Conformance: This property MAY be specified within a PARTICIPANT 528 component. 530 Description: This property provides a calendar user address for the 531 participant. If there is an ATTENDEE property with the same value 532 then the participant is schedulable. 534 Format Definition: 536 This parameter is defined by the following notation: 538 calendaraddress = "CALENDAR-ADDRESS" "=" cal-address 540 7.3. Styled-Description 542 Property name: STYLED-DESCRIPTION 544 Purpose: This property provides for one or more rich-text 545 descriptions to replace or augment that provided by the 546 DESCRIPTION property. 548 Value type: There is no default value type for this property. The 549 value type can be set to URI or TEXT. Other text-based value 550 types can be used when defined in the future. Clients MUST ignore 551 any properties with value types they do not understand. 553 Property Parameters: IANA, non-standard, id, alternate text 554 representation, format type, and language property parameters can 555 be specified on this property. 557 Conformance: The property can be specified multiple times in the 558 "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar components. 560 Description: This property is used in the "VEVENT" and "VTODO" to 561 capture lengthy textual descriptions associated with the activity. 562 This property is used in the "VJOURNAL" calendar component to 563 capture one or more textual journal entries. This property is 564 used in the "VALARM" calendar component to capture the display 565 text for a DISPLAY category of alarm, and to capture the body text 566 for an EMAIL category of alarm. 568 VALUE=TEXT is used to provide rich-text variants of the plain-text 569 DESCRIPTION property. 571 VALUE=URI is used to provide a link to rich-text content which is 572 expected to be displayed inline as part of the event. 574 The intent of this property is limited to providing a styled and/ 575 or language specific version of the DESCRIPTION property. The URL 576 property should be used to link to websites or other related 577 information. 579 Applications MAY attempt to guess the media type of the resource 580 via inspection of its content if and only if the media type of the 581 resource is not given by the "FMTTYPE" parameter. If the media 582 type remains unknown, calendar applications SHOULD treat it as 583 type "text/html". 585 Multiple STYLED-DESCRIPTION properties may be used to provide 586 different formats or different language variants. 588 Format Definition: 590 This property is defined by the following notation: 592 styleddescription = "STYLED-DESCRIPTION" styleddescparam ":" 593 ( 594 ( 595 ";" "VALUE" "=" "URI" 596 ":" uri 597 ) / 598 ( 599 ";" "VALUE" "=" "TEXT" 600 ":" text 601 ) 602 ) 603 CRLF 605 styleddescparam = *( 606 ; 607 ; The following are OPTIONAL, 608 ; but MUST NOT occur more than once. 609 ; 610 (";" altrepparam) / (";" languageparam) / 611 (";" fmttypeparam) / 612 ; 613 ; the following is OPTIONAL 614 ; and MAY occur more than once 615 ; 616 (";" other-param) 617 ) 619 Example: 621 The following is an example of this property. It points to an html 622 description. 624 STYLED-DESCRIPTION;VALUE=URI:http://example.org/desc001.html 626 7.4. Structured-Location 628 Property name: STRUCTURED-LOCATION 630 Purpose: This property provides a typed reference to external 631 information about the location of an event or optionally a plain 632 text typed value. 634 Value type: There is no default value type for this property. The 635 value type can be set to URI or TEXT. 637 Property Parameters: IANA, non-standard, label, loctype or format 638 type parameters can be specified on this property. 640 Conformance: This property MAY be specified zero or more times in 641 any iCalendar component. 643 Description: When used in a component the value of this property 644 provides information about the event venue or of related services 645 such as parking, dining, stations etc.. 647 When a LABEL parameter is supplied the language of the label must 648 match that of the content and of the LANGUAGE parameter if 649 present. 651 Format Definition: 653 This property is defined by the following notation: 655 strucloc = "STRUCTURED-LOCATION" struclocparam 656 ( 657 ( 658 ";" "VALUE" "=" "URI" 659 ":" uri 660 ) / 661 ( 662 ";" "VALUE" "=" "TEXT" 663 ":" text 664 ) 665 ) 666 CRLF 668 struclocparam = *( 669 ; 670 ; the following are OPTIONAL 671 ; but MUST NOT occur more than once 672 ; 673 (";" fmttypeparam) / 674 (";" labelparam) / 675 (";" languageparam) / 676 (";" loctypeparam) / 677 ; 678 ; the following is OPTIONAL 679 ; and MAY occur more than once 680 ; 681 (";" other-param) 682 ) 684 Example: 686 The following is an example of this property. It points to a venue. 688 STRUCTURED-LOCATION;LABEL="The venue": 689 http://dir.example.com/venues/big-hall.vcf 691 7.5. Structured-Resource 693 Property name: STRUCTURED-RESOURCE 695 Purpose: This property provides a typed reference to external 696 information about a resource or optionally a plain text typed 697 value. 699 Value type: There is no default value type for this property. The 700 value type can be set to URI or TEXT. 702 Property Parameters: IANA, non-standard, label, restype or format 703 type parameters can be specified on this property. 705 Conformance: This property MAY be specified zero or more times in 706 any iCalendar component. 708 Description: When used in a component the value of this property 709 provides information about resources used for the event. 711 When a LABEL parameter is supplied the language of the label must 712 match that of the content and of the LANGUAGE parameter if 713 present. 715 Format Definition: 717 This property is defined by the following notation: 719 strucres = "STRUCTURED-RESOURCE" strucresparam / 720 ( 721 ( 722 ";" "VALUE" "=" "URI" 723 ":" uri 724 ) / 725 ( 726 ";" "VALUE" "=" "TEXT" 727 ":" text 728 ) 729 ) 730 CRLF 732 strucresparam = *( 733 ; 734 ; the following are OPTIONAL 735 ; but MUST NOT occur more than once 736 ; 737 (";" fmttypeparam) / 738 (";" labelparam) / 739 (";" languageparam) / 740 (";" restypeparam) / 741 ; 742 ; the following is OPTIONAL 743 ; and MAY occur more than once 744 ; 745 (";" other-param) 746 ) 748 Example: 750 The following is an example of this property. It refers to a 751 projector. 753 STRUCTURED-RESOURCE;restype="projector": 754 http://dir.example.com/projectors/3d.vcf 756 7.6. Structured-Data 758 Property Name: STRUCTURED-DATA 760 Purpose: This property specifies ancillary data associated with the 761 calendar component. 763 Value Type: TEXT, BINARY or URI 764 Property Parameters: IANA, non-standard, inline encoding, and value 765 data type property parameters can be specified on this property. 766 The format type and schema parameters can be specified on this 767 property and are RECOMMENDED for text or inline binary encoded 768 content information. 770 Conformance: This property can be specified multiple times in an 771 iCalendar object. Typically it would be used in "VEVENT", 772 "VTODO", or "VJOURNAL" calendar components. 774 Description: This property is used to specify ancillary data in some 775 structured format either directly (inline) as a "TEXT" or "BINARY" 776 value, or as a link via a "URI" value. 778 Rather than define new iCalendar properties for the variety of 779 event types that might occur, it would be better to leverage 780 existing schemas for such data. For example, schemas available at 781 https://schema.org include different event types. By using 782 standard schemas, interoperability can be improved between 783 calendar clients and non-calendaring systems that wish to generate 784 or process the data. 786 This property allows the direct inclusion of ancillary data whose 787 schema is defined elsewhere. This property also includes 788 parameters to clearly identify the type of the schema being used 789 so that clients can quickly and easily spot what is relevant 790 within the calendar data and present that to users or process it 791 within the calendaring system. 793 iCalendar does support an "ATTACH" property which can be used to 794 include documents or links to documents within the calendar data. 795 However, that property does not allow data to be included as a 796 "TEXT" value (a feature that "STRUCTURED-DATA" does allow), plus 797 attachments are often treated as "opaque" data to be processed by 798 some other system rather than the calendar client. Thus the 799 existing "ATTACH" property is not sufficient to cover the specific 800 needs of inclusion of schema data. Extending the "ATTACH" 801 property to support a new value type would likely cause 802 interoperability problems. Thus a new property to support 803 inclusion of schema data is warranted. 805 Format Definition: 807 This property is defined by the following notation: 809 sdataprop = "STRUCTURED-DATA" sdataparam 810 (":" text) / 811 ( 812 ";" "ENCODING" "=" "BASE64" 813 ";" "VALUE" "=" "BINARY" 814 ":" binary 815 ) / 816 ( 817 ";" "VALUE" "=" "URI" 818 ":" uri 819 ) 820 CRLF 822 sdataparam = *( 823 ; 824 ; The following is OPTIONAL for a URI value, 825 ; RECOMMENDED for a TEXT or BINARY value, 826 ; and MUST NOT occur more than once. 827 ; 828 (";" fmttypeparam) / 829 (";" schemaparam) / 830 ; 831 ; The following is OPTIONAL, 832 ; and MAY occur more than once. 833 ; 834 (";" other-param) 835 ; 836 ) 838 Example: The following is an example of this property: 840 STRUCTURED-DATA;FMTTYPE=application/ld+json; 841 SCHEMA="https://schema.org/SportsEvent"; 842 VALUE=TEXT:{\n 843 "@context": "http://schema.org"\,\n 844 "@type": "SportsEvent"\,\n 845 "homeTeam": "Pittsburgh Pirates"\,\n 846 "awayTeam": "San Francisco Giants"\n 847 }\n 849 8. New Components 850 8.1. Participant 852 Component name: PARTICIPANT 854 Purpose: This component provides information about a participant in 855 an event or optionally a plain text typed value. 857 Conformance: This component MAY be appear in any iCalendar 858 component. 860 Description: This component provides information about an 861 participant in an event, task or poll. A participant may be an 862 attendee in a scheduling sense and the ATTENDEE property may be 863 specified in addition. Participants in events can be individuals 864 or organizations, for example a soccer team, the spectators, or 865 the musicians. 867 The SOURCE property if present may refer to an external definition 868 of the participant - such as a vcard. 870 The STRUCTURED-ADDRESS property if present will provide a cal- 871 address. If an ATTENDEE property has the same value the 872 participant is considered schedulable. The PARTICIPANT component 873 can be used to contain additional meta-data related to the 874 attendee. 876 Format Definition: 878 This property is defined by the following notation: 880 participantc = "BEGIN" ":" "PARTICIPANT" CRLF 881 partprop *alarmc 882 "END" ":" "PARTICIPANT" CRLF 884 partprop = *( 885 ; 886 ; The following are REQUIRED, 887 ; but MUST NOT occur more than once. 888 ; 889 dtstamp / participanttype / 890 ; 891 ; The following are OPTIONAL, 892 ; but MUST NOT occur more than once. 893 ; 894 created / description / last-mod / priority / seq / 895 source / status / scheduleaddress / summary / url / 896 ; 897 ; The following are OPTIONAL, 898 ; and MAY occur more than once. 899 ; 900 attach / categories / comment / 901 contact / rstatus / related / 902 resources / x-prop / iana-prop 903 ; 904 ) 906 Note: When the PRIORITY is supplied it defines the ordering of 907 PARTICIPANT components with the same value for the TYPE parameter. 909 Example: 911 The following is an example of this component. It contains a SOURCE 912 property which points to a VCARD providing information about the 913 event participant. 915 BEGIN:PARTICIPANT 916 PARTICIPANT-TYPE:PRINCIPAL_PERFORMER 917 SOURCE:http://dir.example.com/vcard/aviolinist.vcf 918 END:PARTICIPANT 920 Example: 922 The following is an example for the primary contact. 924 BEGIN: PARTICIPANT 925 SOURCE;FMTTYPE=text/vcard; 926 http://dir.example.com/vcard/contacts/contact1.vcf 927 PARTICIPANT-TYPE:PRIMARY-CONTACT 928 DESCRIPTION:A contact: 929 END:PARTICIPANT 931 8.2. Schedulable Participant 933 A PARTICIPANT component may represent someone or something that needs 934 to be scheduled as defined for ATTENDEE in [RFC5545] and [RFC5546]. 935 The PARTICIPANT component may also represent someone or something 936 that is NOT to receive scheduling messages. 938 A PARTICIPANT component is defined to be schedulable if 940 o It contains a CALENDAR-ADDRESS property 942 o That property value is the same as the value for an ATTENDEE 943 property. 945 If both of these conditions apply then the participant defined by the 946 value of the URL property will take part in scheduling operations as 947 defined in [RFC5546]. 949 An appropriate use for the PARTICIPANT component in scheduling would 950 be to store SEQUENCE and DTSTAMP properties associated with replies 951 from each ATTENDEE. A LOCATION property within the PARTICIPANT 952 component might allow better selection of meeting times when 953 participants are in different timezones. 955 9. Participant Types 957 This section describes types of participation and provides registered 958 values for the PARTICIPANT-TYPE property. 960 ACTIVE: A participant taking an active role - for example a team 961 member. 963 INACTIVE: A participant taking an inactive part - for example an 964 audience member. 966 SPONSOR: A sponsor of the event. The ORDER parameter may be used 967 with this participant type to define the relative order of 968 multiple sponsors. 970 CONTACT: Contact information for the event. The ORDER parameter may 971 be used with this participant type to define the relative order of 972 multiple contacts. 974 BOOKING-CONTACT: Contact information for reservations or payment 976 EMERGENCY-CONTACT: Contact in case of emergency 978 PUBLICITY-CONTACT: Contact for publicity 980 PLANNER-CONTACT: Contact for the event planner or organizer 982 PERFORMER: A performer - for example the soloist or the accompanist. 983 The ORDER parameter may be used with this participant type to 984 define the relative order of multiple performers. For example, 985 ORDER=1 could define the principal performer or soloist. 987 SPEAKER: Speaker at an event 989 10. Resource Types 991 This section describes some initial resource types registered values 992 for the RESTYPE parameter. Typically a resource is anything that 993 might be required or used by a calendar entity and possibly has a 994 directory entry. 996 Such resources may be a room or a projector. This registry provides 997 a place in which such resources may be registered for use by 998 scheduling sevices. 1000 ROOM: A room for he event/meeting. 1002 PROJECTOR: Projection equipment. 1004 REMOTE-CONFERENCE-AUDIO: Audio remote conferencing facilities. 1006 REMOTE-CONFERENCE-VIDEO: Video remote conferencing facilities. 1008 11. Extended examples 1010 The following are some examples of the use of the properties defined 1011 in this specification. They include additional properties defined in 1012 [RFC7986] which includes IMAGE. 1014 11.1. Example 1 1016 The following is an example of a VEVENT describing a concert. It 1017 includes location information for the venue itself as well as 1018 references to parking and restaurants. 1020 BEGIN:VEVENT 1021 CREATED:20170216T145739Z 1022 DESCRIPTION: Piano Sonata No 3\n 1023 Piano Sonata No 30 1024 DTSTAMP:20171116T145739Z 1025 DTSTART;TZID=America/New_York:20170315T150000Z 1026 DTEND;TZID=America/New_York:20170315T163000Z 1027 LAST-MODIFIED:20170216T145739Z 1028 SUMMARY:Beethoven Piano Sonatas 1029 UID:123456 1030 STRUCTURED-LOCATION;LABEL="The venue": 1031 http://dir.example.com/venues/big-hall.vcf 1032 STRUCTURED-LOCATION;LABEL="The venue": 1033 http://dir.example.com/venues/parking.vcf 1034 IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:h 1035 ttp://example.com/images/concert.png 1036 BEGIN:PARTICIPANT 1037 PARTICIPANT-TYPE:SPONSOR 1038 SOURCE:http://example.com/sponsor.vcf 1039 END:PARTICIPANT 1040 BEGIN:PARTICIPANT 1041 PARTICIPANT-TYPE:PERFORMER: 1042 SOURCE:http://www.example.com/people/johndoe.vcf 1043 END:PARTICIPANT 1044 END:VEVENT 1046 11.2. Example 2 1047 The following is an example of a VEVENT describing a meeting. One of 1048 the attendees is a remote participant. 1050 BEGIN:VEVENT 1051 CREATED:20170216T145739Z 1052 DTSTAMP:20101116T145739Z 1053 DTSTART;TZID=America/New_York:20170315T150000Z 1054 DTEND;TZID=America/New_York:20170315T163000Z 1055 LAST-MODIFIED:20170216T145739Z 1056 SUMMARY:Conference plaaning 1057 UID:123456 1058 ORGANIZER:mailto:a@example.com 1059 ATTENDEE;PARTSTAT=ACCEPTED;CN=A:mailto:a@example.com 1060 ATTENDEE;RSVP=TRUE;CN=B:mailto:b@example.com 1061 BEGIN:PARTICIPANT 1062 PARTICIPANT-TYPE:ACTIVE: 1063 SOURCE:http://www.example.com/people/b.vcf 1064 LOCATION:At home 1065 END:PARTICIPANT 1066 END:VEVENT 1068 12. Security Considerations 1070 Applications using these properties need to be aware of the risks 1071 entailed in using the URIs provided as values. See [RFC3986] for a 1072 discussion of the security considerations relating to URIs. 1074 Security considerations relating to the "ATTACH" property, as 1075 described in [RFC5545], are applicable to the "STRUCTURED-DATA" 1076 property. 1078 13. Privacy Considerations 1080 Properties with a "URI" value type can expose their users to privacy 1081 leaks as any network access of the URI data can be tracked. Clients 1082 SHOULD NOT automatically download data referenced by the URI without 1083 explicit instruction from users. This specification does not 1084 introduce any additional privacy concerns beyond those described in 1085 [RFC5545]. 1087 14. IANA Considerations 1089 This section defines updates to the tables defined in [RFC5545] and 1090 new tables. 1092 14.1. Additional iCalendar Registrations 1094 14.1.1. Property Registrations 1096 This document defines the following new iCalendar properties to be 1097 added to the registry defined in Section 8.2.3 of [RFC5545]: 1099 +---------------------+---------+----------------------+ 1100 | Property | Status | Reference | 1101 +---------------------+---------+----------------------+ 1102 | CALENDAR-ADDRESS | Current | RFCXXXX, Section 7.2 | 1103 | PARTICIPANT-TYPE | Current | RFCXXXX, Section 7.1 | 1104 | SOURCE | Current | RFCXXXX, Section 6 | 1105 | STRUCTURED-DATA | Current | RFCXXXX, Section 7.6 | 1106 | STYLED-DESCRIPTION | Current | RFCXXXX, Section 7.3 | 1107 | STRUCTURED-LOCATION | Current | RFCXXXX, Section 7.4 | 1108 | STRUCTURED-RESOURCE | Current | RFCXXXX, Section 7.5 | 1109 +---------------------+---------+----------------------+ 1111 14.1.2. Parameter Registrations 1113 This document defines the following new iCalendar property parameters 1114 to be added to the registry defined in Section 8.2.4 of [RFC5545]: 1116 +--------------------+---------+----------------------+ 1117 | Property Parameter | Status | Reference | 1118 +--------------------+---------+----------------------+ 1119 | LOCTYPE | Current | RFCXXXX, Section 5.1 | 1120 | ORDER | Current | RFCXXXX, Section 5.3 | 1121 | RESTYPE | Current | RFCXXXX, Section 5.2 | 1122 | SCHEMA | Current | RFCXXXX, Section 5.4 | 1123 +--------------------+---------+----------------------+ 1125 14.1.3. Component Registrations 1127 This document defines the following new iCalendar components to be 1128 added to the registry defined in Section 8.3.1 of [RFC5545]: 1130 +-------------+---------+----------------------+ 1131 | Component | Status | Reference | 1132 +-------------+---------+----------------------+ 1133 | PARTICIPANT | Current | RFCXXXX, Section 8.1 | 1134 +-------------+---------+----------------------+ 1136 14.2. New Registration Tables 1138 This section defines new registration tables for PARTICIPANT-TYPE and 1139 RESTYPE values. These tables maybe updated using the same approaches 1140 laid down in Section 8.2.1 of [RFC5545] 1142 14.2.1. Participant Types Registry 1144 The following table has been used to initialize the participant types 1145 registry. 1147 +-------------------+---------+--------------------+ 1148 | Participant Type | Status | Reference | 1149 +-------------------+---------+--------------------+ 1150 | ACTIVE | Current | RFCXXXX, Section 9 | 1151 | INACTIVE | Current | RFCXXXX, Section 9 | 1152 | SPONSOR | Current | RFCXXXX, Section 9 | 1153 | CONTACT | Current | RFCXXXX, Section 9 | 1154 | BOOKING-CONTACT | Current | RFCXXXX, Section 9 | 1155 | EMERGENCY-CONTACT | Current | RFCXXXX, Section 9 | 1156 | PUBLICITY-CONTACT | Current | RFCXXXX, Section 9 | 1157 | PLANNER-CONTACT | Current | RFCXXXX, Section 9 | 1158 | PERFORMER | Current | RFCXXXX, Section 9 | 1159 | SPEAKER | Current | RFCXXXX, Section 9 | 1160 +-------------------+---------+--------------------+ 1162 14.2.2. Resource Types Registry 1164 The following table has been used to initialize the resource types 1165 registry. 1167 +-------------------------+---------+---------------------+ 1168 | Resource Type | Status | Reference | 1169 +-------------------------+---------+---------------------+ 1170 | PROJECTOR | Current | RFCXXXX, Section 10 | 1171 | ROOM | Current | RFCXXXX, Section 10 | 1172 | REMOTE-CONFERENCE-AUDIO | Current | RFCXXXX, Section 10 | 1173 | REMOTE-CONFERENCE-VIDEO | Current | RFCXXXX, Section 10 | 1174 +-------------------------+---------+---------------------+ 1176 15. Acknowledgements 1178 The author would like to thank Chuck Norris of eventful.com for his 1179 work which led to the development of this RFC. 1181 The author would also like to thank the members of CalConnect, The 1182 Calendaring and Scheduling Consortium, the Event Publication 1183 technical committee and the following individuals for contributing 1184 their ideas and support: 1186 Cyrus Daboo, John Haug, Dan Mendell, Ken Murchison, Scott Otis, 1188 16. Normative References 1190 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1191 Requirement Levels", BCP 14, RFC 2119, 1192 DOI 10.17487/RFC2119, March 1997, 1193 . 1195 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1196 Resource Identifier (URI): Generic Syntax", STD 66, 1197 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1198 . 1200 [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types 1201 Registry", RFC 4589, DOI 10.17487/RFC4589, July 2006, 1202 . 1204 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1205 Scheduling Core Object Specification (iCalendar)", 1206 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1207 . 1209 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1210 Interoperability Protocol (iTIP)", RFC 5546, 1211 DOI 10.17487/RFC5546, December 2009, 1212 . 1214 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 1215 DOI 10.17487/RFC7986, October 2016, 1216 . 1218 [W3C.REC-xml-20060816] 1219 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1220 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth 1221 Edition)", World Wide Web Consortium Recommendation REC- 1222 xml-20060816, August 2006, 1223 . 1225 Appendix A. Open issues 1227 None at the moment 1229 Appendix B. Change log 1231 calext-v04 2017-10-11 MD 1233 o Change SCHEDULE-ADDRESS to CALENDAR-ADDRESS 1235 o Explicitly broaden scope of SOURCE 1237 o Add initial registry for RESTYPE and move new tables into separate 1238 section. 1240 o Fix PARTTYPE/PARTICPANT-TYPE inconsistency 1242 calext-v03 2017-10-09 MD 1244 o Mostly typographical and other minor changes 1246 calext-v02 2017-04-20 MD 1248 o Add SCHEDULE-ADDRESS property 1250 o PARTICIPANT becomes a component rather than a property. Turn many 1251 of the former parameters into properties. 1253 o Use existing ATTENDEE property for scheduling. 1255 calext-v01 2017-02-18 MD 1257 o Change ASSOCIATE back to PARTICIPANT 1259 o PARTICIPANT becomes a component rather than a property. Turn many 1260 of the former parameters into properties. 1262 calext-v00 2016-08-?? MD 1264 o Name changed - taken up by calext working group 1266 v06 2016-06-26 MD 1268 o Fix up abnf 1270 o change ref to ietf from daboo 1272 o take out label spec - use Cyrus spec 1274 v05 2016-06-14 MD 1276 o Remove GROUP and HASH. they can be dealt with elsewhere if desired 1277 o Change ORDER to integer >= 1. 1279 o Incorporate Structured-Data into this specification. 1281 v04 2014-02-01 MD 1283 o Added updates attribute. 1285 o Minor typos. 1287 o Resubmitted mostly to refresh the draft. 1289 v03 2013-03-06 MD 1291 o Replace PARTICIPANT with ASSOCIATE plus related changes. 1293 o Added section showing modifications to components. 1295 o Replace ID with GROUP and modify HASH. 1297 o Replace TITLE param with LABEL. 1299 o Fixed STYLED-DESCRIPTION in various ways, correct example. 1301 v02 2012-11-02 MD 1303 o Collapse sections with description of properties and the use cases 1304 into a section with sub-sections. 1306 o New section to describe relating properties. 1308 o Remove idref and upgrade hash to have the reference 1310 o No default value types on properties.. 1312 v01 2012-10-18 MD Many changes. 1314 o SPONSOR and STRUCTURED-CONTACT are now in PARTICIPANT 1316 o Add a STRUCTURED-RESOURCE property 1318 o STYLED-DESCRIPTION to handle rich text 1320 o Much more... 1322 2011-01-07 1324 o Remove MEDIA - it's going in the Cyrus RFC 1325 o Rename EXTENDED-... to STRUCTURED-... 1327 o Add TYPE parameter to SPONSOR 1329 v00 2007-10-19 MD Initial version 1331 Author's Address 1333 Michael Douglass 1334 Spherical Cow Group 1335 226 3rd Street 1336 Troy, NY 12180 1337 USA 1339 Email: mdouglass@sphericalcowgroup.com 1340 URI: http://sphericalcowgroup.com