idnits 2.17.1 draft-ietf-calext-eventpub-extensions-10.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. 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) -- 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 (October 19, 2018) is 1988 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: 1 error (**), 0 flaws (~~), 1 warning (==), 2 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 (if approved) October 19, 2018 5 Intended status: Standards Track 6 Expires: April 22, 2019 8 Event Publishing Extensions to iCalendar 9 draft-ietf-calext-eventpub-extensions-10 11 Abstract 13 This specification updates RFC5545 by introducing a number of new 14 iCalendar properties and components which are of particular use for 15 event publishers and 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 an 19 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 April 22, 2019. 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 5.4. Schema . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 6. Redefined Property SOURCE . . . . . . . . . . . . . . . . . . 10 70 7. New Properties . . . . . . . . . . . . . . . . . . . . . . . 12 71 7.1. Participant Type . . . . . . . . . . . . . . . . . . . . 12 72 7.2. Calendar Address . . . . . . . . . . . . . . . . . . . . 13 73 7.3. Styled-Description . . . . . . . . . . . . . . . . . . . 14 74 7.4. Structured-Location . . . . . . . . . . . . . . . . . . . 16 75 7.5. Structured-Resource . . . . . . . . . . . . . . . . . . . 17 76 7.6. Structured-Data . . . . . . . . . . . . . . . . . . . . . 19 77 8. New Components . . . . . . . . . . . . . . . . . . . . . . . 21 78 8.1. Participant . . . . . . . . . . . . . . . . . . . . . . . 22 79 8.2. Schedulable Participant . . . . . . . . . . . . . . . . . 24 80 9. Extended examples . . . . . . . . . . . . . . . . . . . . . . 24 81 9.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 24 82 9.2. Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 25 83 10. Security Considerations . . . . . . . . . . . . . . . . . . . 26 84 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 26 85 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 86 12.1. Additional iCalendar Registrations . . . . . . . . . . . 27 87 12.1.1. Properties . . . . . . . . . . . . . . . . . . . . . 27 88 12.1.2. Parameters . . . . . . . . . . . . . . . . . . . . . 27 89 12.1.3. Components . . . . . . . . . . . . . . . . . . . . . 27 90 12.2. New Registration Tables . . . . . . . . . . . . . . . . 28 91 12.2.1. Participant Types . . . . . . . . . . . . . . . . . 28 92 12.2.2. Resource Types . . . . . . . . . . . . . . . . . . . 28 93 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 28 94 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 95 14.1. Normative References . . . . . . . . . . . . . . . . . . 29 96 14.2. Informative References . . . . . . . . . . . . . . . . . 29 98 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 30 99 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 30 100 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 32 102 1. Introduction 104 The currently existing iCalendar standard [RFC5545] lacks useful 105 methods for referencing additional, external information relating to 106 calendar components. Additionally there is no standard way to 107 provide rich text descriptions or meta-data associated with the 108 event. 110 Current practice is to embed this information as links in the 111 description or to add non-standard properties as defined in [RFC5545] 112 section 3.8.8.2. 114 This document updates [RFC5545] to define a number of properties and 115 a component referencing such external information that can provide 116 additional information about an iCalendar component. The intent is 117 to allow interchange of such information between applications or 118 systems (e.g., between clients, between client and server, and 119 between servers). Formats such as VCARD are likely to be most useful 120 to the receivers of such events as they may be used in other 121 applications - such as address books. 123 This specification defines a new PARTICIPANT component. Many people 124 or groups may participate in an event. This component provides 125 detailed information. Such participants may act as attendees to the 126 event (or derived events) or may just provide a reference - perhaps 127 for mailing lists. 129 The following properties are defined in this specification 131 STYLED-DESCRIPTION: Supports HTML descriptions. Event publishers 132 typically wish to provide more and better formatted information 133 about the event. 135 STRUCTURED-LOCATION: There may be a number of locations associated 136 with an event. This provides detailed information about the 137 location. 139 STRUCTURED-RESOURCE: Events need resources such as rooms, 140 projectors, conferencing capabilities. 142 STRUCTURED-DATA: The existing properties in iCalendar cover key 143 elements of events and tasks such as start time, end time, 144 location, summary, etc. However, different types of events often 145 have other specific "fields" that it is useful to include in the 146 calendar data. For example, an event representing an airline 147 flight could include the airline, flight number, departure and 148 arrival airport codes, check-in and gate-closing times etc. As 149 another example, a sporting event might contain information about 150 the type of sport, the home and away teams, the league the teams 151 are in, information about nearby parking, etc. 153 PARTICIPANT-TYPE: Used in the PARTICIPANT component to define the 154 type. 156 CALENDAR-ADDRESS: Used in the PARTICIPANT component to provide the 157 calendar address of the participant. 159 In addition the SOURCE property defined in [RFC7986] is redefined to 160 allow VALUE=TEXT and broaden its usage. 162 1.1. Conventions Used in This Document 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 166 "OPTIONAL" in this document are to be interpreted as described in BCP 167 14 [RFC2119] [RFC8174] when, and only when, they appear in all 168 capitals, as shown here. 170 2. Components and properties 172 Previous extensions to the calendaring standards have been largely 173 restricted to the addition of properties or parameters. This is 174 partly because iCalendar libraries had trouble handling components 175 nested deeper than those defined in [RFC5545] 177 In a break with this 'tradition' this specification introduces one of 178 these extensions as a component rather than a property. This is a 179 better match for the way XML and JSON handles such structures and 180 allows richer definitions. 182 It also allows for the addition of extra properties inside the 183 component and resolves some of the problems of trying to add detailed 184 information as a parameter. 186 3. Typed References 188 The properties defined here can all reference external meta-data 189 which may be used by applications to provide enhanced value to users. 190 By providing type information as parameters, clients and servers are 191 able to discover interesting references and make use of them, perhaps 192 for indexing or the presenting of additional related information for 193 the user. 195 The [RFC5545] LOCATION property provides only an unstructured single 196 text value for specifying the location where an event (or task) will 197 occur. This is inadequate for use cases where structured location 198 information (e.g. address, region, country, postal code) is required 199 or preferred, and limits widespread adoption of iCalendar in those 200 settings. 202 Using STRUCTURED-LOCATION, information about a number of interesting 203 locations can be communicated, for example, address, region, country, 204 postal code as well as other informations such as the parking, 205 restaurants and the venue. Servers and clients can retrieve the 206 objects when storing the event and use them to index by geographic 207 location. 209 When a calendar client receives a calendar component it can search 210 the set of supplied properties looking for those of particular 211 interest. The TYPE and FMTTYPE parameters, if supplied, can be used 212 to help the selection. 214 The PARTICIPANT component is designed to handle common use cases in 215 event publication. It is generally important to provide information 216 about the organizers of such events. Sponsors wish to be referenced 217 in a prominent manner. In social calendaring it is often important 218 to identify the active participants in the event, for example a 219 school sports team, and the inactive participants, for example the 220 parents. 222 The PARTICIPANT component can also be used to provide useful extra 223 data about an attendee. For example a LOCATION property inside the 224 PARTICIPANT gives the actual location of a remote attendee. 226 3.1. Use Cases 228 The main motivation for these properties has been event publication 229 but there are opportunities for use elsewhere. The following use 230 cases will describe some possible scenarios. 232 3.1.1. Piano Concert Performance 234 In putting together a concert there are many participants: piano 235 tuner, performer, stage hands etc. In addition there are sponsors 236 and various contacts to be provided. There will also be a number of 237 related locations. A number of events can be created, all of which 238 relate to the performance in different ways. 240 There may be an iTip [RFC5546] meeting request for the piano tuner 241 who will arrive before the performance. Other members of staff may 242 also receive meeting requests. 244 An event can also be created for publication which will have a 245 PARTICIPANT component for the pianist providing a reference to vcard 246 information about the performer. This event would also hold 247 information about parking, local subway stations and the venue 248 itself. In addition, there will be sponsorship information for 249 sponsors of the event and perhaps paid sponsorship properties 250 essentially advertising local establishments. 252 3.1.2. Itineraries 254 These additions also provide opportunities for the travel industry. 255 When booking a flight the PARTICIPANT component can be used to 256 provide references to businesses at the airports and to car hire 257 businesses at the destination. 259 The embedded location information can guide the traveller at the 260 airport or to their final destination. The contact information can 261 provide detailed information about the booking agent, the airlines, 262 car hire companies and the hotel. 264 3.1.2.1. Reserving facilities 266 For a meeting, the size of a room and the equipment needed depends to 267 some extent on the number of attendees actually in the room. 269 A meeting may have 10 attendees non of which are co-located. The 270 current ATTENDEE property dos not allow for the additon of such meta- 271 data. The PARTICIPANT property allows attendees to specify their 272 location. 274 4. Modifications to Calendar Components 276 The following changes to the syntax defined in iCalendar [RFC5545] 277 are made here. New elements are defined in subsequent sections. 279 eventc = "BEGIN" ":" "VEVENT" CRLF 280 eventprop *alarmc *participantc 281 "END" ":" "VEVENT" CRLF 283 eventprop =/ *( 284 ; 285 ; The following are OPTIONAL, 286 ; and MAY occur more than once. 287 ; 288 styleddescription / strucloc / strucres / sdataprop 289 ; 290 ) 292 todoc = "BEGIN" ":" "VTODO" CRLF 293 todoprop *alarmc *participantc 294 "END" ":" "VTODO" CRLF 296 todoprop =/ *( 297 ; 298 ; The following are OPTIONAL, 299 ; and MAY occur more than once. 300 ; 301 styleddescription / strucloc / strucres / sdataprop 302 ; 303 ) 305 journalc = "BEGIN" ":" "VJOURNAL" CRLF 306 jourprop *participantc 307 "END" ":" "VJOURNAL" CRLF 309 jourprop =/ *( 310 ; 311 ; The following are OPTIONAL, 312 ; and MAY occur more than once. 313 ; 314 styleddescription / sdataprop 315 ; 316 ) 318 5. New Property Parameters 320 This specification makes use of the LABEL parameter which is defined 321 in [RFC7986] 323 5.1. Loctype 325 Parameter name: LOCTYPE 327 Purpose: To specify the type of location. 329 Format Definition: 331 This parameter is defined by the following notation: 333 loctypeparam = "LOCTYPE" "=" param-value 335 Description: This parameter MAY be specified on STRUCTURED-LOCATION 336 and provides a way to differentiate multiple properties. For 337 example, it allows event producers to provide location information 338 for the venue and the parking. 340 Values for this parameter are taken from the values defined in 341 [RFC4589]. New location types SHOULD be registered in the manner 342 laid down in that specification 344 5.2. Restype 346 Parameter name: RESTYPE 348 Purpose: To specify the type of resource. 350 Format Definition: 352 This parameter is defined by the following notation: 354 restypeparam = "RESTYPE" "=" restypevalue CRLF 356 restypevalue = ("ROOM" 357 / "PROJECTOR" 358 / "REMOTE-CONFERENCE-AUDIO" 359 / "REMOTE-CONFERENCE-VIDEO" 360 / x-name ; Experimental status 361 / iana-token) ; Other IANA-registered 362 ; values 364 Description: This parameter MAY be specified on STRUCTURED-RESOURCE 365 and provides a way to differentiate multiple properties. 367 The registered values are described below. New resource types 368 SHOULD be registered in the manner laid down in this specification 370 ROOM: A room for the event/meeting. 372 PROJECTOR: Projection equipment. 374 REMOTE-CONFERENCE-AUDIO: Audio remote conferencing facilities. 376 REMOTE-CONFERENCE-VIDEO: Video remote conferencing facilities. 378 5.3. Order 380 Parameter name: ORDER 382 Purpose: To define ordering for the associated property. 384 Format Definition: 386 This parameter is defined by the following notation: 388 orderparam = "ORDER" "=" integer ;Must be greater than or equal to 1 390 Description: The ORDER parameter is OPTIONAL and is used to indicate 391 the relative ordering of the corresponding instance of a property. 392 Its value MUST be an integer greater than or equal to 1 that 393 quantifies the order with 1 being the first in the ordering. 395 When the parameter is absent, the default MUST be to interpret the 396 property instance as being at the lowest level of ordering, that 397 is, the property will appear after any other instances of the same 398 property with any value of ORDER. 400 When any ORDER parameters have the same value all the associated 401 properties appear as a group within which there is no defined 402 order. 404 Note that the value of this parameter is to be interpreted only in 405 relation to values assigned to other corresponding instances of 406 the same property in the same entity. A given value, or the 407 absence of a value, MUST NOT be interpreted on its own. 409 This parameter MAY be applied to any property that allows multiple 410 instances. 412 5.4. Schema 414 Parameter Name: SCHEMA 416 Purpose: To specify the schema used for the content of a 417 "STRUCTURED-DATA" property value. 419 Format Definition: 421 This parameter is defined by the following notation: 423 schemaparam = "SCHEMA" "=" DQUOTE uri DQUOTE 425 Description: This property parameter SHOULD be specified on 426 "STRUCTURED-DATA" properties. When present it provides 427 identifying information about the nature of the content of the 428 corresponding "STRUCTURED-DATA" property value. This can be used 429 to supplement the media type information provided by the "FMTTYPE" 430 parameter on the corresponding property. 432 Example: 434 STRUCTURED-DATA;FMTTYPE=application/ld+json; 435 SCHEMA="https://schema.org/FlightReservation"; 436 ENCODING=BASE64;VALUE=BINARY:Zm9vYmFy 438 6. Redefined Property SOURCE 440 The SOURCE property defined in [RFC7986] is redefined to allow 441 VALUE=TEXT and broaden its usage to any component. 443 Property name: SOURCE 445 Purpose: This property provides a reference to information about a 446 component such as a participant possibly as a vcard or optionally 447 a plain text typed value. 449 Value type: The default value type for this property is URI. The 450 value type can also be set to TEXT to indicate plain text content. 452 Property Parameters: Non-standard or format type parameters can be 453 specified on this property. 455 Conformance: This property MAY be appear in any iCalendar component. 457 Description: This property provides information about the component 458 in which it appears. 460 In a resource or participant it may provide a reference to a vcard 461 giving directory information. 463 In a VCALENDAR component this property identifies a location where 464 a client can retrieve updated data for the calendar. Clients 465 SHOULD honor any specified "REFRESH-INTERVAL" value when 466 periodically retrieving data. Note that this property differs 467 from the "URL" property in that "URL" is meant to provide an 468 alternative representation of the calendar data rather than the 469 original location of the data. 471 In a calendar entity component such as an event the SOURCE 472 property may provide a reference to the original source of the 473 event. This may be used by aggregators to provide a link back. 475 Format Definition: 477 This property is defined by the following notation: 479 source = "SOURCE" sourceparam 480 ( 481 ( 482 ";" "VALUE" "=" "URI" 483 ":" uri 484 ) / 485 ( 486 ";" "VALUE" "=" "TEXT" 487 ":" text 488 ) 489 ) 490 CRLF 492 sourceparam = *( 493 ; 494 ; the following are OPTIONAL 495 ; but MUST NOT occur more than once 496 ; 497 (";" fmttypeparam) / 498 ; 499 ; the following is OPTIONAL 500 ; and MAY occur more than once 501 ; 502 (";" other-param) 503 ; 504 ) 506 Example: 508 The following is an example referring to a VCARD. 510 SOURCE;FMTTYPE=text/vcard;VALUE=URL: 511 http://dir.example.com/vcard/contacts/contact1.vcf 513 7. New Properties 515 7.1. Participant Type 517 Property name: PARTICIPANT-TYPE 519 Purpose: To specify the type of participant. 521 Value type: The value type for this property is TEXT. The allowable 522 values are defined below. 524 Property Parameters: Non-standard parameters can be specified on 525 this property. 527 Conformance: This property MUST be specified within a PARTICIPANT 528 component. 530 Description: This property defines the type of participation in 531 events or tasks. Participants can be individuals or 532 organizations, for example a soccer team, the spectators, or the 533 musicians. 535 Format Definition: 537 This parameter is defined by the following notation: 539 participanttype = "PARTICIPANT-TYPE" "=" partvalue CRLF 541 partvalue = ("ACTIVE" 542 / "INACTIVE" 543 / "SPONSOR" 544 / "CONTACT" 545 / "BOOKING-CONTACT" 546 / "EMERGENCY-CONTACT" 547 / "PUBLICITY-CONTACT" 548 / "PLANNER-CONTACT" 549 / "PERFORMER" 550 / "SPEAKER" 551 / x-name ; Experimental status 552 / iana-token) ; Other IANA-registered 553 ; values 555 Example: 557 The following is an example of this property: 559 PARTICIPANT-TYPE:SPEAKER 561 The registered values for the PARTICIPANT-TYPE property have the 562 meanings described here: 564 ACTIVE: A participant taking an active role - for example a team 565 member. 567 INACTIVE: A participant taking an inactive part - for example an 568 audience member. 570 SPONSOR: A sponsor of the event. The ORDER parameter may be used 571 with this participant type to define the relative order of 572 multiple sponsors. 574 CONTACT: Contact information for the event. The ORDER parameter may 575 be used with this participant type to define the relative order of 576 multiple contacts. 578 BOOKING-CONTACT: Contact information for reservations or payment 580 EMERGENCY-CONTACT: Contact in case of emergency 582 PUBLICITY-CONTACT: Contact for publicity 584 PLANNER-CONTACT: Contact for the event planner or organizer 586 PERFORMER: A performer - for example the soloist or the accompanist. 587 The ORDER parameter may be used with this participant type to 588 define the relative order of multiple performers. For example, 589 ORDER=1 could define the principal performer or soloist. 591 SPEAKER: Speaker at an event 593 7.2. Calendar Address 595 Property name: CALENDAR-ADDRESS 597 Purpose: To specify the calendar address for a participant. 599 Value type: CAL-ADDRESS 601 Property Parameters: IANA or non-standard property parameters can be 602 specified on this property. 604 Conformance: This property MAY be specified within a PARTICIPANT 605 component. 607 Description: This property provides a calendar user address for the 608 participant. If there is an ATTENDEE property with the same value 609 then the participant is schedulable. 611 Format Definition: 613 This parameter is defined by the following notation: 615 calendaraddress = "CALENDAR-ADDRESS" "=" cal-address 617 7.3. Styled-Description 619 Property name: STYLED-DESCRIPTION 621 Purpose: This property provides for one or more rich-text 622 descriptions to replace or augment that provided by the 623 DESCRIPTION property. 625 Value type: There is no default value type for this property. The 626 value type can be set to URI or TEXT. Other text-based value 627 types can be used when defined in the future. Clients MUST ignore 628 any properties with value types they do not understand. 630 Property Parameters: IANA, non-standard, id, alternate text 631 representation, format type, and language property parameters can 632 be specified on this property. 634 Conformance: The property can be specified multiple times in the 635 "VEVENT", "VTODO", "VJOURNAL", "PARTICIPANT", or "VALARM" calendar 636 components. 638 Description: This property is used in the "VEVENT" and "VTODO" to 639 capture lengthy textual descriptions associated with the activity. 640 This property is used in the "VJOURNAL" calendar component to 641 capture one or more textual journal entries. This property is 642 used in the "VALARM" calendar component to capture the display 643 text for a DISPLAY category of alarm, and to capture the body text 644 for an EMAIL category of alarm. In the PARTICIPANT component it 645 provides a detailed description of the participant. 647 VALUE=TEXT is used to provide rich-text variants of the plain-text 648 DESCRIPTION property. 650 VALUE=URI is used to provide a link to rich-text content which is 651 expected to be displayed inline as part of the event. 653 The intent of this property is limited to providing a styled and/ 654 or language specific version of the DESCRIPTION property. The URL 655 property should be used to link to websites or other related 656 information. 658 Applications MAY attempt to guess the media type of the resource 659 via inspection of its content if and only if the media type of the 660 resource is not given by the "FMTTYPE" parameter. If the media 661 type remains unknown, calendar applications SHOULD treat it as 662 type "text/html". 664 Multiple STYLED-DESCRIPTION properties may be used to provide 665 different formats or different language variants. 667 Format Definition: 669 This property is defined by the following notation: 671 styleddescription = "STYLED-DESCRIPTION" styleddescparam ":" 672 ( 673 ( 674 ";" "VALUE" "=" "URI" 675 ":" uri 676 ) / 677 ( 678 ";" "VALUE" "=" "TEXT" 679 ":" text 680 ) 681 ) 682 CRLF 684 styleddescparam = *( 685 ; 686 ; The following are OPTIONAL, 687 ; but MUST NOT occur more than once. 688 ; 689 (";" altrepparam) / (";" languageparam) / 690 (";" fmttypeparam) / 691 ; 692 ; the following is OPTIONAL 693 ; and MAY occur more than once 694 ; 695 (";" other-param) 696 ) 698 Example: 700 The following is an example of this property. It points to an html 701 description. 703 STYLED-DESCRIPTION;VALUE=URI:http://example.org/desc001.html 705 7.4. Structured-Location 707 Property name: STRUCTURED-LOCATION 709 Purpose: This property provides a typed reference to external 710 information about the location of an event or optionally a plain 711 text typed value. 713 Value type: There is no default value type for this property. The 714 value type can be set to URI or TEXT. 716 Property Parameters: IANA, non-standard, label, loctype or format 717 type parameters can be specified on this property. 719 Conformance: This property MAY be specified zero or more times in 720 any iCalendar component. 722 Description: When used in a component the value of this property 723 provides information about the event venue or of related services 724 such as parking, dining, stations etc.. 726 When a LABEL parameter is supplied the language of the label must 727 match that of the content and of the LANGUAGE parameter if 728 present. 730 Format Definition: 732 This property is defined by the following notation: 734 strucloc = "STRUCTURED-LOCATION" struclocparam 735 ( 736 ( 737 ";" "VALUE" "=" "URI" 738 ":" uri 739 ) / 740 ( 741 ";" "VALUE" "=" "TEXT" 742 ":" text 743 ) 744 ) 745 CRLF 747 struclocparam = *( 748 ; 749 ; the following are OPTIONAL 750 ; but MUST NOT occur more than once 751 ; 752 (";" fmttypeparam) / 753 (";" labelparam) / 754 (";" languageparam) / 755 (";" loctypeparam) / 756 ; 757 ; the following is OPTIONAL 758 ; and MAY occur more than once 759 ; 760 (";" other-param) 761 ) 763 Example: 765 The following is an example of this property. It points to a venue. 767 STRUCTURED-LOCATION;LABEL="The venue": 768 http://dir.example.com/venues/big-hall.vcf 770 7.5. Structured-Resource 772 Property name: STRUCTURED-RESOURCE 774 Purpose: This property provides a typed reference to external 775 information about a resource or optionally a plain text typed 776 value. Typically a resource is anything that might be required or 777 used by a calendar entity and possibly has a directory entry. 779 Value type: There is no default value type for this property. The 780 value type can be set to URI or TEXT. 782 Property Parameters: IANA, non-standard, label, restype or format 783 type parameters can be specified on this property. 785 Conformance: This property MAY be specified zero or more times in 786 any iCalendar component. 788 Description: When used in a component the value of this property 789 provides information about resources used for the event. 791 Such resources may be a room or a projector. This RESTYPE value 792 registry provides a place in which resource types may be 793 registered for use by scheduling sevices. 795 When a LABEL parameter is supplied the language of the label must 796 match that of the content and of the LANGUAGE parameter if 797 present. 799 Format Definition: 801 This property is defined by the following notation: 803 strucres = "STRUCTURED-RESOURCE" strucresparam / 804 ( 805 ( 806 ";" "VALUE" "=" "URI" 807 ":" uri 808 ) / 809 ( 810 ";" "VALUE" "=" "TEXT" 811 ":" text 812 ) 813 ) 814 CRLF 816 strucresparam = *( 817 ; 818 ; the following are OPTIONAL 819 ; but MUST NOT occur more than once 820 ; 821 (";" fmttypeparam) / 822 (";" labelparam) / 823 (";" languageparam) / 824 (";" restypeparam) / 825 ; 826 ; the following is OPTIONAL 827 ; and MAY occur more than once 828 ; 829 (";" other-param) 830 ) 832 Example: 834 The following is an example of this property. It refers to a 835 projector. 837 STRUCTURED-RESOURCE;value=uri;restype="projector": 838 http://dir.example.com/projectors/3d.vcf 840 7.6. Structured-Data 842 Property Name: STRUCTURED-DATA 844 Purpose: This property specifies ancillary data associated with the 845 calendar component. 847 Value Type: TEXT, BINARY or URI 848 Property Parameters: IANA, non-standard, inline encoding, and value 849 data type property parameters can be specified on this property. 850 The format type and schema parameters can be specified on this 851 property and are RECOMMENDED for text or inline binary encoded 852 content information. 854 Conformance: This property can be specified multiple times in an 855 iCalendar object. Typically it would be used in "VEVENT", 856 "VTODO", or "VJOURNAL" calendar components. 858 Description: This property is used to specify ancillary data in some 859 structured format either directly (inline) as a "TEXT" or "BINARY" 860 value, or as a link via a "URI" value. 862 Rather than define new iCalendar properties for the variety of 863 event types that might occur, it would be better to leverage 864 existing schemas for such data. For example, schemas available at 865 https://schema.org include different event types. By using 866 standard schemas, interoperability can be improved between 867 calendar clients and non-calendaring systems that wish to generate 868 or process the data. 870 This property allows the direct inclusion of ancillary data whose 871 schema is defined elsewhere. This property also includes 872 parameters to clearly identify the type of the schema being used 873 so that clients can quickly and easily spot what is relevant 874 within the calendar data and present that to users or process it 875 within the calendaring system. 877 iCalendar does support an "ATTACH" property which can be used to 878 include documents or links to documents within the calendar data. 879 However, that property does not allow data to be included as a 880 "TEXT" value (a feature that "STRUCTURED-DATA" does allow), plus 881 attachments are often treated as "opaque" data to be processed by 882 some other system rather than the calendar client. Thus the 883 existing "ATTACH" property is not sufficient to cover the specific 884 needs of inclusion of schema data. Extending the "ATTACH" 885 property to support a new value type would likely cause 886 interoperability problems. Thus a new property to support 887 inclusion of schema data is warranted. 889 Format Definition: 891 This property is defined by the following notation: 893 sdataprop = "STRUCTURED-DATA" sdataparam 894 (":" text) / 895 ( 896 ";" "ENCODING" "=" "BASE64" 897 ";" "VALUE" "=" "BINARY" 898 ":" binary 899 ) / 900 ( 901 ";" "VALUE" "=" "URI" 902 ":" uri 903 ) 904 CRLF 906 sdataparam = *( 907 ; 908 ; The following is OPTIONAL for a URI value, 909 ; RECOMMENDED for a TEXT or BINARY value, 910 ; and MUST NOT occur more than once. 911 ; 912 (";" fmttypeparam) / 913 (";" schemaparam) / 914 ; 915 ; The following is OPTIONAL, 916 ; and MAY occur more than once. 917 ; 918 (";" other-param) 919 ; 920 ) 922 Example: The following is an example of this property: 924 STRUCTURED-DATA;FMTTYPE=application/ld+json; 925 SCHEMA="https://schema.org/SportsEvent"; 926 VALUE=TEXT:{\n 927 "@context": "http://schema.org"\,\n 928 "@type": "SportsEvent"\,\n 929 "homeTeam": "Pittsburgh Pirates"\,\n 930 "awayTeam": "San Francisco Giants"\n 931 }\n 933 8. New Components 934 8.1. Participant 936 Component name: PARTICIPANT 938 Purpose: This component provides information about a participant in 939 an event or optionally a plain text typed value. 941 Conformance: This component MAY be appear in any iCalendar 942 component. 944 Description: This component provides information about an 945 participant in an event, task or poll. A participant may be an 946 attendee in a scheduling sense and the ATTENDEE property may be 947 specified in addition. Participants in events can be individuals 948 or organizations, for example a soccer team, the spectators, or 949 the musicians. 951 The SOURCE property if present may refer to an external definition 952 of the participant - such as a vcard. 954 The CALENDAR-ADDRESS property if present will provide a cal- 955 address. If an ATTENDEE property has the same value the 956 participant is considered schedulable. The PARTICIPANT component 957 can be used to contain additional meta-data related to the 958 attendee. 960 Format Definition: 962 This property is defined by the following notation: 964 participantc = "BEGIN" ":" "PARTICIPANT" CRLF 965 partprop *alarmc 966 "END" ":" "PARTICIPANT" CRLF 968 partprop = *( 969 ; 970 ; The following are REQUIRED, 971 ; but MUST NOT occur more than once. 972 ; 973 dtstamp / participanttype / 974 ; 975 ; The following are OPTIONAL, 976 ; but MUST NOT occur more than once. 977 ; 978 created / description / last-mod / priority / seq / 979 source / status / calendaraddress / summary / url / 980 ; 981 ; The following are OPTIONAL, 982 ; and MAY occur more than once. 983 ; 984 attach / categories / comment / 985 contact / location / rstatus / related / 986 resources / strucloc / strucres / styleddescription / 987 x-prop / iana-prop 988 ; 989 ) 991 Note: When the PRIORITY is supplied it defines the ordering of 992 PARTICIPANT components with the same value for the TYPE parameter. 994 Example: 996 The following is an example of this component. It contains a SOURCE 997 property which points to a VCARD providing information about the 998 event participant. 1000 BEGIN:PARTICIPANT 1001 PARTICIPANT-TYPE:PRINCIPAL_PERFORMER 1002 SOURCE:http://dir.example.com/vcard/aviolinist.vcf 1003 END:PARTICIPANT 1005 Example: 1007 The following is an example for the primary contact. 1009 BEGIN: PARTICIPANT 1010 SOURCE;FMTTYPE=text/vcard; 1011 http://dir.example.com/vcard/contacts/contact1.vcf 1012 PARTICIPANT-TYPE:PRIMARY-CONTACT 1013 DESCRIPTION:A contact: 1014 END:PARTICIPANT 1016 8.2. Schedulable Participant 1018 A PARTICIPANT component may represent someone or something that needs 1019 to be scheduled as defined for ATTENDEE in [RFC5545] and [RFC5546]. 1020 The PARTICIPANT component may also represent someone or something 1021 that is NOT to receive scheduling messages. 1023 A PARTICIPANT component is defined to be schedulable if 1025 o It contains a CALENDAR-ADDRESS property 1027 o That property value is the same as the value for an ATTENDEE 1028 property. 1030 If both of these conditions apply then the participant defined by the 1031 value of the URL property will take part in scheduling operations as 1032 defined in [RFC5546]. 1034 An appropriate use for the PARTICIPANT component in scheduling would 1035 be to store SEQUENCE and DTSTAMP properties associated with replies 1036 from each ATTENDEE. A LOCATION property within the PARTICIPANT 1037 component might allow better selection of meeting times when 1038 participants are in different timezones. 1040 9. Extended examples 1042 The following are some examples of the use of the properties defined 1043 in this specification. They include additional properties defined in 1044 [RFC7986] which includes IMAGE. 1046 9.1. Example 1 1047 The following is an example of a VEVENT describing a concert. It 1048 includes location information for the venue itself as well as 1049 references to parking and restaurants. 1051 BEGIN:VEVENT 1052 CREATED:20170216T145739Z 1053 DESCRIPTION: Piano Sonata No 3\n 1054 Piano Sonata No 30 1055 DTSTAMP:20171116T145739Z 1056 DTSTART;TZID=America/New_York:20170315T150000Z 1057 DTEND;TZID=America/New_York:20170315T163000Z 1058 LAST-MODIFIED:20170216T145739Z 1059 SUMMARY:Beethoven Piano Sonatas 1060 UID:123456 1061 STRUCTURED-LOCATION;LABEL="The venue": 1062 http://dir.example.com/venues/big-hall.vcf 1063 STRUCTURED-LOCATION;LABEL="The venue": 1064 http://dir.example.com/venues/parking.vcf 1065 IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:h 1066 ttp://example.com/images/concert.png 1067 BEGIN:PARTICIPANT 1068 PARTICIPANT-TYPE:SPONSOR 1069 SOURCE:http://example.com/sponsor.vcf 1070 END:PARTICIPANT 1071 BEGIN:PARTICIPANT 1072 PARTICIPANT-TYPE:PERFORMER: 1073 SOURCE:http://www.example.com/people/johndoe.vcf 1074 END:PARTICIPANT 1075 END:VEVENT 1077 9.2. Example 2 1078 The following is an example of a VEVENT describing a meeting. One of 1079 the attendees is a remote participant. 1081 BEGIN:VEVENT 1082 CREATED:20170216T145739Z 1083 DTSTAMP:20101116T145739Z 1084 DTSTART;TZID=America/New_York:20170315T150000Z 1085 DTEND;TZID=America/New_York:20170315T163000Z 1086 LAST-MODIFIED:20170216T145739Z 1087 SUMMARY:Conference plaaning 1088 UID:123456 1089 ORGANIZER:mailto:a@example.com 1090 ATTENDEE;PARTSTAT=ACCEPTED;CN=A:mailto:a@example.com 1091 ATTENDEE;RSVP=TRUE;CN=B:mailto:b@example.com 1092 BEGIN:PARTICIPANT 1093 PARTICIPANT-TYPE:ACTIVE: 1094 SOURCE:http://www.example.com/people/b.vcf 1095 LOCATION:At home 1096 END:PARTICIPANT 1097 END:VEVENT 1099 10. Security Considerations 1101 Applications using these properties need to be aware of the risks 1102 entailed in using the URIs provided as values. See [RFC3986] for a 1103 discussion of the security considerations relating to URIs. 1105 Security considerations relating to the "ATTACH" property, as 1106 described in [RFC5545], are applicable to the "STRUCTURED-DATA" 1107 property. 1109 11. Privacy Considerations 1111 Properties with a "URI" value type can expose their users to privacy 1112 leaks as any network access of the URI data can be tracked. Clients 1113 SHOULD NOT automatically download data referenced by the URI without 1114 explicit instruction from users. This specification does not 1115 introduce any additional privacy concerns beyond those described in 1116 [RFC5545]. 1118 12. IANA Considerations 1120 This section defines updates to the tables defined in [RFC5545] and 1121 new tables. 1123 12.1. Additional iCalendar Registrations 1125 12.1.1. Properties 1127 This document defines the following new iCalendar properties to be 1128 added to the registry defined in Section 8.2.3 of [RFC5545]: 1130 +---------------------+---------+----------------------+ 1131 | Property | Status | Reference | 1132 +---------------------+---------+----------------------+ 1133 | CALENDAR-ADDRESS | Current | RFCXXXX, Section 7.2 | 1134 | PARTICIPANT-TYPE | Current | RFCXXXX, Section 7.1 | 1135 | SOURCE | Current | RFCXXXX, Section 6 | 1136 | STRUCTURED-DATA | Current | RFCXXXX, Section 7.6 | 1137 | STYLED-DESCRIPTION | Current | RFCXXXX, Section 7.3 | 1138 | STRUCTURED-LOCATION | Current | RFCXXXX, Section 7.4 | 1139 | STRUCTURED-RESOURCE | Current | RFCXXXX, Section 7.5 | 1140 +---------------------+---------+----------------------+ 1142 12.1.2. Parameters 1144 This document defines the following new iCalendar property parameters 1145 to be added to the registry defined in Section 8.2.4 of [RFC5545]: 1147 +--------------------+---------+----------------------+ 1148 | Property Parameter | Status | Reference | 1149 +--------------------+---------+----------------------+ 1150 | LOCTYPE | Current | RFCXXXX, Section 5.1 | 1151 | ORDER | Current | RFCXXXX, Section 5.3 | 1152 | RESTYPE | Current | RFCXXXX, Section 5.2 | 1153 | SCHEMA | Current | RFCXXXX, Section 5.4 | 1154 +--------------------+---------+----------------------+ 1156 12.1.3. Components 1158 This document defines the following new iCalendar components to be 1159 added to the registry defined in Section 8.3.1 of [RFC5545]: 1161 +-------------+---------+----------------------+ 1162 | Component | Status | Reference | 1163 +-------------+---------+----------------------+ 1164 | PARTICIPANT | Current | RFCXXXX, Section 8.1 | 1165 +-------------+---------+----------------------+ 1167 12.2. New Registration Tables 1169 This section defines new registration tables for PARTICIPANT-TYPE and 1170 RESTYPE values. These tables may be updated using the same 1171 approaches laid down in Section 8.2.1 of [RFC5545] 1173 12.2.1. Participant Types 1175 The following table has been used to initialize the participant types 1176 registry. 1178 +-------------------+---------+----------------------+ 1179 | Participant Type | Status | Reference | 1180 +-------------------+---------+----------------------+ 1181 | ACTIVE | Current | RFCXXXX, Section 7.1 | 1182 | INACTIVE | Current | RFCXXXX, Section 7.1 | 1183 | SPONSOR | Current | RFCXXXX, Section 7.1 | 1184 | CONTACT | Current | RFCXXXX, Section 7.1 | 1185 | BOOKING-CONTACT | Current | RFCXXXX, Section 7.1 | 1186 | EMERGENCY-CONTACT | Current | RFCXXXX, Section 7.1 | 1187 | PUBLICITY-CONTACT | Current | RFCXXXX, Section 7.1 | 1188 | PLANNER-CONTACT | Current | RFCXXXX, Section 7.1 | 1189 | PERFORMER | Current | RFCXXXX, Section 7.1 | 1190 | SPEAKER | Current | RFCXXXX, Section 7.1 | 1191 +-------------------+---------+----------------------+ 1193 12.2.2. Resource Types 1195 The following table has been used to initialize the resource types 1196 registry. 1198 +-------------------------+---------+----------------------+ 1199 | Resource Type | Status | Reference | 1200 +-------------------------+---------+----------------------+ 1201 | PROJECTOR | Current | RFCXXXX, Section 5.2 | 1202 | ROOM | Current | RFCXXXX, Section 5.2 | 1203 | REMOTE-CONFERENCE-AUDIO | Current | RFCXXXX, Section 5.2 | 1204 | REMOTE-CONFERENCE-VIDEO | Current | RFCXXXX, Section 5.2 | 1205 +-------------------------+---------+----------------------+ 1207 13. Acknowledgements 1209 The author would like to thank Chuck Norris of eventful.com for his 1210 work which led to the development of this RFC. 1212 The author would also like to thank the members of CalConnect, The 1213 Calendaring and Scheduling Consortium, the Event Publication 1214 technical committee and the following individuals for contributing 1215 their ideas and support: 1217 Cyrus Daboo, John Haug, Dan Mendell, Ken Murchison, Scott Otis, 1219 14. References 1221 14.1. Normative References 1223 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1224 Requirement Levels", BCP 14, RFC 2119, 1225 DOI 10.17487/RFC2119, March 1997, 1226 . 1228 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1229 Resource Identifier (URI): Generic Syntax", STD 66, 1230 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1231 . 1233 [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types 1234 Registry", RFC 4589, DOI 10.17487/RFC4589, July 2006, 1235 . 1237 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1238 Scheduling Core Object Specification (iCalendar)", 1239 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1240 . 1242 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1243 Interoperability Protocol (iTIP)", RFC 5546, 1244 DOI 10.17487/RFC5546, December 2009, 1245 . 1247 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 1248 DOI 10.17487/RFC7986, October 2016, 1249 . 1251 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1252 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1253 May 2017, . 1255 14.2. Informative References 1257 [iana-property-registry] 1258 "IANA iCalendar Element Registries", 1259 . 1262 Appendix A. Open issues 1264 None at the moment 1266 Appendix B. Change log 1268 calext-v09 2018-08-30 MD 1270 o Sorted out inconsistencies in refs to 5546 1272 calext-v08 2018-07-06 MD 1274 o Add some text for equal ORDER values 1276 o Switched scheduleaddress to calendaraddress in participant abnf. 1277 Also added more properties 1279 o Fixed PARTICIPANT abnf 1281 calext-v04 2017-10-11 MD 1283 o Change SCHEDULE-ADDRESS to CALENDAR-ADDRESS 1285 o Explicitly broaden scope of SOURCE 1287 o Add initial registry for RESTYPE and move new tables into separate 1288 section. 1290 o Fix PARTTYPE/PARTICPANT-TYPE inconsistency 1292 calext-v03 2017-10-09 MD 1294 o Mostly typographical and other minor changes 1296 calext-v02 2017-04-20 MD 1298 o Add SCHEDULE-ADDRESS property 1300 o PARTICIPANT becomes a component rather than a property. Turn many 1301 of the former parameters into properties. 1303 o Use existing ATTENDEE property for scheduling. 1305 calext-v01 2017-02-18 MD 1307 o Change ASSOCIATE back to PARTICIPANT 1308 o PARTICIPANT becomes a component rather than a property. Turn many 1309 of the former parameters into properties. 1311 calext-v00 2016-08-?? MD 1313 o Name changed - taken up by calext working group 1315 v06 2016-06-26 MD 1317 o Fix up abnf 1319 o change ref to ietf from daboo 1321 o take out label spec - use Cyrus spec 1323 v05 2016-06-14 MD 1325 o Remove GROUP and HASH. they can be dealt with elsewhere if desired 1327 o Change ORDER to integer >= 1. 1329 o Incorporate Structured-Data into this specification. 1331 v04 2014-02-01 MD 1333 o Added updates attribute. 1335 o Minor typos. 1337 o Resubmitted mostly to refresh the draft. 1339 v03 2013-03-06 MD 1341 o Replace PARTICIPANT with ASSOCIATE plus related changes. 1343 o Added section showing modifications to components. 1345 o Replace ID with GROUP and modify HASH. 1347 o Replace TITLE param with LABEL. 1349 o Fixed STYLED-DESCRIPTION in various ways, correct example. 1351 v02 2012-11-02 MD 1353 o Collapse sections with description of properties and the use cases 1354 into a section with sub-sections. 1356 o New section to describe relating properties. 1358 o Remove idref and upgrade hash to have the reference 1360 o No default value types on properties.. 1362 v01 2012-10-18 MD Many changes. 1364 o SPONSOR and STRUCTURED-CONTACT are now in PARTICIPANT 1366 o Add a STRUCTURED-RESOURCE property 1368 o STYLED-DESCRIPTION to handle rich text 1370 o Much more... 1372 2011-01-07 1374 o Remove MEDIA - it's going in the Cyrus RFC 1376 o Rename EXTENDED-... to STRUCTURED-... 1378 o Add TYPE parameter to SPONSOR 1380 v00 2007-10-19 MD Initial version 1382 Author's Address 1384 Michael Douglass 1385 Spherical Cow Group 1386 226 3rd Street 1387 Troy, NY 12180 1388 USA 1390 Email: mdouglass@sphericalcowgroup.com 1391 URI: http://sphericalcowgroup.com