idnits 2.17.1 draft-ietf-calext-eventpub-extensions-05.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 (October 11, 2017) is 2383 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) October 11, 2017 5 Intended status: Standards Track 6 Expires: April 14, 2018 8 Event Publishing Extensions to iCalendar 9 draft-ietf-calext-eventpub-extensions-05 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 April 14, 2018. 38 Copyright Notice 40 Copyright (c) 2017 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 4. Modifications to Calendar Components . . . . . . . . . . . . 6 63 5. New Property Parameters . . . . . . . . . . . . . . . . . . . 7 64 5.1. Loctype . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 5.2. Restype . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 5.3. Order . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 5.4. Schema . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 6. Redefined Property SOURCE . . . . . . . . . . . . . . . . . . 10 69 7. New Properties . . . . . . . . . . . . . . . . . . . . . . . 11 70 7.1. Participant Type . . . . . . . . . . . . . . . . . . . . 11 71 7.2. Calendar Address . . . . . . . . . . . . . . . . . . . . 12 72 7.3. Styled-Description . . . . . . . . . . . . . . . . . . . 12 73 7.4. Structured-Location . . . . . . . . . . . . . . . . . . . 14 74 7.5. Structured-Resource . . . . . . . . . . . . . . . . . . . 16 75 7.6. Structured-Data . . . . . . . . . . . . . . . . . . . . . 17 76 8. New Components . . . . . . . . . . . . . . . . . . . . . . . 19 77 8.1. Participant . . . . . . . . . . . . . . . . . . . . . . . 20 78 8.2. Schedulable Participant . . . . . . . . . . . . . . . . . 22 79 9. Participant Types . . . . . . . . . . . . . . . . . . . . . . 22 80 10. Resource Types . . . . . . . . . . . . . . . . . . . . . . . 23 81 11. Extended examples . . . . . . . . . . . . . . . . . . . . . . 23 82 11.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . 24 83 11.2. Example 2 . . . . . . . . . . . . . . . . . . . . . . . 24 84 12. Security Considerations . . . . . . . . . . . . . . . . . . . 25 85 13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 25 86 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 87 14.1. Additional iCalendar Registrations . . . . . . . . . . . 26 88 14.1.1. Property Registrations . . . . . . . . . . . . . . . 26 89 14.1.2. Parameter Registrations . . . . . . . . . . . . . . 26 90 14.1.3. Component Registrations . . . . . . . . . . . . . . 26 91 14.2. New Registration Tables . . . . . . . . . . . . . . . . 27 92 14.2.1. Participant Types Registry . . . . . . . . . . . . . 27 93 14.2.2. Resource Types Registry . . . . . . . . . . . . . . 27 94 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 95 16. Normative References . . . . . . . . . . . . . . . . . . . . 28 96 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 28 97 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 29 98 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31 100 1. Introduction 102 The currently existing iCalendar standard [RFC5545] lacks useful 103 methods for referencing additional, external information relating to 104 calendar components. Additionally there is no standard way to 105 provide rich text descriptions or meta-data associated with the 106 event. 108 Current practice is to embed this information as links in the 109 description or to add x-properties. 111 This document defines a number of properties and a component 112 referencing such external information that can provide additional 113 information about an iCalendar component. The intent is to allow 114 interchange of such information between applications or systems 115 (e.g., between clients, between client and server, and between 116 servers). Formats such as VCARD are likely to be most useful to the 117 receivers of such events as they may be used in other applications - 118 such as address books. 120 This specification defines a new PARTICIPANT component. Many people 121 or groups may participate in an event. This component provides 122 detailed information. Such participants may act as attendees to the 123 event (or derived events) or may just provide a reference - perhaps 124 for mailing lists. 126 The following properties are defined in this specification 128 STYLED-DESCRIPTION: Supports HTML descriptions. Event publishers 129 typically wish to provide more and better formatted information 130 about the event. 132 STRUCTURED-LOCATION: There may be a number of locations associated 133 with an event. This provides detailed information about the 134 location. 136 STRUCTURED-RESOURCE: Events need resources such as rooms, 137 projectors, conferencing capabilities. 139 STRUCTURED-DATA: The existing properties in iCalendar cover key 140 elements of events and tasks such as start time, end time, 141 location, summary, etc. However, different types of events often 142 have other specific "fields" that it is useful to include in the 143 calendar data. For example, an event representing an airline 144 flight could include the airline, flight number, departure and 145 arrival airport codes, check-in and gate-closing times etc. As 146 another example, a sporting event might contain information about 147 the type of sport, the home and away teams, the league the teams 148 are in, information about nearby parking, etc. 150 PARTICIPANT-TYPE: Used in the PARTICIPANT component to define the 151 type. 153 CALENDAR-ADDRESS: Used in the PARTICIPANT component to provide the 154 calendar address of the participant. 156 In addition the SOURCE property defined in [RFC7986] is redefined to 157 allow VALUE=TEXT and broaden its usage. 159 1.1. Conventions Used in This Document 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 163 "OPTIONAL" in this document are to be interpreted as described in 164 [RFC2119]. 166 2. Components and properties 168 Previous extensions to the calendaring standards have been largely 169 restricted to the addition of properties or parameters. This is 170 partly because iCalendar libraries had trouble handling components 171 nested deeper than those defined in [RFC5545] 173 In a break with this 'tradition' this specification introduces one of 174 these extensions as a component rather than a property. This is a 175 better match for the way XML and JSON handles such structures and 176 allows richer definitions. 178 It also allows for the addition of extra properties inside the 179 component and resolves some of the problems of trying to add detailed 180 information as a parameter. 182 3. Typed References 184 The properties defined here can all reference external meta-data 185 which may be used by applications to provide enhanced value to users. 186 By providing type information as parameters, clients and servers are 187 able to discover interesting references and make use of them, perhaps 188 for indexing or the presentation of additional related information 189 for the user. 191 The [RFC5545] LOCATION property provides only an unstructured single 192 text value for specifying the location where an event (or task) will 193 occur. This is inadequate for use cases where structured location 194 information (e.g. address, region, country, postal code) is required 195 or preferred, and limits widespread adoption of iCalendar in those 196 settings. 198 Using STRUCTURED-LOCATION, information about a number of interesting 199 locations can be communicated, for example, parking, restaurants and 200 the venue. Servers and clients can retrieve the objects when storing 201 the event and use them to index by geographic location. 203 When a calendar client receives a calendar component it can search 204 the set of supplied properties looking for those of particular 205 interest. The TYPE and FMTTYPE parameters, if supplied, can be used 206 to help the selection. 208 The PARTICIPANT component is designed to handle common use cases in 209 event publication. It is generally important to provide information 210 about the organizers of such events. Sponsors wish to be referenced 211 in a prominent manner. In social calendaring it is often important 212 to identify the active participants in the event, for example a 213 school sports team, and the inactive participants, for example the 214 parents. 216 The PARTICIPANT component canalso be used to provide useful extra 217 daat about an attendee. For example a LOCATION property inside the 218 PARTICIPANT gives the actual location of a remote attendee. 220 3.1. Use Cases 222 The main motivation for these properties has been event publication 223 but there are opportunities for use elsewhere. The following use 224 cases will describe some possible scenarios. 226 3.1.1. Piano Concert Performance 228 In putting together a concert there are many participants: piano 229 tuner, performer, stage hands etc. In addition there are sponsors 230 and various contacts to be provided. There will also be a number of 231 related locations. A number of events can be created, all of which 232 relate to the performance in different ways. 234 There may be an iTip [RFC5546] meeting request for the piano tuner 235 who will arrive before the performance. Other members of staff may 236 also receive meeting requests. 238 An event can also be created for publication which will have a 239 PARTICIPANT component for the pianist providing a reference to vcard 240 information about the performer. This event would also hold 241 information about parking, local subway stations and the venue 242 itself. In addition, there will be sponsorship information for 243 sponsors of the event and perhaps paid sponsorship properties 244 essentially advertising local establishments. 246 3.1.2. Itineraries 248 These additions also provide opportunities for the travel industry. 249 When booking a flight the PARTICIPANT component can be used to 250 provide references to businesses at the airports and to car hire 251 businesses at the destination. 253 The embedded location information can guide the traveller at the 254 airport or to their final destination. The contact information can 255 provide detailed information about the booking agent, the airlines 256 and car hire companies and the hotel. 258 4. Modifications to Calendar Components 260 The following changes to the syntax defined in iCalendar [RFC5545] 261 are made here. New elements are defined in subsequent sections. 263 eventc = "BEGIN" ":" "VEVENT" CRLF 264 eventprop *alarmc *participantc 265 "END" ":" "VEVENT" CRLF 267 eventprop =/ *( 268 ; 269 ; The following are OPTIONAL, 270 ; and MAY occur more than once. 271 ; 272 styleddescription / strucloc / strucres / sdataprop 273 ; 274 ) 276 todoc = "BEGIN" ":" "VTODO" CRLF 277 todoprop *alarmc *participantc 278 "END" ":" "VTODO" CRLF 280 todoprop =/ *( 281 ; 282 ; The following are OPTIONAL, 283 ; and MAY occur more than once. 284 ; 285 styleddescription / strucloc / strucres / sdataprop 286 ; 287 ) 289 journalc = "BEGIN" ":" "VJOURNAL" CRLF 290 jourprop *participantc 291 "END" ":" "VJOURNAL" CRLF 293 jourprop =/ *( 294 ; 295 ; The following are OPTIONAL, 296 ; and MAY occur more than once. 297 ; 298 styleddescription / sdataprop 299 ; 300 ) 302 5. New Property Parameters 304 This specification makes use of the LABEL property parameter which is 305 defined in [RFC7986] 307 5.1. Loctype 309 Parameter name: LOCTYPE 311 Purpose: To specify the type of location. 313 Format Definition: 315 This parameter is defined by the following notation: 317 loctypeparam = "LOCTYPE" "=" param-value 319 Description: This parameter MAY be specified on STRUCTURED-LOCATION 320 and provides a way to differentiate multiple properties. For 321 example, it allows event producers to provide location information 322 for the venue and the parking. 324 Values for this parameter are taken from the values defined in 325 [RFC4589]. New location types SHOULD be registered in the manner 326 laid down in that specification 328 5.2. Restype 330 Parameter name: RESTYPE 332 Purpose: To specify the type of resource. 334 Format Definition: 336 This parameter is defined by the following notation: 338 restypeparam = "RESTYPE" "=" param-value 340 Description: This parameter MAY be specified on STRUCTURED-RESOURCE 341 and provides a way to differentiate multiple properties. 343 The allowable values are defined in Section 10 New resource types 344 SHOULD be registered in the manner laid down in this specification 346 5.3. Order 348 Parameter name: ORDER 350 Purpose: To define ordering for the associated property. 352 Format Definition: 354 This parameter is defined by the following notation: 356 orderparam = "ORDER" "=" integer ;Must be greater than or equal to 1 358 Description: The ORDER parameter is OPTIONAL and is used to indicate 359 the relative ordering of the corresponding instance of a property. 360 Its value MUST be an integer greater than or equal to 1 that 361 quantifies the order with 1 being the first in the ordering. 363 When the parameter is absent, the default MUST be to interpret the 364 property instance as being at the lowest level of ordering, that 365 is, the property will appear after any other instances of the same 366 property with any value of ORDER. 368 Note that the value of this parameter is to be interpreted only in 369 relation to values assigned to other corresponding instances of 370 the same property in the same entity. A given value, or the 371 absence of a value, MUST NOT be interpreted on its own. 373 This parameter MAY be applied to any property that allows multiple 374 instances. 376 5.4. Schema 378 Parameter Name: SCHEMA 380 Purpose: To specify the schema used for the content of a 381 "STRUCTURED-DATA" property value. 383 Format Definition: 385 This parameter is defined by the following notation: 387 schemaparam = "SCHEMA" "=" DQUOTE uri DQUOTE 389 Description: This property parameter SHOULD be specified on 390 "STRUCTURED-DATA" properties. When present it provides 391 identifying information about the nature of the content of the 392 corresponding "STRUCTURED-DATA" property value. This can be used 393 to supplement the media type information provided by the "FMTTYPE" 394 parameter on the corresponding property. 396 Example: 398 STRUCTURED-DATA;FMTTYPE=application/ld+json; 399 SCHEMA="https://schema.org/FlightReservation"; 400 ENCODING=BASE64;VALUE=BINARY:Zm9vYmFy 402 6. Redefined Property SOURCE 404 The SOURCE property defined in [RFC7986] is redefined to allow 405 VALUE=TEXT and broaden its usage to any component. 407 Property name: SOURCE 409 Purpose: This property provides a reference to information about a 410 component such as a participant possibly as a vcard or optionally 411 a plain text typed value. 413 Value type: The default value type for this property is URI. The 414 value type can also be set to TEXT to indicate plain text content. 416 Property Parameters: Non-standard or format type parameters can be 417 specified on this property. 419 Conformance: This property MAY be appear in any iCalendar component. 421 Description: This property provides information about the component 422 in which it appears. 424 In a resource or participant it may provide a reference to a vcard 425 giving directory information. 427 In a VCALENDAR component this property identifies a location where 428 a client can retrieve updated data for the calendar. Clients 429 SHOULD honor any specified "REFRESH-INTERVAL" value when 430 periodically retrieving data. Note that this property differs 431 from the "URL" property in that "URL" is meant to provide an 432 alternative representation of the calendar data rather than the 433 original location of the data. 435 In a calendar entity component such as an event the SOURCE 436 property may provide a reference to the original source of the 437 event. This may be used by aggregators to provide a link back. 439 Format Definition: 441 This property is defined by the following notation: 443 source = "SOURCE" sourceparam 444 ( 445 ( 446 ";" "VALUE" "=" "URI" 447 ":" uri 448 ) / 449 ( 450 ";" "VALUE" "=" "TEXT" 451 ":" text 452 ) 453 ) 454 CRLF 456 sourceparam = *( 457 ; 458 ; the following are OPTIONAL 459 ; but MUST NOT occur more than once 460 ; 461 (";" fmttypeparam) / 462 ; 463 ; the following is OPTIONAL 464 ; and MAY occur more than once 465 ; 466 (";" other-param) 467 ; 468 ) 470 Example: 472 The following is an example referring to a VCARD. 474 SOURCE;FMTTYPE=text/vcard;VALUE=URL: 475 http://dir.example.com/vcard/contacts/contact1.vcf 477 7. New Properties 479 7.1. Participant Type 481 Property name: PARTICIPANT-TYPE 483 Purpose: To specify the type of participant. 485 Value type: The value type for this property is TEXT. The allowable 486 values are defined in Section 9. 488 Property Parameters: Non-standard parameters can be specified on 489 this property. 491 Conformance: This property MUST be specified within a PARTICIPANT 492 component. 494 Description: This property defines the type of participation in 495 events or tasks. Participants can be individuals or 496 organizations, for example a soccer team, the spectators, or the 497 musicians. 499 Format Definition: 501 This parameter is defined by the following notation: 503 participanttype = "PARTICIPANT-TYPE" "=" iana-token 505 7.2. Calendar Address 507 Property name: CALENDAR-ADDRESS 509 Purpose: To specify the calendar address for a participant. 511 Value type: CAL-ADDRESS 513 Property Parameters: IANA or non-standard property parameters can be 514 specified on this property. 516 Conformance: This property MAY be specified within a PARTICIPANT 517 component. 519 Description: This property provides a calendar user address for the 520 participant. If there is an ATTENDEE property with the same value 521 then the participant is schedulable. 523 Format Definition: 525 This parameter is defined by the following notation: 527 calendaraddress = "CALENDAR-ADDRESS" "=" cal-address 529 7.3. Styled-Description 531 Property name: STYLED-DESCRIPTION 533 Purpose: This property provides for one or more rich-text 534 descriptions to replace or augment that provided by the 535 DESCRIPTION property. 537 Value type: There is no default value type for this property. The 538 value type can be set to URI or TEXT. Other text-based value 539 types can be used when defined in the future. Clients MUST ignore 540 any properties with value types they do not understand. 542 Property Parameters: IANA, non-standard, id, alternate text 543 representation, format type, and language property parameters can 544 be specified on this property. 546 Conformance: The property can be specified multiple times in the 547 "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar components. 549 Description: This property is used in the "VEVENT" and "VTODO" to 550 capture lengthy textual descriptions associated with the activity. 551 This property is used in the "VJOURNAL" calendar component to 552 capture one or more textual journal entries. This property is 553 used in the "VALARM" calendar component to capture the display 554 text for a DISPLAY category of alarm, and to capture the body text 555 for an EMAIL category of alarm. 557 VALUE=TEXT is used to provide rich-text variants of the plain-text 558 DESCRIPTION property. 560 VALUE=URI is used to provide a link to rich-text content which is 561 expected to be displayed inline as part of the event. 563 The intent of this property is limited to providing a styled and/ 564 or language specific version of the DESCRIPTION property. The URL 565 property should be used to link to websites or other related 566 information. 568 Applications MAY attempt to guess the media type of the resource 569 via inspection of its content if and only if the media type of the 570 resource is not given by the "FMTTYPE" parameter. If the media 571 type remains unknown, calendar applications SHOULD treat it as 572 type "text/html". 574 Multiple STYLED-DESCRIPTION properties may be used to provide 575 different formats or different language variants. 577 Format Definition: 579 This property is defined by the following notation: 581 styleddescription = "STYLED-DESCRIPTION" styleddescparam ":" 582 ( 583 ( 584 ";" "VALUE" "=" "URI" 585 ":" uri 586 ) / 587 ( 588 ";" "VALUE" "=" "TEXT" 589 ":" text 590 ) 591 ) 592 CRLF 594 styleddescparam = *( 595 ; 596 ; The following are OPTIONAL, 597 ; but MUST NOT occur more than once. 598 ; 599 (";" altrepparam) / (";" languageparam) / 600 (";" fmttypeparam) / 601 ; 602 ; the following is OPTIONAL 603 ; and MAY occur more than once 604 ; 605 (";" other-param) 606 ) 608 Example: 610 The following is an example of this property. It points to an html 611 description. 613 STYLED-DESCRIPTION;VALUE=URI:http://example.org/desc001.html 615 7.4. Structured-Location 617 Property name: STRUCTURED-LOCATION 619 Purpose: This property provides a typed reference to external 620 information about the location of an event or optionally a plain 621 text typed value. 623 Value type: There is no default value type for this property. The 624 value type can be set to URI or TEXT. 626 Property Parameters: IANA, non-standard, label, loctype or format 627 type parameters can be specified on this property. 629 Conformance: This property MAY be specified zero or more times in 630 any iCalendar component. 632 Description: When used in a component the value of this property 633 provides information about the event venue or of related services 634 such as parking, dining, stations etc.. 636 When a LABEL parameter is supplied the language of the label must 637 match that of the content and of the LANGUAGE parameter if 638 present. 640 Format Definition: 642 This property is defined by the following notation: 644 strucloc = "STRUCTURED-LOCATION" struclocparam 645 ( 646 ( 647 ";" "VALUE" "=" "URI" 648 ":" uri 649 ) / 650 ( 651 ";" "VALUE" "=" "TEXT" 652 ":" text 653 ) 654 ) 655 CRLF 657 struclocparam = *( 658 ; 659 ; the following are OPTIONAL 660 ; but MUST NOT occur more than once 661 ; 662 (";" fmttypeparam) / 663 (";" labelparam) / 664 (";" languageparam) / 665 (";" loctypeparam) / 666 ; 667 ; the following is OPTIONAL 668 ; and MAY occur more than once 669 ; 670 (";" other-param) 671 ) 673 Example: 675 The following is an example of this property. It points to a venue. 677 STRUCTURED-LOCATION;LABEL="The venue": 678 http://dir.example.com/venues/big-hall.vcf 680 7.5. Structured-Resource 682 Property name: STRUCTURED-RESOURCE 684 Purpose: This property provides a typed reference to external 685 information about a resource or optionally a plain text typed 686 value. 688 Value type: There is no default value type for this property. The 689 value type can be set to URI or TEXT. 691 Property Parameters: IANA, non-standard, label, restype or format 692 type parameters can be specified on this property. 694 Conformance: This property MAY be specified zero or more times in 695 any iCalendar component. 697 Description: When used in a component the value of this property 698 provides information about resources used for the event. 700 When a LABEL parameter is supplied the language of the label must 701 match that of the content and of the LANGUAGE parameter if 702 present. 704 Format Definition: 706 This property is defined by the following notation: 708 strucres = "STRUCTURED-RESOURCE" strucresparam / 709 ( 710 ( 711 ";" "VALUE" "=" "URI" 712 ":" uri 713 ) / 714 ( 715 ";" "VALUE" "=" "TEXT" 716 ":" text 717 ) 718 ) 719 CRLF 721 strucresparam = *( 722 ; 723 ; the following are OPTIONAL 724 ; but MUST NOT occur more than once 725 ; 726 (";" fmttypeparam) / 727 (";" labelparam) / 728 (";" languageparam) / 729 (";" restypeparam) / 730 ; 731 ; the following is OPTIONAL 732 ; and MAY occur more than once 733 ; 734 (";" other-param) 735 ) 737 Example: 739 The following is an example of this property. It refers to a 740 projector. 742 STRUCTURED-RESOURCE;restype="projector": 743 http://dir.example.com/projectors/3d.vcf 745 7.6. Structured-Data 747 Property Name: STRUCTURED-DATA 749 Purpose: This property specifies ancillary data associated with the 750 calendar component. 752 Value Type: TEXT, BINARY or URI 753 Property Parameters: IANA, non-standard, inline encoding, and value 754 data type property parameters can be specified on this property. 755 The format type and schema parameters can be specified on this 756 property and are RECOMMENDED for text or inline binary encoded 757 content information. 759 Conformance: This property can be specified multiple times in an 760 iCalendar object. Typically it would be used in "VEVENT", 761 "VTODO", or "VJOURNAL" calendar components. 763 Description: This property is used to specify ancillary data in some 764 structured format either directly (inline) as a "TEXT" or "BINARY" 765 value, or as a link via a "URI" value. 767 Rather than define new iCalendar properties for the variety of 768 event types that might occur, it would be better to leverage 769 existing schemas for such data. For example, schemas available at 770 https://schema.org include different event types. By using 771 standard schemas, interoperability can be improved between 772 calendar clients and non-calendaring systems that wish to generate 773 or process the data. 775 This property allows the direct inclusion of ancillary data whose 776 schema is defined elsewhere. This property also includes 777 parameters to clearly identify the type of the schema being used 778 so that clients can quickly and easily spot what is relevant 779 within the calendar data and present that to users or process it 780 within the calendaring system. 782 iCalendar does support an "ATTACH" property which can be used to 783 include documents or links to documents within the calendar data. 784 However, that property does not allow data to be included as a 785 "TEXT" value (a feature that "STRUCTURED-DATA" does allow), plus 786 attachments are often treated as "opaque" data to be processed by 787 some other system rather than the calendar client. Thus the 788 existing "ATTACH" property is not sufficient to cover the specific 789 needs of inclusion of schema data. Extending the "ATTACH" 790 property to support a new value type would likely cause 791 interoperability problems. Thus a new property to support 792 inclusion of schema data is warranted. 794 Format Definition: 796 This property is defined by the following notation: 798 sdataprop = "STRUCTURED-DATA" sdataparam 799 (":" text) / 800 ( 801 ";" "ENCODING" "=" "BASE64" 802 ";" "VALUE" "=" "BINARY" 803 ":" binary 804 ) / 805 ( 806 ";" "VALUE" "=" "URI" 807 ":" uri 808 ) 809 CRLF 811 sdataparam = *( 812 ; 813 ; The following is OPTIONAL for a URI value, 814 ; RECOMMENDED for a TEXT or BINARY value, 815 ; and MUST NOT occur more than once. 816 ; 817 (";" fmttypeparam) / 818 (";" schemaparam) / 819 ; 820 ; The following is OPTIONAL, 821 ; and MAY occur more than once. 822 ; 823 (";" other-param) 824 ; 825 ) 827 Example: The following is an example of this property: 829 STRUCTURED-DATA;FMTTYPE=application/ld+json; 830 SCHEMA="https://schema.org/SportsEvent"; 831 VALUE=TEXT:{\n 832 "@context": "http://schema.org"\,\n 833 "@type": "SportsEvent"\,\n 834 "homeTeam": "Pittsburgh Pirates"\,\n 835 "awayTeam": "San Francisco Giants"\n 836 }\n 838 8. New Components 839 8.1. Participant 841 Component name: PARTICIPANT 843 Purpose: This component provides information about a participant in 844 an event or optionally a plain text typed value. 846 Conformance: This component MAY be appear in any iCalendar 847 component. 849 Description: This component provides information about an 850 participant in an event, task or poll. A participant may be an 851 attendee in a scheduling sense and the ATTENDEE property may be 852 specified in addition. Participants in events can be individuals 853 or organizations, for example a soccer team, the spectators, or 854 the musicians. 856 The SOURCE property if present may refer to an external definition 857 of the participant - such as a vcard. 859 The STRUCTURED-ADDRESS property if present will provide a cal- 860 address. If an ATTENDEE property has the same value the 861 participant is considered schedulable. The PARTICIPANT component 862 can be used to contain additional meta-data related to the 863 attendee. 865 Format Definition: 867 This property is defined by the following notation: 869 participantc = "BEGIN" ":" "PARTICIPANT" CRLF 870 partprop *alarmc 871 "END" ":" "PARTICIPANT" CRLF 873 partprop = *( 874 ; 875 ; The following are REQUIRED, 876 ; but MUST NOT occur more than once. 877 ; 878 dtstamp / participanttype / 879 ; 880 ; The following are OPTIONAL, 881 ; but MUST NOT occur more than once. 882 ; 883 created / description / last-mod / priority / seq / 884 source / status / scheduleaddress / summary / url / 885 ; 886 ; The following are OPTIONAL, 887 ; and MAY occur more than once. 888 ; 889 attach / categories / comment / 890 contact / rstatus / related / 891 resources / x-prop / iana-prop 892 ; 893 ) 895 Note: When the PRIORITY is supplied it defines the ordering of 896 PARTICIPANT components with the same value for the TYPE parameter. 898 Example: 900 The following is an example of this component. It contains a SOURCE 901 property which points to a VCARD providing information about the 902 event participant. 904 BEGIN:PARTICIPANT 905 PARTICIPANT-TYPE:PRINCIPAL_PERFORMER 906 SOURCE:http://dir.example.com/vcard/aviolinist.vcf 907 END:PARTICIPANT 909 Example: 911 The following is an example for the primary contact. 913 BEGIN: PARTICIPANT 914 SOURCE;FMTTYPE=text/vcard; 915 http://dir.example.com/vcard/contacts/contact1.vcf 916 PARTICIPANT-TYPE:PRIMARY-CONTACT 917 DESCRIPTION:A contact: 918 END:PARTICIPANT 920 8.2. Schedulable Participant 922 A PARTICIPANT component may represent someone or something that needs 923 to be scheduled as defined for ATTENDEE in [RFC5545] and [RFC5546]. 924 The PARTICIPANT component may also represent someone or something 925 that is NOT to receive scheduling messages. 927 A PARTICIPANT component is defined to be schedulable if 929 o It contains a CALENDAR-ADDRESS property 931 o That property value is the same as the value for an ATTENDEE 932 property. 934 If both of these conditions apply then the participant defined by the 935 value of the URL property will take part in scheduling operations as 936 defined in [RFC5546]. 938 An appropriate use for the PARTICIPANT component in scheduling would 939 be to store SEQUENCE and DTSTAMP properties associated with replies 940 from each ATTENDEE. A LOCATION property within the PARTICIPANT 941 component might allow better selection of meeting times when 942 participants are in different timezones. 944 9. Participant Types 946 This section describes types of participation and provides registered 947 values for the PARTICIPANT-TYPE property. 949 ACTIVE: A participant taking an active role - for example a team 950 member. 952 INACTIVE: A participant taking an inactive part - for example an 953 audience member. 955 SPONSOR: A sponsor of the event. The ORDER parameter may be used 956 with this participant type to define the relative order of 957 multiple sponsors. 959 CONTACT: Contact information for the event. The ORDER parameter may 960 be used with this participant type to define the relative order of 961 multiple contacts. 963 BOOKING-CONTACT: Contact information for reservations or payment 965 EMERGENCY-CONTACT: Contact in case of emergency 967 PUBLICITY-CONTACT: Contact for publicity 969 PLANNER-CONTACT: Contact for the event planner or organizer 971 PERFORMER: A performer - for example the soloist or the accompanist. 972 The ORDER parameter may be used with this participant type to 973 define the relative order of multiple performers. For example, 974 ORDER=1 could define the principal performer or soloist. 976 SPEAKER: Speaker at an event 978 10. Resource Types 980 This section describes some initial resource types registered values 981 for the RESTYPE parameter. Typically a resource is anything that 982 might be required or used by a calendar entity and possibly has a 983 directory entry. 985 Such resources may be a room or a projector. This registry provides 986 a place in which such resources may be registered for use by 987 scheduling sevices. 989 ROOM: A room for he event/meeting. 991 PROJECTOR: Projection equipment. 993 REMOTE-CONFERENCE-AUDIO: Audio remote conferencing facilities. 995 REMOTE-CONFERENCE-VIDEO: Video remote conferencing facilities. 997 11. Extended examples 999 The following are some examples of the use of the properties defined 1000 in this specification. They include additional properties defined in 1001 [RFC7986] which includes IMAGE. 1003 11.1. Example 1 1005 The following is an example of a VEVENT describing a concert. It 1006 includes location information for the venue itself as well as 1007 references to parking and restaurants. 1009 BEGIN:VEVENT 1010 CREATED:20170216T145739Z 1011 DESCRIPTION: Piano Sonata No 3\n 1012 Piano Sonata No 30 1013 DTSTAMP:20171116T145739Z 1014 DTSTART;TZID=America/New_York:20170315T150000Z 1015 DTEND;TZID=America/New_York:20170315T163000Z 1016 LAST-MODIFIED:20170216T145739Z 1017 SUMMARY:Beethoven Piano Sonatas 1018 UID:123456 1019 STRUCTURED-LOCATION;LABEL="The venue": 1020 http://dir.example.com/venues/big-hall.vcf 1021 STRUCTURED-LOCATION;LABEL="The venue": 1022 http://dir.example.com/venues/parking.vcf 1023 IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:h 1024 ttp://example.com/images/concert.png 1025 BEGIN:PARTICIPANT 1026 PARTICIPANT-TYPE:SPONSOR 1027 SOURCE:http://example.com/sponsor.vcf 1028 END:PARTICIPANT 1029 BEGIN:PARTICIPANT 1030 PARTICIPANT-TYPE:PERFORMER: 1031 SOURCE:http://www.example.com/people/johndoe.vcf 1032 END:PARTICIPANT 1033 END:VEVENT 1035 11.2. Example 2 1036 The following is an example of a VEVENT describing a meeting. One of 1037 the attendees is a remote participant. 1039 BEGIN:VEVENT 1040 CREATED:20170216T145739Z 1041 DTSTAMP:20101116T145739Z 1042 DTSTART;TZID=America/New_York:20170315T150000Z 1043 DTEND;TZID=America/New_York:20170315T163000Z 1044 LAST-MODIFIED:20170216T145739Z 1045 SUMMARY:Conference plaaning 1046 UID:123456 1047 ORGANIZER:mailto:a@example.com 1048 ATTENDEE;PARTSTAT=ACCEPTED;CN=A:mailto:a@example.com 1049 ATTENDEE;RSVP=TRUE;CN=B:mailto:b@example.com 1050 BEGIN:PARTICIPANT 1051 PARTICIPANT-TYPE:ACTIVE: 1052 SOURCE:http://www.example.com/people/b.vcf 1053 LOCATION:At home 1054 END:PARTICIPANT 1055 END:VEVENT 1057 12. Security Considerations 1059 Applications using these properties need to be aware of the risks 1060 entailed in using the URIs provided as values. See [RFC3986] for a 1061 discussion of the security considerations relating to URIs. 1063 Security considerations relating to the "ATTACH" property, as 1064 described in [RFC5545], are applicable to the "STRUCTURED-DATA" 1065 property. 1067 13. Privacy Considerations 1069 Properties with a "URI" value type can expose their users to privacy 1070 leaks as any network access of the URI data can be tracked. Clients 1071 SHOULD NOT automatically download data referenced by the URI without 1072 explicit instruction from users. This specification does not 1073 introduce any additional privacy concerns beyond those described in 1074 [RFC5545]. 1076 14. IANA Considerations 1078 This section defines updates to the tables defined in [RFC5545] and 1079 new tables. 1081 14.1. Additional iCalendar Registrations 1083 14.1.1. Property Registrations 1085 This document defines the following new iCalendar properties to be 1086 added to the registry defined in Section 8.2.3 of [RFC5545]: 1088 +---------------------+---------+----------------------+ 1089 | Property | Status | Reference | 1090 +---------------------+---------+----------------------+ 1091 | CALENDAR-ADDRESS | Current | RFCXXXX, Section 7.2 | 1092 | PARTICIPANT-TYPE | Current | RFCXXXX, Section 7.1 | 1093 | SOURCE | Current | RFCXXXX, Section 6 | 1094 | STRUCTURED-DATA | Current | RFCXXXX, Section 7.6 | 1095 | STYLED-DESCRIPTION | Current | RFCXXXX, Section 7.3 | 1096 | STRUCTURED-LOCATION | Current | RFCXXXX, Section 7.4 | 1097 | STRUCTURED-RESOURCE | Current | RFCXXXX, Section 7.5 | 1098 +---------------------+---------+----------------------+ 1100 14.1.2. Parameter Registrations 1102 This document defines the following new iCalendar property parameters 1103 to be added to the registry defined in Section 8.2.4 of [RFC5545]: 1105 +--------------------+---------+----------------------+ 1106 | Property Parameter | Status | Reference | 1107 +--------------------+---------+----------------------+ 1108 | LOCTYPE | Current | RFCXXXX, Section 5.1 | 1109 | ORDER | Current | RFCXXXX, Section 5.3 | 1110 | RESTYPE | Current | RFCXXXX, Section 5.2 | 1111 | SCHEMA | Current | RFCXXXX, Section 5.4 | 1112 +--------------------+---------+----------------------+ 1114 14.1.3. Component Registrations 1116 This document defines the following new iCalendar components to be 1117 added to the registry defined in Section 8.3.1 of [RFC5545]: 1119 +-------------+---------+----------------------+ 1120 | Component | Status | Reference | 1121 +-------------+---------+----------------------+ 1122 | PARTICIPANT | Current | RFCXXXX, Section 8.1 | 1123 +-------------+---------+----------------------+ 1125 14.2. New Registration Tables 1127 This section defines new registration tables for PARTICIPANT-TYPE and 1128 RESTYPE values. These tables maybe updated using the same approaches 1129 laid down in Section 8.2.1 of [RFC5545] 1131 14.2.1. Participant Types Registry 1133 The following table has been used to initialize the participant types 1134 registry. 1136 +-------------------+---------+--------------------+ 1137 | Participant Type | Status | Reference | 1138 +-------------------+---------+--------------------+ 1139 | ACTIVE | Current | RFCXXXX, Section 9 | 1140 | INACTIVE | Current | RFCXXXX, Section 9 | 1141 | SPONSOR | Current | RFCXXXX, Section 9 | 1142 | CONTACT | Current | RFCXXXX, Section 9 | 1143 | BOOKING-CONTACT | Current | RFCXXXX, Section 9 | 1144 | EMERGENCY-CONTACT | Current | RFCXXXX, Section 9 | 1145 | PUBLICITY-CONTACT | Current | RFCXXXX, Section 9 | 1146 | PLANNER-CONTACT | Current | RFCXXXX, Section 9 | 1147 | PERFORMER | Current | RFCXXXX, Section 9 | 1148 | SPEAKER | Current | RFCXXXX, Section 9 | 1149 +-------------------+---------+--------------------+ 1151 14.2.2. Resource Types Registry 1153 The following table has been used to initialize the resource types 1154 registry. 1156 +-------------------------+---------+---------------------+ 1157 | Resource Type | Status | Reference | 1158 +-------------------------+---------+---------------------+ 1159 | PROJECTOR | Current | RFCXXXX, Section 10 | 1160 | ROOM | Current | RFCXXXX, Section 10 | 1161 | REMOTE-CONFERENCE-AUDIO | Current | RFCXXXX, Section 10 | 1162 | REMOTE-CONFERENCE-VIDEO | Current | RFCXXXX, Section 10 | 1163 +-------------------------+---------+---------------------+ 1165 15. Acknowledgements 1167 The author would like to thank Chuck Norris of eventful.com for his 1168 work which led to the development of this RFC. 1170 The author would also like to thank the members of CalConnect, The 1171 Calendaring and Scheduling Consortium, the Event Publication 1172 technical committee and the following individuals for contributing 1173 their ideas and support: 1175 Cyrus Daboo, John Haug, Dan Mendell, Ken Murchison, Scott Otis, 1177 16. Normative References 1179 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1180 Requirement Levels", BCP 14, RFC 2119, 1181 DOI 10.17487/RFC2119, March 1997, 1182 . 1184 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1185 Resource Identifier (URI): Generic Syntax", STD 66, 1186 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1187 . 1189 [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types 1190 Registry", RFC 4589, DOI 10.17487/RFC4589, July 2006, 1191 . 1193 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1194 Scheduling Core Object Specification (iCalendar)", 1195 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1196 . 1198 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1199 Interoperability Protocol (iTIP)", RFC 5546, 1200 DOI 10.17487/RFC5546, December 2009, 1201 . 1203 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 1204 DOI 10.17487/RFC7986, October 2016, 1205 . 1207 [W3C.REC-xml-20060816] 1208 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1209 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth 1210 Edition)", World Wide Web Consortium Recommendation REC- 1211 xml-20060816, August 2006, 1212 . 1214 Appendix A. Open issues 1216 None at the moment 1218 Appendix B. Change log 1220 calext-v04 2017-10-11 MD 1222 o Change SCHEDULE-ADDRESS to CALENDAR-ADDRESS 1224 o Explicitly broaden scope of SOURCE 1226 o Add initial registry for RESTYPE and move new tables into separate 1227 section. 1229 o Fix PARTTYPE/PARTICPANT-TYPE inconsistency 1231 calext-v03 2017-10-09 MD 1233 o Mostly typographical and other minor changes 1235 calext-v02 2017-04-20 MD 1237 o Add SCHEDULE-ADDRESS property 1239 o PARTICIPANT becomes a component rather than a property. Turn many 1240 of the former parameters into properties. 1242 o Use existing ATTENDEE property for scheduling. 1244 calext-v01 2017-02-18 MD 1246 o Change ASSOCIATE back to PARTICIPANT 1248 o PARTICIPANT becomes a component rather than a property. Turn many 1249 of the former parameters into properties. 1251 calext-v00 2016-08-?? MD 1253 o Name changed - taken up by calext working group 1255 v06 2016-06-26 MD 1257 o Fix up abnf 1259 o change ref to ietf from daboo 1261 o take out label spec - use Cyrus spec 1263 v05 2016-06-14 MD 1265 o Remove GROUP and HASH. they can be dealt with elsewhere if desired 1266 o Change ORDER to integer >= 1. 1268 o Incorporate Structured-Data into this specification. 1270 v04 2014-02-01 MD 1272 o Added updates attribute. 1274 o Minor typos. 1276 o Resubmitted mostly to refresh the draft. 1278 v03 2013-03-06 MD 1280 o Replace PARTICIPANT with ASSOCIATE plus related changes. 1282 o Added section showing modifications to components. 1284 o Replace ID with GROUP and modify HASH. 1286 o Replace TITLE param with LABEL. 1288 o Fixed STYLED-DESCRIPTION in various ways, correct example. 1290 v02 2012-11-02 MD 1292 o Collapse sections with description of properties and the use cases 1293 into a section with sub-sections. 1295 o New section to describe relating properties. 1297 o Remove idref and upgrade hash to have the reference 1299 o No default value types on properties.. 1301 v01 2012-10-18 MD Many changes. 1303 o SPONSOR and STRUCTURED-CONTACT are now in PARTICIPANT 1305 o Add a STRUCTURED-RESOURCE property 1307 o STYLED-DESCRIPTION to handle rich text 1309 o Much more... 1311 2011-01-07 1313 o Remove MEDIA - it's going in the Cyrus RFC 1314 o Rename EXTENDED-... to STRUCTURED-... 1316 o Add TYPE parameter to SPONSOR 1318 v00 2007-10-19 MD Initial version 1320 Author's Address 1322 Michael Douglass 1323 Spherical Cow Group 1324 226 3rd Street 1325 Troy, NY 12180 1326 USA 1328 Email: mdouglass@sphericalcowgroup.com 1329 URI: http://sphericalcowgroup.com