XML Format for Chandler's Data Model Schemas

Warning: we are making some terminology changes to bring this format into sync with the repository and the data model work. We recently checked in some terminology changes.

Goals

• Capture chandler data model in one canonical source, checked into CVS
• Use this format directly for loading schema items into the repository.
• Transform to RDF
• Generate documentation about data model

Example

<DomainSchema itemName="book:BookSchema" root="Books"
              xmlns="http://osafoundation.org/2003/08/CoreSchema"
              xmlns:core="http://osafoundation.org/2003/08/CoreSchema"
              xmlns:util="http://osafoundation.org/2003/08/UtilitySchema"
              xmlns:people="http://osafoundation.org/2003/08/PeopleSchema"
              xmlns:book="http://osafoundation.org/2003/08/BookSchema"
              xml:base="http://osafoundation.org/2003/08/BookSchema">

  <displayName>Book Schema</displayName>
  <description>Kinds, Attributes, and Items for a book parcel.</description>

  <!-- @@@ may be temporary, once we figure out parcel loading -->
  <!--     right now, handy for parser or xslt transform -->
  <itemPathMapping prefix="book" path="BookSchema"/>
  <itemPathMapping prefix="people" path="PeopleSchema"/>
  <itemPathMapping prefix="core" path="CoreSchema"/>
  <itemPathMapping prefix="util" path="UtilSchema"/>

  <version>0.2</version>
  <dependsOn itemref="people:PeopleSchema"/>
  <dependsOn itemref="core:CoreSchema"/>
  <dependsOn itemref="util:UtilitySchema"/>

  <Attribute itemName="book:isbn">
    <displayName>ISBN</displayName>
    <cardinality>single</cardinality>
    <type itemref="String"/>
    <description>The ISBN number associated with a book</description>
    <required/>
  </Attribute>

  <Attribute itemName="book:title">
    <displayName>Book Title</displayName>
    <cardinality>single</cardinality>
    <type itemref="String"/>
    <description>The title of a book.</description>
    <required/>
  </Attribute>

  <Attribute itemName="book:author">
    <displayName>Book Author</displayName>
    <cardinality>single</cardinality>
    <type itemref="book:Author"/>
    <description>The author of a book.</description>
    <inverseAttribute itemref="book:authored"/>
  </Attribute>

  <Attribute itemName="book:authored">
    <displayName>Authored</displayName>
    <cardinality>list</cardinality>
    <type itemref="book:Book"/>
    <description>Books a given person has authored.</description>
    <inverseAttribute itemref="book:author"/>
  </Attribute>

  <Kind itemName="book:Book">
    <displayName>Book</displayName>
    <description>A kind representing a book</description>
    <attributes itemref="book:isbn"/>
    <attributes itemref="book:title"/>
    <attributes itemref="book:author"/>
  </Kind>

  <Kind itemName="book:Author">
    <displayName>Book Author</displayName>
    <description>A kind representing the author of a book.</description>
    <superKinds itemref="people:Person"/>
    <attributes itemref="book:authored"/>
    <displayAttribute itemref="people:name"/>
  </Kind>

  <Alias itemName="book:LibraryInfo">
    <displayName>Library Information</displayName>
    <description>An alias for any book related item.</description>
    <aliasFor itemref="book:Book"/>
    <aliasFor itemref="book:Author"/>
  </Alias>

  <book:Author itemName="book:YM">
    <people:name>Yann Martel</people:name>
  </book:Author>

  <book:Book itemName="book:LP">
    <book:title>Life of Pi</book:title>
    <book:author itemref="YM"/>
    <book:isbn>0-15-602732-1</book:isbn>
  </book:Book>

</DomainSchema>

Elements

• <DomainSchema>: The root element for the document, the schema being defined.
  • itemName xml attribute: Uniquely identifies this schema. Not the UUID. Used to define the URI for this Item, also used in the repository containment path.
  • <displayName>: String that can be used as a display name for this Schema.
  • <description>: Description of this item, for documentation.
  • <examples>: Example for this item, for documentation.
  • <issues>: Open issue related to this item, for documentation.
  • <itemPathMapping>: Defines the mapping between a namespace prefix and the containment path of the data parcel, used to generate itemrefs. Yes, we should be able to derive this somehow, and not need to list the paths. Useful for practical reasons in the short term, may go away.
    • prefix xml attribute: The namespace prefix used for this containment path. The prefix is used by itemrefs.
    • path xml attribute: The containment path.
  • <version>: Capture version information about the schema. Semantics are still fuzzy, a placeholder.
  • <dependsOn>: Include a tag for every schema this schema depends on.
    • itemref xml attribute: gives a URI to reference the DomainSchema

• <Kind>: Top level element, will generate a Kind item in the repository.
  • itemName xml attribute: Uniquely identifies this Item among all other Kinds, Types and Aliases in this schema. Not the UUID. Used to define the URI for this Item, also used in the repository containment path.
  • <displayName>: String that can be used as a display name for this Kind.
  • <description>: Description of this item, for documentation.
  • <examples>: Example for this item, for documentation.
  • <issues>: Open issue related to this item, for documentation.
  • <superKinds>: Optional empty element if this Kind has a superKind. A Kind may have multiple superKinds.
    • itemref xml attribute: gives a URI to reference the superKind.
  • <attributes>: One empty element for each implied attribute on this Kind.
    • itemref xml attribute: gives a URI to reference the Attribute.
  • <displayAttribute>: Optional empty element if a particular Attribute is to be used as the display value for an instance.
    • itemref xml attribute: gives a URI to reference the Attribute.
  • <equivalentKinds>: Include an empty tag for each equivalent Kind.
    • itemref xml attribute: gives a URI to reference the Kind
  • <hidden>: Optional empty element if this Kind is hidden.
  • <abstract>: Optional empty element if this Kind is abstract.
  • <classes>: One element for each class mapping associated with this kind. The element contains the class name.
    • key xml attribute: the name of the mapping. Currently, only 'python' is supported.

• <Attribute>: Top level element, will generate an Attribute item in the repository. The Attribute will be globally accessible.
  • itemName xml attribute: Uniquely identifies this Item among all other Attributes. Not the UUID. Used to define the URI for this Item, also used in the repository containment path.
  • <displayName>: String that can be used as a display name for this Attribute.
  • <description>: Description of this item, for documentation.
  • <examples>: Example for this item, for documentation.
  • <issues>: Open issue related to this item, for documentation.
  • <type>: One empty element for the Type, Kind or Alias allowed for values of this Attribute.
    • itemref xml attribute: gives a URI to reference the Type, Kind or Alias
  • <cardinality>: Gives the cardinality of the attribute, one of these:
    • single: only one value
    • list: ordered collection
    • dict: mapping collection, by default uuid is used as the key -- only available for attributes that hold literals, not item references
  • <superAttribute>: Optional empty element if this attribute has a superAttribute.
    • itemref xml attribute: gives a URI to reference the superAttribute.
  • <defaultValue>: Optional default value for this Attribute.
  • <required>: Include an empty tag if this is a required attribute.
  • <inheritFrom>: Optional empty element if this attribute will inherit a value from another attribute.
    • itemref xml attribute: gives a URI to reference the attribute whose value will be inherited.
  • <derivationNotes>: Element contains notes about attribute derivation, a future feature that isn't yet worked out.
  • <hidden>: Include an empty tag if this is a hidden attribute.
  • <equivalentAttributes>: Include an empty tag for each equivalent Attribute
    • itemref xml attribute: gives a URI to reference the Attribute
  • <inverseAttribute>: Include an empty tag for the Attribute to be used as the inverse. Only applies to bidirectional references.
    • itemref xml attribute: gives a URI to reference the Attribute
  • <referencePolicy>: Only applies to attributes that are references to items. Describes the type of relationship that this item has to the item refered to by this attribute. Right now this is just an experimental idea; we're not actually using this information yet, other than to document it. The idea is that the notion of "referencePolicy" would be easier to manage than a more complex set of delete and copy policies. For more info see BrianDouglasSkinner's comments about reference policies. The proposed referencePolicies are:
    • peer:
      • This is the default value, if the attribute has no relationshipType element.
      • The 'inverseAttribute' must have relationshipType 'peer'.
      • The delete policy will be set to 'strong reference' (aka 'cascade:count').
      • The copy policy will be set to 'leave null if the inverseAttribute is cardinality single, otherwise do a shallow copy'.
    • parent: The item that uses this attribute is part of a hierarchy of items. This attribute points to an item which is the parent of this item.
      • The 'inverseAttribute' must have relationshipType 'children'.
      • The delete policy will be set to 'strong reference' (aka 'cascade:count').
      • The copy policy will be set to 'shallow'.
      • In RDF/OWL, the attribute will be marked as 'transitive'.
    • children: The item that uses this attribute is part of a hierarchy of items. This attribute points to the items which are the children of this item.
      • The 'inverseAttribute' must have relationshipType 'parent'.
      • The delete policy will be set to 'strong reference' (aka 'cascade:count').
      • The copy policy will be set to 'leave null if the inverseAttribute is cardinality single, otherwise do a shallow copy'.
      • In RDF/OWL, the attribute will be marked as 'transitive'.
    • owns:
      • The 'inverseAttribute' must have relationshipType 'ownedBy'.
      • The delete policy will be set to 'cascade'.
      • The copy policy will be set to 'deep'.
    • ownedBy:
      • The 'inverseAttribute' must have relationshipType 'owns'.
      • The 'cardinality' must be 'single'.
      • The delete policy will be set to 'weak reference' (aka 'remove').
      • The copy policy will be set to 'leave null if the inverseAttribute is cardinality single, otherwise do a shallow copy'.
    • equivalent:
      • The 'inverseAttribute' must be this attribute.
      • In RDF/OWL, the attribute will be marked as 'transitive'.
      • In RDF/OWL, the attribute will be marked as 'symmetric'.

• <Alias>: Top level element, will generate an Alias item in the repository. The Alias will be globally accessible.
  • itemName xml attribute: Uniquely identifies this item among all other kinds, types and aliases in this schema. Not the UUID. Used in the repository containment path. Used to reference this item from other schema declarations.
  • <displayName>: String that can be used as a display name for this Alias.
  • <description>: Description of this item, for documentation.
  • <examples>: Example for this item, for documentation.
  • <issues>: Open issue related to this item, for documentation.
  • <aliasFor>: One empty element for each Type or Kind this alias can represent.
    • itemref xml attribute: gives a URI to reference a Type or Kind item.

• <Type>: Top level element, will generate a Type item in the repository. The Type will be globally accessible.
  • itemName xml attribute: Uniquely identifies this item among all other kinds, types and aliases in this schema. Not the UUID. Used in the repository containment path. Used to reference this item from other schema declarations.
  • <displayName>: String that can be used as a display name
  • <description>: Description of this item, for documentation.
  • <examples>: Example for this item, for documentation.
  • <issues>: Open issue related to this item, for documentation.
  • <fields>: Empty attribute for each field in the type
    • name xml attribute: give the name of the field
    • type xml attribute: give the type of the field

Schemas Describing XML Format

• Jungle.DataModelSchema-DTD (@@@ mildly bogus, need to fix to match current thinking)
• DataModelSchema-XMLSchema^?
• DataModelSchema-RelaxNG^?

XSLT Transforms

• Jungle.DataModelSchemaRepositoryTransform (now just an exercise, as we now parse the format directly)
• Jungle.DataModelSchemaXHTMLTransform Micah Dubinko's XSLT
• @@@ To RDF/XML.

Notes/Assumptions/Decisions

• Every item has a URI. The URI is a separate concept from the uuid.
• Wherever the xml attribute "itemref" is used, the xml attribute "uuid" could be used instead. Instead of having a URI value, "uuid" xml attribute would have a uuid value identifying the item.

Open Issues/To Do

• Terminology.
  • It would be nice to have one word for Kind/Type/Alias. Current proposal is Taxon.
  • DomainSchema vs schema vs data model schema, etc.
  • We've made a number of terminology changes, to attempt to be consistent everywhere.

• Does every CalendarEvent Kind item have the same URI? Across different repositories? Across replicated repositories? Is the repository an item is located in part of its URI?
  • One proposal: URIs are unique for items, just like uuids.

• We're still a bit fuzzy on some of the problems we know we need to solve with the data model. Some elements are subject to change once we're less fuzzy:
  • version
  • derivationRules
  • unidirectional
  • referencePolicy

• We might want an "include" feature, either our own tag or use XMLInclude. At the moment, we're able to avoid it in our PIM schema and core schemas.

• We'll want various attributes to have defaults. For example, the default of cardinality might be 'single'. One goal is for the common case to be short and sweet. This document doesn't specify the defaults yet, we'll add them as we gain experience.

• We'll want to clean up the containmentPath/dependsOn/namespace tags. We want the containment path for each DomainSchema specified in at most one document. Perhaps it will be generated based on the parcel directory, or some other reasonable solution.

---

Discussion

• BrianDouglasSkinner's comments about reference policies: http://lists.osafoundation.org/pipermail/dev/2003-August/000756.html
• Feedback from MicahDubinko: http://lists.osafoundation.org/pipermail/dev/2003-August/000760.html

-- KatieCappsParlante - 13 Aug 2003