idnits 2.17.1 draft-ietf-calext-eventpub-extensions-04.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 10, 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 10, 2017 5 Intended status: Standards Track 6 Expires: April 13, 2018 8 Event Publishing Extensions to iCalendar 9 draft-ietf-calext-eventpub-extensions-04 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 13, 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 . . . . . . . . . . . . . . . . . . . . . 5 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. New Properties . . . . . . . . . . . . . . . . . . . . . . . 10 69 6.1. Participant Type . . . . . . . . . . . . . . . . . . . . 10 70 6.2. Schedule Address . . . . . . . . . . . . . . . . . . . . 10 71 6.3. Styled-Description . . . . . . . . . . . . . . . . . . . 11 72 6.4. Structured-Location . . . . . . . . . . . . . . . . . . . 12 73 6.5. Structured-Resource . . . . . . . . . . . . . . . . . . . 14 74 6.6. Source . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 6.7. Structured-Data . . . . . . . . . . . . . . . . . . . . . 18 76 7. New Components . . . . . . . . . . . . . . . . . . . . . . . 20 77 7.1. Participant . . . . . . . . . . . . . . . . . . . . . . . 20 78 7.2. Schedulable Participant . . . . . . . . . . . . . . . . . 22 79 8. Participant Types . . . . . . . . . . . . . . . . . . . . . . 22 80 9. Extended examples . . . . . . . . . . . . . . . . . . . . . . 23 81 9.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . . 23 82 9.2. Example 2 . . . . . . . . . . . . . . . . . . . . . . . . 24 83 10. Security Considerations . . . . . . . . . . . . . . . . . . . 25 84 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . 25 85 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 86 12.1. Property Registrations . . . . . . . . . . . . . . . . . 25 87 12.2. Parameter Registrations . . . . . . . . . . . . . . . . 26 88 12.3. Component Registrations . . . . . . . . . . . . . . . . 26 89 12.4. Participant Types Registry . . . . . . . . . . . . . . . 26 90 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 27 91 14. Normative References . . . . . . . . . . . . . . . . . . . . 27 92 Appendix A. Open issues . . . . . . . . . . . . . . . . . . . . 28 93 Appendix B. Change log . . . . . . . . . . . . . . . . . . . . . 28 94 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 96 1. Introduction 98 The currently existing iCalendar standard [RFC5545] lacks useful 99 methods for referencing additional, external information relating to 100 calendar components. Additionally there is no standard way to 101 provide rich text descriptions or meta-data associated with the 102 event. 104 Current practice is to embed this information as links in the 105 description or to add x-properties. 107 This document defines a number of properties and a component 108 referencing such external information that can provide additional 109 information about an iCalendar component. The intent is to allow 110 interchange of such information between applications or systems 111 (e.g., between clients, between client and server, and between 112 servers). Formats such as VCARD are likely to be most useful to the 113 receivers of such events as they may be used in other applications - 114 such as address books. 116 The following properties are defined in this specification 118 STYLED-DESCRIPTION: Supports HTML descriptions. Event publishers 119 typically wish to provide more and better formatted information 120 about the event. 122 STRUCTURED-LOCATION: There may be a number of locations associated 123 with an event. This provides detailed information about the 124 location. 126 STRUCTURED-RESOURCE: Events need resources such as rooms, 127 projectors, conferencing capabilities. 129 STRUCTURED-DATA: The existing properties in iCalendar cover key 130 elements of events and tasks such as start time, end time, 131 location, summary, etc. However, different types of events often 132 have other specific "fields" that it is useful to include in the 133 calendar data. For example, an event representing an airline 134 flight could include the airline, flight number, departure and 135 arrival airport codes, check-in and gate-closing times etc. As 136 another example, a sporting event might contain information about 137 the type of sport, the home and away teams, the league the teams 138 are in, information about nearby parking, etc. 140 In addition this specification defines a new PARTICIPANT component. 141 Many people or groups may participate in an event. This component 142 provides detailed information. Such participants may act as 143 attendees to the event (or derived events) or may just provide a 144 reference - perhaps for mailing lists. 146 1.1. Conventions Used in This Document 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 150 "OPTIONAL" in this document are to be interpreted as described in 151 [RFC2119]. 153 2. Components and properties 155 Previous extensions to the calendaring standards have been largely 156 restricted to the addition of properties or parameters. This is 157 partly because iCalendar libraries had trouble handling components 158 nested deeper than those defined in [RFC5545] 160 In a break with this 'tradition' this specification introduces one of 161 these extensions as a component rather than a property. This is a 162 better match for the way XML and JSON handles such structures and 163 allows richer definitions. 165 It also allows for the addition of extra properties inside the 166 component and resolves some of the problems of trying to add detailed 167 information as a parameter. 169 3. Typed References 171 The properties defined here can all reference external meta-data 172 which may be used by applications to provide enhanced value to users. 173 By providing type information as parameters, clients and servers are 174 able to discover interesting references and make use of them, perhaps 175 for indexing or the presentation of additional related information 176 for the user. 178 The [RFC5545] LOCATION property provides only an unstructured single 179 text value for specifying the location where an event (or task) will 180 occur. This is inadequate for use cases where structured location 181 information (e.g. address, region, country, postal code) is required 182 or preferred, and limits widespread adoption of iCalendar in those 183 settings. 185 Using STRUCTURED-LOCATION, information about a number of interesting 186 locations can be communicated, for example, parking, restaurants and 187 the venue. Servers and clients can retrieve the objects when storing 188 the event and use them to index by geographic location. 190 When a calendar client receives a calendar component it can search 191 the set of supplied properties looking for those of particular 192 interest. The TYPE and FMTTYPE parameters, if supplied, can be used 193 to help the selection. 195 The PARTICIPANT component is designed to handle common use cases in 196 event publication. It is generally important to provide information 197 about the organizers of such events. Sponsors wish to be referenced 198 in a prominent manner. In social calendaring it is often important 199 to identify the active participants in the event, for example a 200 school sports team, and the inactive participants, for example the 201 parents. 203 The PARTICIPANT component canalso be used to provide useful extra 204 daat about an attendee. For example a LOCATION property inside the 205 PARTICIPANT gives the actual location of a remote attendee. 207 3.1. Use Cases 209 The main motivation for these properties has been event publication 210 but there are opportunities for use elsewhere. The following use 211 cases will describe some possible scenarios. 213 3.1.1. Piano Concert Performance 215 In putting together a concert there are many participants: piano 216 tuner, performer, stage hands etc. In addition there are sponsors 217 and various contacts to be provided. There will also be a number of 218 related locations. A number of events can be created, all of which 219 relate to the performance in different ways. 221 There may be an iTip [RFC5546] meeting request for the piano tuner 222 who will arrive before the performance. Other members of staff may 223 also receive meeting requests. 225 An event can also be created for publication which will have a 226 PARTICIPANT component for the pianist providing a reference to vcard 227 information about the performer. This event would also hold 228 information about parking, local subway stations and the venue 229 itself. In addition, there will be sponsorship information for 230 sponsors of the event and perhaps paid sponsorship properties 231 essentially advertising local establishments. 233 3.1.2. Itineraries 235 These additions also provide opportunities for the travel industry. 236 When booking a flight the PARTICIPANT component can be used to 237 provide references to businesses at the airports and to car hire 238 businesses at the destination. 240 The embedded location information can guide the traveller at the 241 airport or to their final destination. The contact information can 242 provide detailed information about the booking agent, the airlines 243 and car hire companies and the hotel. 245 4. Modifications to Calendar Components 247 The following changes to the syntax defined in iCalendar [RFC5545] 248 are made here. New elements are defined in subsequent sections. 250 eventc = "BEGIN" ":" "VEVENT" CRLF 251 eventprop *alarmc *participantc 252 "END" ":" "VEVENT" CRLF 254 eventprop =/ *( 255 ; 256 ; The following are OPTIONAL, 257 ; and MAY occur more than once. 258 ; 259 styleddescription / strucloc / strucres / sdataprop 260 ; 261 ) 263 todoc = "BEGIN" ":" "VTODO" CRLF 264 todoprop *alarmc *participantc 265 "END" ":" "VTODO" CRLF 267 todoprop =/ *( 268 ; 269 ; The following are OPTIONAL, 270 ; and MAY occur more than once. 271 ; 272 styleddescription / strucloc / strucres / sdataprop 273 ; 274 ) 276 journalc = "BEGIN" ":" "VJOURNAL" CRLF 277 jourprop *participantc 278 "END" ":" "VJOURNAL" CRLF 280 jourprop =/ *( 281 ; 282 ; The following are OPTIONAL, 283 ; and MAY occur more than once. 284 ; 285 styleddescription / sdataprop 286 ; 287 ) 289 5. New Property Parameters 291 This specification makes use of the LABEL property parameter which is 292 defined in [RFC7986] 294 5.1. Loctype 296 Parameter name: LOCTYPE 298 Purpose: To specify the type of location. 300 Format Definition: 302 This parameter is defined by the following notation: 304 loctypeparam = "LOCTYPE" "=" param-value 306 Description: This parameter MAY be specified on STRUCTURED-LOCATION 307 and provides a way to differentiate multiple properties. For 308 example, it allows event producers to provide location information 309 for the venue and the parking. 311 Values for this parameter are taken from the values defined in 312 [RFC4589]. New location types SHOULD be registered in the manner 313 laid down in that specification 315 5.2. Restype 317 Parameter name: RESTYPE 319 Purpose: To specify the type of resource. 321 Format Definition: 323 This parameter is defined by the following notation: 325 restypeparam = "RESTYPE" "=" param-value 327 Description: This parameter MAY be specified on STRUCTURED-RESOURCE 328 and provides a way to differentiate multiple properties. 330 Values for this parameter are taken from the values defined in the 331 registry. New resource types SHOULD be registered in the manner 332 laid down in this specification 334 5.3. Order 336 Parameter name: ORDER 338 Purpose: To define ordering for the associated property. 340 Format Definition: 342 This parameter is defined by the following notation: 344 orderparam = "ORDER" "=" integer ;Must be greater than or equal to 1 346 Description: The ORDER parameter is OPTIONAL and is used to indicate 347 the relative ordering of the corresponding instance of a property. 348 Its value MUST be an integer greater than or equal to 1 that 349 quantifies the order with 1 being the first in the ordering. 351 When the parameter is absent, the default MUST be to interpret the 352 property instance as being at the lowest level of ordering, that 353 is, the property will appear after any other instances of the same 354 property with any value of ORDER. 356 Note that the value of this parameter is to be interpreted only in 357 relation to values assigned to other corresponding instances of 358 the same property in the same entity. A given value, or the 359 absence of a value, MUST NOT be interpreted on its own. 361 This parameter MAY be applied to any property that allows multiple 362 instances. 364 5.4. Schema 366 Parameter Name: SCHEMA 368 Purpose: To specify the schema used for the content of a 369 "STRUCTURED-DATA" property value. 371 Format Definition: 373 This parameter is defined by the following notation: 375 schemaparam = "SCHEMA" "=" DQUOTE uri DQUOTE 377 Description: This property parameter SHOULD be specified on 378 "STRUCTURED-DATA" properties. When present it provides 379 identifying information about the nature of the content of the 380 corresponding "STRUCTURED-DATA" property value. This can be used 381 to supplement the media type information provided by the "FMTTYPE" 382 parameter on the corresponding property. 384 Example: 386 STRUCTURED-DATA;FMTTYPE=application/ld+json; 387 SCHEMA="https://schema.org/FlightReservation"; 388 ENCODING=BASE64;VALUE=BINARY:Zm9vYmFy 390 6. New Properties 392 6.1. Participant Type 394 Property name: PARTICIPANT-TYPE 396 Purpose: To specify the type of participant. 398 Value type: The value type for this property is TEXT. The allowable 399 values are defined in Section 8. 401 Property Parameters: Non-standard parameters can be specified on 402 this property. 404 Conformance: This property MUST be specified within a PARTICIPANT 405 component. 407 Description: This property defines the type of participation in 408 events or tasks. Participants can be individuals or 409 organizations, for example a soccer team, the spectators, or the 410 musicians. 412 Format Definition: 414 This parameter is defined by the following notation: 416 participanttype = "PARTICIPANT-TYPE" "=" iana-token 418 6.2. Schedule Address 420 Property name: SCHEDULE-ADDRESS 422 Purpose: To specify the calendar address for a participant. 424 Value type: CAL-ADDRESS 426 Property Parameters: IANA or non-standard property parameters can be 427 specified on this property. 429 Conformance: This property MAY be specified within a PARTICIPANT 430 component. 432 Description: This property provides a calendar user address for the 433 participant. If there is an ATTENDEE property with the same value 434 then the participant is schedulable. 436 Format Definition: 438 This parameter is defined by the following notation: 440 scheduleaddress = "SCHEDULE-ADDRESS" "=" cal-address 442 6.3. Styled-Description 444 Property name: STYLED-DESCRIPTION 446 Purpose: This property provides for one or more rich-text 447 descriptions to replace or augment that provided by the 448 DESCRIPTION property. 450 Value type: There is no default value type for this property. The 451 value type can be set to URI or TEXT. Other text-based value 452 types can be used when defined in the future. Clients MUST ignore 453 any properties with value types they do not understand. 455 Property Parameters: IANA, non-standard, id, alternate text 456 representation, format type, and language property parameters can 457 be specified on this property. 459 Conformance: The property can be specified multiple times in the 460 "VEVENT", "VTODO", "VJOURNAL", or "VALARM" calendar components. 462 Description: This property is used in the "VEVENT" and "VTODO" to 463 capture lengthy textual descriptions associated with the activity. 464 This property is used in the "VJOURNAL" calendar component to 465 capture one or more textual journal entries. This property is 466 used in the "VALARM" calendar component to capture the display 467 text for a DISPLAY category of alarm, and to capture the body text 468 for an EMAIL category of alarm. 470 VALUE=TEXT is used to provide rich-text variants of the plain-text 471 DESCRIPTION property. 473 VALUE=URI is used to provide a link to rich-text content which is 474 expected to be displayed inline as part of the event. 476 The intent of this property is limited to providing a styled and/ 477 or language specific version of the DESCRIPTION property. The URL 478 property should be used to link to websites or other related 479 information. 481 Applications MAY attempt to guess the media type of the resource 482 via inspection of its content if and only if the media type of the 483 resource is not given by the "FMTTYPE" parameter. If the media 484 type remains unknown, calendar applications SHOULD treat it as 485 type "text/html". 487 Multiple STYLED-DESCRIPTION properties may be used to provide 488 different formats or different language variants. 490 Format Definition: 492 This property is defined by the following notation: 494 styleddescription = "STYLED-DESCRIPTION" styleddescparam ":" 495 ( 496 ( 497 ";" "VALUE" "=" "URI" 498 ":" uri 499 ) / 500 ( 501 ";" "VALUE" "=" "TEXT" 502 ":" text 503 ) 504 ) 505 CRLF 507 styleddescparam = *( 508 ; 509 ; The following are OPTIONAL, 510 ; but MUST NOT occur more than once. 511 ; 512 (";" altrepparam) / (";" languageparam) / 513 (";" fmttypeparam) / 514 ; 515 ; the following is OPTIONAL 516 ; and MAY occur more than once 517 ; 518 (";" other-param) 519 ) 521 Example: 523 The following is an example of this property. It points to an html 524 description. 526 STYLED-DESCRIPTION;VALUE=URI:http://example.org/desc001.html 528 6.4. Structured-Location 530 Property name: STRUCTURED-LOCATION 531 Purpose: This property provides a typed reference to external 532 information about the location of an event or optionally a plain 533 text typed value. 535 Value type: There is no default value type for this property. The 536 value type can be set to URI or TEXT. 538 Property Parameters: IANA, non-standard, label, loctype or format 539 type parameters can be specified on this property. 541 Conformance: This property MAY be specified zero or more times in 542 any iCalendar component. 544 Description: When used in a component the value of this property 545 provides information about the event venue or of related services 546 such as parking, dining, stations etc.. 548 When a LABEL parameter is supplied the language of the label must 549 match that of the content and of the LANGUAGE parameter if 550 present. 552 Format Definition: 554 This property is defined by the following notation: 556 strucloc = "STRUCTURED-LOCATION" struclocparam 557 ( 558 ( 559 ";" "VALUE" "=" "URI" 560 ":" uri 561 ) / 562 ( 563 ";" "VALUE" "=" "TEXT" 564 ":" text 565 ) 566 ) 567 CRLF 569 struclocparam = *( 570 ; 571 ; the following are OPTIONAL 572 ; but MUST NOT occur more than once 573 ; 574 (";" fmttypeparam) / 575 (";" labelparam) / 576 (";" languageparam) / 577 (";" loctypeparam) / 578 ; 579 ; the following is OPTIONAL 580 ; and MAY occur more than once 581 ; 582 (";" other-param) 583 ) 585 Example: 587 The following is an example of this property. It points to a venue. 589 STRUCTURED-LOCATION;LABEL="The venue": 590 http://dir.example.com/venues/big-hall.vcf 592 6.5. Structured-Resource 594 Property name: STRUCTURED-RESOURCE 596 Purpose: This property provides a typed reference to external 597 information about a resource or optionally a plain text typed 598 value. 600 Value type: There is no default value type for this property. The 601 value type can be set to URI or TEXT. 603 Property Parameters: IANA, non-standard, label, restype or format 604 type parameters can be specified on this property. 606 Conformance: This property MAY be specified zero or more times in 607 any iCalendar component. 609 Description: When used in a component the value of this property 610 provides information about resources used for the event. 612 When a LABEL parameter is supplied the language of the label must 613 match that of the content and of the LANGUAGE parameter if 614 present. 616 Format Definition: 618 This property is defined by the following notation: 620 strucres = "STRUCTURED-RESOURCE" strucresparam / 621 ( 622 ( 623 ";" "VALUE" "=" "URI" 624 ":" uri 625 ) / 626 ( 627 ";" "VALUE" "=" "TEXT" 628 ":" text 629 ) 630 ) 631 CRLF 633 strucresparam = *( 634 ; 635 ; the following are OPTIONAL 636 ; but MUST NOT occur more than once 637 ; 638 (";" fmttypeparam) / 639 (";" labelparam) / 640 (";" languageparam) / 641 (";" restypeparam) / 642 ; 643 ; the following is OPTIONAL 644 ; and MAY occur more than once 645 ; 646 (";" other-param) 647 ) 649 Example: 651 The following is an example of this property. It refers to a 652 projector. 654 STRUCTURED-RESOURCE;restype="projector": 655 http://dir.example.com/projectors/3d.vcf 657 6.6. Source 659 Property name: SOURCE 661 Purpose: This property provides a reference to information about a 662 component such as a participant possibly as a vcard or optionally 663 a plain text typed value. 665 Value type: The default value type for this property is URI. The 666 value type can also be set to TEXT to indicate plain text content. 668 Property Parameters: Non-standard or format type parameters can be 669 specified on this property. 671 Conformance: This property MAY be appear in any iCalendar component. 673 Description: This property provides information about the component 674 in which it appears. It may provide a reference to a vcard giving 675 directory information about a resource or participant. 677 Format Definition: 679 This property is defined by the following notation: 681 source = "SOURCE" sourceparam 682 ( 683 ( 684 ";" "VALUE" "=" "URI" 685 ":" uri 686 ) / 687 ( 688 ";" "VALUE" "=" "TEXT" 689 ":" text 690 ) 691 ) 692 CRLF 694 sourceparam = *( 695 ; 696 ; the following are OPTIONAL 697 ; but MUST NOT occur more than once 698 ; 699 (";" fmttypeparam) / 700 ; 701 ; the following is OPTIONAL 702 ; and MAY occur more than once 703 ; 704 (";" other-param) 705 ; 706 ) 708 Example: 710 The following is an example referring to a VCARD. 712 SOURCE;FMTTYPE=text/vcard; 713 http://dir.example.com/vcard/contacts/contact1.vcf 715 6.7. Structured-Data 717 Property Name: STRUCTURED-DATA 719 Purpose: This property specifies ancillary data associated with the 720 calendar component. 722 Value Type: TEXT, BINARY or URI 724 Property Parameters: IANA, non-standard, inline encoding, and value 725 data type property parameters can be specified on this property. 726 The format type and schema parameters can be specified on this 727 property and are RECOMMENDED for text or inline binary encoded 728 content information. 730 Conformance: This property can be specified multiple times in an 731 iCalendar object. Typically it would be used in "VEVENT", 732 "VTODO", or "VJOURNAL" calendar components. 734 Description: This property is used to specify ancillary data in some 735 structured format either directly (inline) as a "TEXT" or "BINARY" 736 value, or as a link via a "URI" value. 738 Rather than define new iCalendar properties for the variety of 739 event types that might occur, it would be better to leverage 740 existing schemas for such data. For example, schemas available at 741 https://schema.org include different event types. By using 742 standard schemas, interoperability can be improved between 743 calendar clients and non-calendaring systems that wish to generate 744 or process the data. 746 This property allows the direct inclusion of ancillary data whose 747 schema is defined elsewhere. This property also includes 748 parameters to clearly identify the type of the schema being used 749 so that clients can quickly and easily spot what is relevant 750 within the calendar data and present that to users or process it 751 within the calendaring system. 753 iCalendar does support an "ATTACH" property which can be used to 754 include documents or links to documents within the calendar data. 755 However, that property does not allow data to be included as a 756 "TEXT" value (a feature that "STRUCTURED-DATA" does allow), plus 757 attachments are often treated as "opaque" data to be processed by 758 some other system rather than the calendar client. Thus the 759 existing "ATTACH" property is not sufficient to cover the specific 760 needs of inclusion of schema data. Extending the "ATTACH" 761 property to support a new value type would likely cause 762 interoperability problems. Thus a new property to support 763 inclusion of schema data is warranted. 765 Format Definition: 767 This property is defined by the following notation: 769 sdataprop = "STRUCTURED-DATA" sdataparam 770 (":" text) / 771 ( 772 ";" "ENCODING" "=" "BASE64" 773 ";" "VALUE" "=" "BINARY" 774 ":" binary 775 ) / 776 ( 777 ";" "VALUE" "=" "URI" 778 ":" uri 779 ) 780 CRLF 782 sdataparam = *( 783 ; 784 ; The following is OPTIONAL for a URI value, 785 ; RECOMMENDED for a TEXT or BINARY value, 786 ; and MUST NOT occur more than once. 787 ; 788 (";" fmttypeparam) / 789 (";" schemaparam) / 790 ; 791 ; The following is OPTIONAL, 792 ; and MAY occur more than once. 793 ; 794 (";" other-param) 795 ; 796 ) 798 Example: The following is an example of this property: 800 STRUCTURED-DATA;FMTTYPE=application/ld+json; 801 SCHEMA="https://schema.org/SportsEvent"; 802 VALUE=TEXT:{\n 803 "@context": "http://schema.org"\,\n 804 "@type": "SportsEvent"\,\n 805 "homeTeam": "Pittsburgh Pirates"\,\n 806 "awayTeam": "San Francisco Giants"\n 807 }\n 809 7. New Components 811 7.1. Participant 813 Component name: PARTICIPANT 815 Purpose: This component provides information about a participant in 816 an event or optionally a plain text typed value. 818 Conformance: This component MAY be appear in any iCalendar 819 component. 821 Description: This component provides information about an 822 participant in an event, task or poll. A participant may be an 823 attendee in a scheduling sense and the ATTENDEE property may be 824 specified in addition. Participants in events can be individuals 825 or organizations, for example a soccer team, the spectators, or 826 the musicians. 828 The SOURCE property if present may refer to an external definition 829 of the participant - such as a vcard. 831 The STRUCTURED-ADDRESS property if present will provide a cal- 832 address. If an ATTENDEE property has the same value the 833 participant is considered schedulable. The PARTICIPANT component 834 can be used to contain additional meta-data related to the 835 attendee. 837 Format Definition: 839 This property is defined by the following notation: 841 participantc = "BEGIN" ":" "PARTICIPANT" CRLF 842 partprop *alarmc 843 "END" ":" "PARTICIPANT" CRLF 845 partprop = *( 846 ; 847 ; The following are REQUIRED, 848 ; but MUST NOT occur more than once. 849 ; 850 dtstamp / participanttype / 851 ; 852 ; The following are OPTIONAL, 853 ; but MUST NOT occur more than once. 854 ; 855 created / description / last-mod / priority / seq / 856 source / status / scheduleaddress / summary / url / 857 ; 858 ; The following are OPTIONAL, 859 ; and MAY occur more than once. 860 ; 861 attach / categories / comment / 862 contact / rstatus / related / 863 resources / x-prop / iana-prop 864 ; 865 ) 867 Note: When the PRIORITY is supplied it defines the ordering of 868 PARTICIPANT components with the same value for the TYPE parameter. 870 Example: 872 The following is an example of this component. It contains a SOURCE 873 property which points to a VCARD providing information about the 874 event participant. 876 BEGIN:PARTICIPANT 877 PARTTYPE:PRINCIPAL_PERFORMER 878 SOURCE:http://dir.example.com/vcard/aviolinist.vcf 879 END:PARTICIPANT 881 Example: 883 The following is an example for the primary contact. 885 BEGIN: PARTICIPANT 886 SOURCE;FMTTYPE=text/vcard; 887 http://dir.example.com/vcard/contacts/contact1.vcf 888 PARTTYPE:PRIMARY-CONTACT 889 DESCRIPTION:A contact: 890 END:PARTICIPANT 892 7.2. Schedulable Participant 894 A PARTICIPANT component may represent someone or something that needs 895 to be scheduled as defined for ATTENDEE in [RFC5545] and [RFC5546]. 896 The PARTICIPANT component may also represent someone or something 897 that is NOT to receive scheduling messages. 899 A PARTICIPANT component is defined to be schedulable if 901 o It contains a SCHEDULE-ADDRESS property 903 o That property value is the same as the value for an ATTENDEE 904 property. 906 If both of these conditions apply then the participant defined by the 907 value of the URL property will take part in scheduling operations as 908 defined in [RFC5546]. 910 An appropriate use for the PARTICIPANT component in scheduling would 911 be to store SEQUENCE and DTSTAMP properties associated with replies 912 from each ATTENDEE. A LOCATION property within the PARTICIPANT 913 component might allow better selection of meeting times when 914 participants are in different timezones. 916 8. Participant Types 918 This section describes types of participation and provides registered 919 values for the PARTTYPE property. 921 ACTIVE: A participant taking an active role - for example a team 922 member. 924 INACTIVE: A participant taking an inactive part - for example an 925 audience member. 927 SPONSOR: A sponsor of the event. The ORDER parameter may be used 928 with this participant type to define the relative order of 929 multiple sponsors. 931 CONTACT: Contact information for the event. The ORDER parameter may 932 be used with this participant type to define the relative order of 933 multiple contacts. 935 BOOKING-CONTACT: Contact information for reservations or payment 937 EMERGENCY-CONTACT: Contact in case of emergency 939 PUBLICITY-CONTACT: Contact for publicity 941 PLANNER-CONTACT: Contact for the event planner or organizer 943 PERFORMER: A performer - for example the soloist or the accompanist. 944 The ORDER parameter may be used with this participant type to 945 define the relative order of multiple performers. For example, 946 ORDER=1 could define the principal performer or soloist. 948 SPEAKER: Speaker at an event 950 9. Extended examples 952 The following are some examples of the use of the properties defined 953 in this specification. They include additional properties defined in 954 [RFC7986] which includes IMAGE. 956 9.1. Example 1 957 The following is an example of a VEVENT describing a concert. It 958 includes location information for the venue itself as well as 959 references to parking and restaurants. 961 BEGIN:VEVENT 962 CREATED:20170216T145739Z 963 DESCRIPTION: Piano Sonata No 3\n 964 Piano Sonata No 30 965 DTSTAMP:20171116T145739Z 966 DTSTART;TZID=America/New_York:20170315T150000Z 967 DTEND;TZID=America/New_York:20170315T163000Z 968 LAST-MODIFIED:20170216T145739Z 969 SUMMARY:Beethoven Piano Sonatas 970 UID:123456 971 STRUCTURED-LOCATION;LABEL="The venue": 972 http://dir.example.com/venues/big-hall.vcf 973 STRUCTURED-LOCATION;LABEL="The venue": 974 http://dir.example.com/venues/parking.vcf 975 IMAGE;VALUE=URI;DISPLAY=BADGE;FMTTYPE=image/png:h 976 ttp://example.com/images/concert.png 977 BEGIN:PARTICIPANT 978 PARTTYPE:SPONSOR 979 SOURCE:http://example.com/sponsor.vcf 980 END:PARTICIPANT 981 BEGIN:PARTICIPANT 982 PARTTYPE:PERFORMER: 983 SOURCE:http://www.example.com/people/johndoe.vcf 984 END:PARTICIPANT 985 END:VEVENT 987 9.2. Example 2 988 The following is an example of a VEVENT describing a meeting. One of 989 the attendees is a remote participant. 991 BEGIN:VEVENT 992 CREATED:20170216T145739Z 993 DTSTAMP:20101116T145739Z 994 DTSTART;TZID=America/New_York:20170315T150000Z 995 DTEND;TZID=America/New_York:20170315T163000Z 996 LAST-MODIFIED:20170216T145739Z 997 SUMMARY:Conference plaaning 998 UID:123456 999 ORGANIZER:mailto:a@example.com 1000 ATTENDEE;PARTSTAT=ACCEPTED;CN=A:mailto:a@example.com 1001 ATTENDEE;RSVP=TRUE;CN=B:mailto:b@example.com 1002 BEGIN:PARTICIPANT 1003 PARTTYPE:ACTIVE: 1004 SOURCE:http://www.example.com/people/b.vcf 1005 LOCATION:At home 1006 END:PARTICIPANT 1007 END:VEVENT 1009 10. Security Considerations 1011 Applications using these properties need to be aware of the risks 1012 entailed in using the URIs provided as values. See [RFC3986] for a 1013 discussion of the security considerations relating to URIs. 1015 Security considerations relating to the "ATTACH" property, as 1016 described in [RFC5545], are applicable to the "STRUCTURED-DATA" 1017 property. 1019 11. Privacy Considerations 1021 Properties with a "URI" value type can expose their users to privacy 1022 leaks as any network access of the URI data can be tracked. Clients 1023 SHOULD NOT automatically download data referenced by the URI without 1024 explicit instruction from users. This specification does not 1025 introduce any additional privacy concerns beyond those described in 1026 [RFC5545]. 1028 12. IANA Considerations 1030 12.1. Property Registrations 1032 This document defines the following new iCalendar properties to be 1033 added to the registry defined in Section 8.2.3 of [RFC5545]: 1035 +---------------------+---------+----------------------+ 1036 | Property | Status | Reference | 1037 +---------------------+---------+----------------------+ 1038 | PARTTYPE | Current | RFCXXXX, Section 6.1 | 1039 | SCHEDULE-ADDRESS | Current | RFCXXXX, Section 6.2 | 1040 | STRUCTURED-DATA | Current | RFCXXXX, Section 6.7 | 1041 | STYLED-DESCRIPTION | Current | RFCXXXX, Section 6.3 | 1042 | STRUCTURED-LOCATION | Current | RFCXXXX, Section 6.4 | 1043 | STRUCTURED-RESOURCE | Current | RFCXXXX, Section 6.5 | 1044 | SOURCE | Current | RFCXXXX, Section 6.6 | 1045 +---------------------+---------+----------------------+ 1047 12.2. Parameter Registrations 1049 This document defines the following new iCalendar property parameters 1050 to be added to the registry defined in Section 8.2.4 of [RFC5545]: 1052 +--------------------+---------+----------------------+ 1053 | Property Parameter | Status | Reference | 1054 +--------------------+---------+----------------------+ 1055 | LOCTYPE | Current | RFCXXXX, Section 5.1 | 1056 | ORDER | Current | RFCXXXX, Section 5.3 | 1057 | RESTYPE | Current | RFCXXXX, Section 5.2 | 1058 | SCHEMA | Current | RFCXXXX, Section 5.4 | 1059 +--------------------+---------+----------------------+ 1061 12.3. Component Registrations 1063 This document defines the following new iCalendar components to be 1064 added to the registry defined in Section 8.3.1 of [RFC5545]: 1066 +-------------+---------+----------------------+ 1067 | Component | Status | Reference | 1068 +-------------+---------+----------------------+ 1069 | PARTICIPANT | Current | RFCXXXX, Section 7.1 | 1070 +-------------+---------+----------------------+ 1072 12.4. Participant Types Registry 1074 The following table has been used to initialize the participant types 1075 registry. 1077 +-------------------+---------+--------------------+ 1078 | Participant Type | Status | Reference | 1079 +-------------------+---------+--------------------+ 1080 | ACTIVE | Current | RFCXXXX, Section 8 | 1081 | INACTIVE | Current | RFCXXXX, Section 8 | 1082 | SPONSOR | Current | RFCXXXX, Section 8 | 1083 | CONTACT | Current | RFCXXXX, Section 8 | 1084 | BOOKING-CONTACT | Current | RFCXXXX, Section 8 | 1085 | EMERGENCY-CONTACT | Current | RFCXXXX, Section 8 | 1086 | PUBLICITY-CONTACT | Current | RFCXXXX, Section 8 | 1087 | PLANNER-CONTACT | Current | RFCXXXX, Section 8 | 1088 | PERFORMER | Current | RFCXXXX, Section 8 | 1089 | SPEAKER | Current | RFCXXXX, Section 8 | 1090 +-------------------+---------+--------------------+ 1092 13. Acknowledgements 1094 The author would like to thank Chuck Norris of eventful.com for his 1095 work which led to the development of this RFC. 1097 The author would also like to thank the members of CalConnect, The 1098 Calendaring and Scheduling Consortium, the Event Publication 1099 technical committee and the following individuals for contributing 1100 their ideas and support: 1102 Cyrus Daboo, John Haug, Dan Mendell, Ken Murchison, Scott Otis, 1104 14. Normative References 1106 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1107 Requirement Levels", BCP 14, RFC 2119, 1108 DOI 10.17487/RFC2119, March 1997, 1109 . 1111 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1112 Resource Identifier (URI): Generic Syntax", STD 66, 1113 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1114 . 1116 [RFC4589] Schulzrinne, H. and H. Tschofenig, "Location Types 1117 Registry", RFC 4589, DOI 10.17487/RFC4589, July 2006, 1118 . 1120 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 1121 Scheduling Core Object Specification (iCalendar)", 1122 RFC 5545, DOI 10.17487/RFC5545, September 2009, 1123 . 1125 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 1126 Interoperability Protocol (iTIP)", RFC 5546, 1127 DOI 10.17487/RFC5546, December 2009, 1128 . 1130 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 1131 DOI 10.17487/RFC7986, October 2016, 1132 . 1134 [W3C.REC-xml-20060816] 1135 Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1136 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fourth 1137 Edition)", World Wide Web Consortium Recommendation REC- 1138 xml-20060816, August 2006, 1139 . 1141 Appendix A. Open issues 1143 restype values: Need to determine what if any registry of resource 1144 types already exists and use that or define one here. 1146 SOURCE property: Already defined in 7986. Should I recast this as 1147 an extension of that property. Allows VALUE=TEXT and use in other 1148 than a calendar. 1150 Appendix B. Change log 1152 calext-v02 2017-04-20 MD 1154 o Add SCHEDULE-ADDRESS property 1156 o PARTICIPANT becomes a component rather than a property. Turn many 1157 of the former parameters into properties. 1159 o Use existing ATTENDEE property for scheduling. 1161 calext-v01 2017-02-18 MD 1163 o Change ASSOCIATE back to PARTICIPANT 1165 o PARTICIPANT becomes a component rather than a property. Turn many 1166 of the former parameters into properties. 1168 calext-v00 2016-08-?? MD 1170 o Name changed - taken up by calext working group 1172 v06 2016-06-26 MD 1173 o Fix up abnf 1175 o change ref to ietf from daboo 1177 o take out label spec - use Cyrus spec 1179 v05 2016-06-14 MD 1181 o Remove GROUP and HASH. they can be dealt with elsewhere if desired 1183 o Change ORDER to integer >= 1. 1185 o Incorporate Structured-Data into this specification. 1187 v04 2014-02-01 MD 1189 o Added updates attribute. 1191 o Minor typos. 1193 o Resubmitted mostly to refresh the draft. 1195 v03 2013-03-06 MD 1197 o Replace PARTICIPANT with ASSOCIATE plus related changes. 1199 o Added section showing modifications to components. 1201 o Replace ID with GROUP and modify HASH. 1203 o Replace TITLE param with LABEL. 1205 o Fixed STYLED-DESCRIPTION in various ways, correct example. 1207 v02 2012-11-02 MD 1209 o Collapse sections with description of properties and the use cases 1210 into a section with sub-sections. 1212 o New section to describe relating properties. 1214 o Remove idref and upgrade hash to have the reference 1216 o No default value types on properties.. 1218 v01 2012-10-18 MD Many changes. 1220 o SPONSOR and STRUCTURED-CONTACT are now in PARTICIPANT 1221 o Add a STRUCTURED-RESOURCE property 1223 o STYLED-DESCRIPTION to handle rich text 1225 o Much more... 1227 2011-01-07 1229 o Remove MEDIA - it's going in the Cyrus RFC 1231 o Rename EXTENDED-... to STRUCTURED-... 1233 o Add TYPE parameter to SPONSOR 1235 v00 2007-10-19 MD Initial version 1237 Author's Address 1239 Michael Douglass 1240 Spherical Cow Group 1241 226 3rd Street 1242 Troy, NY 12180 1243 USA 1245 Email: mdouglass@sphericalcowgroup.com 1246 URI: http://sphericalcowgroup.com