Schema Display Formats -- Options

We have a good deal of PIM schema info available, and more will be coming soon. We need to figure out how best to present that info to make it useful to everybody who needs to see it.

We've experimented with a variety of different formats for presenting schema information. Here are some examples, all of which describe the "Calendar Event" and its attributes.

Send me mail if you have opinions about what sort of format we should standardize on as we start to have more and more PIM schema to publish: skinner@osafoundation.org.

We're planning to have an XSL that will read our XML schema files and generate HTML documentation. Let me know if you have suggestions or feature requests about how that documentation should look.

Examples

• "Calendar Event" in Plain Text
• "Calendar Event" in Schema XML
• "Calendar Event" in a diagram
• "Calendar Event" as an HTML table <-- Be patient after clicking. After it loads it should scroll to the right place, but it takes awhile.
• "Calendar Event" attributes presented as part of a polymorphism discussion

Plain Text

CalendarEvent
  owning calendar -> a Calendar item
  summary -> a String
  description -> a list of Strings
  categories -> a list of Strings
  startTime -> a Datetime
  endTime -> a Datetime
  organizer -> a list of (Contacts, Groups, People, Organizations)
  attendees -> a list of Invitations, or
               a list of (Contacts, Groups, People, Organizations)
  resources -> a list of Resource items
  location -> a list of Places (or Strings)
  recurrence -> a RecurrencePattern item
  reminder -> a list of Reminder items
  transparency -> ??? maybe a public/private flag?
  free/busy -> true/false
  eventGenre -> 'Holiday'/'Meeting'/'Birthday'/'Phone Call', etc.

Schema XML

  <Kind id="cal:CalendarEvent">
    <displayName>Calendar Event</displayName>
    <example>'Lunch with Tug'</example>
    <description>
      A Calendar Event represents an entry on a calendar.
    </description>
    <superKind itemref="cal:InformationItem"/>
    <attribute itemref="cal:summary"/>
    <attribute itemref="cal:comment"/>
    <attribute itemref="cal:categories"/>
    <attribute itemref="cal:startTime"/>
    <attribute itemref="cal:endTime"/>
    <attribute itemref="cal:organizer"/>
    <attribute itemref="cal:attendees"/>
    <attribute itemref="cal:location"/>
    <attribute itemref="cal:recurrence"/>
    <attribute itemref="cal:reminder"/>
    <attribute itemref="cal:transparency"/>
  </Kind>

  <AttributeDefinition id="cal:summary">
    <displayName>summary</displayName>
    <description>example: 'Lunch with Tug'. Similar to the ical 
      property 'Summary'</description>
    <cardinality>single</cardinality>
    <type itemref="core:String"/>
  </AttributeDefinition>

  <AttributeDefinition id="cal:comment">
    <displayName>comment</displayName>
    <description>Similar to the ical property 'Description'</description>
    <cardinality>list</cardinality>
    <type itemref="core:String"/>
  </AttributeDefinition>

  <AttributeDefinition id="cal:categories">
    <displayName>categories</displayName>
    <description>Similar to the ical property 'Categories'</description>
    <cardinality>list</cardinality>
    <type itemref="core:String"/>
  </AttributeDefinition>

  <AttributeDefinition id="cal:startTime">
    <displayName>start time</displayName>
    <description>When does this Calendar Event start?</description>
    <cardinality>single</cardinality>
    <required/>
    <type itemref="core:DateTime"/>
  </AttributeDefinition>

  <AttributeDefinition id="cal:endTime">
    <displayName>end time</displayName>
    <description>When does this Calendar Event end?</description>
    <cardinality>single</cardinality>
    <required/>
    <type itemref="core:DateTime"/>
  </AttributeDefinition>

  <AttributeDefinition id="cal:organizer">
    <displayName>organizer</displayName>
    <description>Similar to the ical property 'Organizer' -- has importance for iTIP. 
      (@@@ -- 'Type' should be something that can have values which could be any of a 
      variety of types: people, organizations, or groups)</description>
    <cardinality>list</cardinality>
    <type itemref="core:Contact"/>
    <inverseAttribute itemref="cal:@@@"/>
  </AttributeDefinition>

  <AttributeDefinition id="cal:attendees">
    <displayName>attendees</displayName>
    <description>Similar to the ical property 'Attendee'. Alternatively, we could 
      do something interesting here, perhaps have two attributes with 'attribute  
      inheritance', or have two attributes that are both sub-attributes of some 
      common super-attribute: participant, invitee.  In this case, 'organizer' 
      would also be a 'participant.  (@@@ -- 'Type' should really be something 
      that can have values which could be any of a variety of types: people, 
      organizations, groups, resources or maybe even just simple strings.)
    </description>
    <cardinality>list</cardinality>
    <type itemref="core:Contact"/>
    <inverseAttribute itemref="cal:@@@ -- attending?"/>
  </AttributeDefinition>

  <AttributeDefinition id="cal:location">
    <displayName>location</displayName>
    <description>Similar to the ical property 'Location'. (@@@ -- 'Type' should 
      really be something that can have values which could be either Places 
      or just simple strings.)</description>
    <cardinality>list</cardinality>
    <type itemref="core:Place"/>
    <inverseAttribute itemref="cal:@@@"/>
    <deletePolicy>strong reference</deletePolicy>
  </AttributeDefinition>

  <AttributeDefinition id="cal:recurrence">
    <displayName>recurrence</displayName>
    <description>Similar to the ical property 'Recurrence'.</description>
    <cardinality>list</cardinality>
    <type itemref="core:RecurrencePattern"/>
    <inverseAttribute itemref="cal:@@@"/>
    <deletePolicy>strong reference</deletePolicy>
  </AttributeDefinition>

  <AttributeDefinition id="cal:reminder">
    <displayName>reminder</displayName>
    <description>Similar to the ical property 'Reminder'.</description>
    <cardinality>list</cardinality>
    <type itemref="core:Reminder"/>
    <inverseAttribute itemref="cal:@@@"/>
    <deletePolicy>strong reference</deletePolicy>
  </AttributeDefinition>

  <AttributeDefinition id="cal:transparency">
    <displayName>transparency</displayName>
    <description>Similar to the ical property 'Transparency'.  (@@@ -- Transparency  
      Enum should have instances for 'free', 'busy', etc.  Actually, we might do 
      this differently, and have a reference to a FreeBusyItem.</description>
    <cardinality>single</cardinality>
    <type itemref="core:@@@ -- type?"/>
  </AttributeDefinition>

Contributors

• BrianDouglasSkinner - 23 Oct 2003