< Previous PageNext Page > Hide TOC

Creating a Sync Schema

A sync schema consists of a property list, image files, and localization files contained in a bundle that you specify when registering a schema. If you are using Core Data, then it might contain one or more managed object models, too. You can create a schema to extend an existing schema or to define your own schema. The schema property list contains a description of the entities and properties used by the client as well as other attributes used by the sync engine.

See Cocoa Design Patterns in Cocoa Fundamentals Guide for a description of entity-relationship models and terminology. See “Registering Schemas” for how to register your own schemas.

Contents:

Sync Schema Components
Creating a Sync Schema Bundle
Creating a Sync Schema Property List
Localizing Property Names
Creating a Schema Extension

Sync Schema Components

A sync schema is a property list stored in a .syncschema bundle along with other related files such as localization and image files. A property list is made up of primitive types such as arrays, dictionaries, and string values, not arbitrary types. Nevertheless, it’s helpful to view a property list as a pseudo object model.Figure 1 illustrates the components in a sync schema: the schema itself, entities, data classes, attributes, and relationships. The double arrowheads in the diagram imply a to-many relationship (implemented as an array in the property list) between components.

Figure 1  Sync schema components

Creating a Sync Schema Bundle

You can create a schema bundle using Xcode. Just select New Project from the File menu and select the Sync Schema template from the Assistant. Then edit the Schema.plist file to define your entities and properties as described in “Creating a Sync Schema Property List.” You can also localize the names of entities and properties using the Schema.strings file as described in “Localizing Property Names.”

Creating a Sync Schema Property List

After you create a schema bundle, you edit the Schema.plist file to define your entities and properties. Unless otherwise stated, the following high-level sync schema properties are optional:

For example, the following property list fragment specifies the name of the sync schema as com.mycompany.SyncExamples. Typically, you use reverse DNS-style names for schemas, entities, and client identifiers. (Working applications using this example schema are located in /Developer/Examples/Sync Services/MediaExample.)

<plist version="1.0">

<dict>

    <key>Name</key>

    <string>com.mycompany.SyncExamples</string>

    <key>DataClasses</key>

    <array>

     ...

    </array>

    <key>Entities</key>

    <array>

     ...

    </array>

</dict>

</plist>

Data Class Properties

A data class is a logical grouping of related entities. Typically, it is a grouping that makes sense to a user—for example, a group of entities that a user might want to sync over .Mac such as contacts. You can add an entity to a data class by setting the entity’s DataClass attribute. Any data class you create should be added to the schema’s DataClasses property.

The properties of a data class are as follows:

For example, the following property list fragment specifies the data classes for an example application:

    <key>DataClasses</key>

    <array>

        <dict>

            <key>Name</key>

            <string>com.mycompany.SyncExamples</string>

            <key>ImagePath</key>

            <string>SyncExamples.icns</string>

        </dict>

    </array>

Entity Properties

The properties of an entity within a sync schema are described below and are optional unless explicitly stated otherwise:

For example, the following property list fragment describes the properties of the com.mycompany.syncexamples.Media entity. Sample values for the Attributes and Relationships properties appear in “Attribute Properties” and “Relationship Properties.”

<dict>

    <key>Name</key>

    <string>com.mycompany.syncexamples.Media</string>

    <key>DataClass</key>

    <string>com.mycompany.SyncExamples</string>

    <key>Attributes</key>

    ...

    <key>Relationships</key>

    ...

    <key>IdentityProperties</key>

    ...

</dict>

Attribute Properties

The properties of an attribute belonging to an entity are as follows:

Sync Services supports the following types of attributes. Note that the types are case-sensitive and expected to appear in lowercase.

For example, the following property list fragment describes the attributes of the com.mycompany.syncexamples.Media entity. Each dictionary below contains the name and type of each attribute. For example, the date attribute is specified as a calendar date type. Therefore, when pushing or pulling a com.mycompany.syncexamples.Media record, the value for the date key will be an instance of NSCalendarDate.

<key>Attributes</key>

<array>

    <dict>

        <key>Name</key>

        <string>date</string>

        <key>Type</key>

        <string>calendar date</string>

    </dict>

    <dict>

        <key>Name</key>

        <string>imageURL</string>

        <key>Type</key>

        <string>url</string>

    </dict>

    <dict>

        <key>Name</key>

        <string>title</string>

        <key>Type</key>

        <string>string</string>

    </dict>

</array>

If you use an array type, you can further limit the contents of the array to instances of a class and its subclasses using the Subtype key. For example, the following property list fragment describes a dates attribute as an array containing NSCalendarDate objects. The Subtype key is optional but if used, is enforced by the sync engine.

<key>Attributes</key>

<array>

    <dict>

        <key>Name</key>

        <string>dates</string>

        <key>Type</key>

        <string>array</string>

        <key>Subtype</key>

        <string>calendar date</string>

    </dict>

</array>

If you use an enum type, you must also specify the possible enum values using the EnumValues key. In this example, the display order attribute is an enum that can be either firstNameFirst or lastNameFirst:

<dict>

    <key>EnumValues</key>

    <array>

    <string>firstNameFirst</string>

    <string>lastNameFirst</string>

    </array>

    <key>Name</key>

    <string>display order</string>

    <key>Type</key>

    <string>enum</string>

</dict>

Relationship Properties

Relationships from one entity to another are allowed only if the entities belong to the same data class. If you attempt to define a relationship to an entity in another data class, validation fails at runtime and an exception is raised. Schema validation may fail as well.

The properties of a relationship belonging to an entity are:

For example, the following property list fragment describes the relationships of the com.mycompany.syncexamples.Media entity. The fragment defines a to-one relationship, called event, from com.mycompany.syncexamples.Media to com.mycompany.syncexamples.Event.

<key>Relationships</key>

<array>

    <dict>

        <key>Name</key>

        <string>event</string>

        <key>Ordinality</key>

        <string>one</string>

        <key>Target</key>

        <array>

            <string>com.mycompany.syncexamples.Event</string>

        </array>

    </dict>

</array>

Inverse Relationship Properties

The properties of an inverse relationship belonging to a relationship are as follows:

For example, the following property list fragment describes the inverse relationship between the event relationship of the com.mycompany.syncexamples.Media entity and the media relationship of the com.mycompany.syncexamples.Event entity. The media relationship is a to-many relationship from com.mycompany.syncexamples.Event to com.mycompany.syncexamples.Media.

<key>InverseRelationships</key>

<array>

    <dict>

        <key>EntityName</key>

        <string>com.mycompany.syncexamples.Event</string>

        <key>RelationshipName</key>

        <string>media</string>

    </dict>

</array>

Identity Properties

The value of the IdentityProperties key is an array containing the names of the properties that are used to identify a record of this entity type if there is a conflict. For example, the identity properties for a com.mycompany.syncexamples.Media entity are specified as the date and title properties below. The com.mycompany.syncexamples.Media entity may have other properties, such as imageURL, which are not in this array.

<key>IdentityProperties</key>

<array>

    <string>date</string>

    <string>title</string>

</array>

Warning: You should always push the identity properties for a record. Otherwise, you might create duplicate records during the first sync or a refresh sync.

Property Dependencies

In some cases, if one property changes, you might want to push another related property, even if its value didn’t change. For example, suppose you change a calendar event to an all day event in iCal and using your phone you change the start time of the same event. Even though each client changed a different property, the changes conflict and need to be resolved. You can inform the sync engine about dependent properties within your entities so that these types of conflicts are recognized when syncing.

The value of the PropertyDependencies key is an array of arrays containing the dependent properties. Each array contains the set of properties that are dependent on each other. For example, you might declare that the startDate, endDate and allDayEvent properties are dependent as follows:

<key>PropertyDependencies</key>

<array>

    <array>

        <string>startDate</string>

        <string>endDate</string>

        <string>allDayEvent</string>

    </array>

</array>

Localizing Property Names

You can define user-friendly names for data classes, entities, and properties by editing the Schema.strings schema bundle localization file. Localized names are used by Sync Services applications that present records to users.

For example, an alert message might appear using a data class name in a message—for example, a panel might appear asking the user if it’s okay to syncronize with other applications. If no localization is provided, the DNS-style data class name is used in the alert message which might be confusing to the user. You should modify your Schema.strings file to provide both plural and singular forms of data class names.

Specifically, you can define a localized string for the DataClass, Entity, Relationship, and Attribute components illustrated in Figure 1. The key for the DataClass and Entity localized string is simply the Name attribute of the DataClass component. The key for an Attribute or Relationship component is of the form:

$entity/$property

For example, the Schema.strings file for the MediaExample application located in /Developer/Examples/Sync Services is:

/* Data Class: The data class for the Sync Services examples.*/

"com.mycompany.SyncExamples" = "Media Example Data";

/* Singular Data Class Name: Used for any UI that needs a singular name.*/

"Singular:com.mycompany.SyncExamples" = "Media Example Data";

/* Entity: A media item such as a photo taken at an event. */

"com.mycompany.syncexamples.Media" = "Media";

/* Attribute: The date a photo was taken. */

"com.mycompany.syncexamples.Media/date" = "Creation Date";

/* Attribute: The file URL for the image. */

"com.mycompany.syncexamples.Media/imageURL" = "Image URL";

/* Attribute: A user-friendly title of the photo. */

"com.mycompany.syncexamples.Media/title" = "Image Title";

/* Relationship: The event where the photo was taken. */

"com.mycompany.syncexamples.Media/event" = "Event";

...

Creating a Schema Extension

Sync Services also allows you to extend an existing schema without changing it directly—for example, when you don’t have permission to change it directly or you want to encapsulate your extensions from other applications. Sync Services ensures that only those applications that use the extension see the entities and properties defined by them. You can even extend existing Apple Applications schemas without adversely affecting other desktop applications. Read Apple Applications Schema Reference for details on these schemas.

Schema extensions reside in a bundle structure that is identical to sync schema bundles. The only difference is that the Schema.plist and Schema.strings files pertain only to entity and property extensions.

For example, suppose you want to add an entity called Calendar to the MediaExample schema, which maintains a collection of Event records. That way, when you import an iCal file, you can group the events together. You can do this by creating a Calendar entity with an identity attribute, such as a name or title, and an inverse to-many relationship to Event.

Follow these steps to create a schema extension that adds a Calendar entity to SyncExamples.syncschema:

1. Define a unique name for the schema extension in Schema.plist:

   <key>Name</key>

   <string>SyncExamplesExtension</string>

2. Add new properties to existing entities in Schema.plist. Specifically, add an inverse to-one relationship from Event to Calendar:

   <dict>

   <key>ExtensionName</key>

   <string>com.mycompany.syncexamples.EventExtensions</string>

   <key>Name</key>

   <string>com.mycompany.syncexamples.Event</string>

   <key>Relationships</key>

   <array>

   <dict>

   <key>InverseRelationships</key>

   <array>

   <dict>

   <key>EntityName</key>

   <string>com.mycompany.syncexamples.Calendar</string>

   <key>RelationshipName</key>

   <string>events</string>

   </dict>

   </array>

   <key>Name</key>

   <string>calendar</string>

   <key>Ordinality</key>

   <string>one</string>

   <key>Target</key>

   <array>

   <string>com.mycompany.syncexamples.Calendar</string>

   </array>

   </dict>

   </array>

   </dict>

3. Add new entity definitions to Schema.plist: Specifically, add a Calendar entity and to-many inverse relationship from Calendar to Event. You can use the same data class, com.mycompany.SyncExamples, defined in SyncExamples.syncschema:

   <dict>

   <key>Attributes</key>

   <array>

   <dict>

   <key>Name</key>

   <string>title</string>

   <key>Type</key>

   <string>string</string>

   </dict>

   </array>

   <key>DataClass</key>

   <string>com.mycompany.SyncExamples</string>

   <key>IdentityProperties</key>

   <array>

   <string>title</string>

   </array>

   <key>Name</key>

   <string>com.mycompany.syncexamples.Calendar</string>

   <key>Relationships</key>

   <array>

   <dict>

   <key>InverseRelationships</key>

   <array>

   <dict>

   <key>EntityName</key>

   <string>com.mycompany.syncexamples.Event</string>

   <key>RelationshipName</key>

   <string>calendar</string>

   </dict>

   </array>

   <key>Name</key>

   <string>events</string>

   <key>Ordinality</key>

   <string>many</string>

   <key>Target</key>

   <array>

   <string>com.mycompany.syncexamples.Event</string>

   </array>

   </dict>

   </array>

   </dict>

4. Finally, add localization strings for new entities and properties to Schema.strings:

   /* Relationship: The calendar associated with an event. */

   "com.mycompany.syncexamples.Event/calendar" = "Calendar";

   /* Entity: A calendar, group of events.*/

   "com.mycompany.syncexamples.Calendar" = "Calendar";

   /* Attribute: The calendar title. */

   "com.mycompany.syncexamples.Calendar/title" = "Title";

   /* Relationship: The events associated with a calendar. */

   "com.mycompany.syncexamples.Calendar/events" = "Events";

The schema extensions file should look similar to the file in Listing 1.

Listing 1  Schema Extensions Example

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

    <key>Entities</key>

    <array>

        <dict>

            <key>ExtensionName</key>

            <string>com.mycompany.syncexamples.EventExtensions</string>

            <key>Name</key>

            <string>com.mycompany.syncexamples.Event</string>

            <key>Relationships</key>

            <array>

                <dict>

                    <key>InverseRelationships</key>

                    <array>

                        <dict>

                            <key>EntityName</key>

                            <string>com.mycompany.syncexamples.Calendar</string>

                            <key>RelationshipName</key>

                            <string>events</string>

                        </dict>

                    </array>

                    <key>Name</key>

                    <string>calendar</string>

                    <key>Ordinality</key>

                    <string>one</string>

                    <key>Target</key>

                    <array>

                        <string>com.mycompany.syncexamples.Calendar</string>

                    </array>

                </dict>

            </array>

        </dict>

        <dict>

            <key>Attributes</key>

            <array>

                <dict>

                    <key>Name</key>

                    <string>title</string>

                    <key>Type</key>

                    <string>string</string>

                </dict>

            </array>

            <key>DataClass</key>

            <string>com.mycompany.SyncExamples</string>

            <key>IdentityProperties</key>

            <array>

                <string>title</string>

            </array>

            <key>Name</key>

            <string>com.mycompany.syncexamples.Calendar</string>

            <key>Relationships</key>

            <array>

                <dict>

                    <key>InverseRelationships</key>

                    <array>

                        <dict>

                            <key>EntityName</key>

                            <string>com.mycompany.syncexamples.Event</string>

                            <key>RelationshipName</key>

                            <string>calendar</string>

                        </dict>

                    </array>

                    <key>Name</key>

                    <string>events</string>

                    <key>Ordinality</key>

                    <string>many</string>

                    <key>Target</key>

                    <array>

                        <string>com.mycompany.syncexamples.Event</string>

                    </array>

                </dict>

            </array>

        </dict>

    </array>

    <key>Name</key>

    <string>SyncExamplesExtension</string>

</dict>

</plist>

< Previous PageNext Page > Hide TOC