- Publishing a Schema
- Creating a Sync Schema
- Data Class Properties
- Entity Properties
- Conclusion
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Entity Properties
The entity properties is the most complex piece of the sync schema and consequently the portion that will cause the most issues. If an application is getting sync errors during development, chances are that the error is here. The properties are shown in the following table.
|
Name |
A unique name for the entity (typically, a reverse DNS-style name such as com.apple.Contacts). Can be localized using the Schema.strings file located in the schema bundle. This key is required. |
|
ExtensionName |
A unique name for this extension if you are adding attributes to an existing entity. The extension name is used to scope the attribute and relationship names to prevent collisions (typically, a reverse DNS-style name such as com.apple.iCal.CalendarExtensions). If this is a schema extension, this key is required. |
|
DataClass |
The name of the data class this entity belongs to. This key is required. |
|
ExcludeFromDataChangeAlert |
Set to true if you want to exclude changes to records of this entity type from the total count of changed records used in alert messages; false otherwise. |
|
Attributes |
An array containing dictionaries describing the attributes in the entity or extension. |
|
Relationships |
An array containing dictionaries describing the relationships in the entity or extension. |
|
IdentityProperties |
An array containing the names of the entity properties that are used to match a new record from a sync client with an existing record. If the target of a to-one relationship is used, the name of the relationship is specified. |
|
PropertyDependencies |
An array containing arrays of groups of properties that are dependent on each other. A dependent property is one that must be pushed to a client if any of its dependencies are changed. Each entry in this array is itself an array of strings, specifying the names of the codependent properties. Entries in these arrays can be an attribute name or a relationship name. |
|
Parent |
The name of the relationship that contains or encloses records belonging to this entity. Used to display a user-friendly entity name when conflicts occur during syncing. For example, in the contacts schema, the target of the contact relationship is the parent of a Phone Number record. |
An example of this level of the properties file would be:
<dict> <key>Name</key> <string>com.zarrastudios.myApplicationSync.NewsSource</string> <key>DataClass</key> <string>com.zarrastudios.myApplicationSync.News</string> <key>Attributes</key> ... <key>Relationships</key> ... <key>IdentityProperties</key> ... </dict>
The properties of an attribute are shown in the following table.
|
Name |
The name of the attribute. Can be localized using the Schema.strings file located in the schema bundle. The localization key is $entity/$attribute_name. For example, the localization key for the title attribute of the com.zarrastudios.myApplicationSync.NewsSource entity would be com.zarrastudios.myApplicationSync.NewsSource/title. This key is required. |
|
Required |
Value of yes or no. The sync engine will reject a record that doesn’t have a required attribute set. The default value is no. |
|
Type |
The type of the attribute. This key is required. |
|
ExcludeFromDataChangeAlert |
Set to true if you want to exclude changes to this attribute from the total count of changed attributes used in alert messages; false otherwise. |
Sync Services currently supports the following types of attributes:
|
array |
NSArray |
|
boolean |
NSNumber |
|
calendar date |
NSCalendarDate |
|
color |
NSColor |
|
data |
NSData |
|
date |
NSDate |
|
dictionary |
NSDictionary |
|
number |
NSNumber |
|
string |
NSString |
|
url |
NSURL |
|
enum |
NSString |
Based on these definitions, the following fragment could describe the new source object:
<key>Attributes</key>
<array>
<dict>
<key>Name</key>
<string>source</string>
<key>Type</key>
<string>url</string>
</dict>
<dict>
<key>Name</key>
<string>title</string>
<key>Type</key>
<string>string</string>
</dict>
<dict>
<key>Name</key>
<string>added</string>
<key>Type</key>
<string>date</string>
</dict>
</array>
When using an array type, it is possible to further limit the contents of the array to instances of a class and its subclasses as follows:
<dict>
<key>Name</key>
<string>feeds</string>
<key>Type</key>
<string>array</string>
<key>Subtype</key>
<string>url</string>
</dict>
When using an enum type, it is required that all the values for the enum also be defined:
<dict>
<key>Name</key>
<string>status</string>
<key>Type</key>
<string>enum</string>
<key>EnumValues</key>
<array>
<string>Active</string>
<string>Inactive</string>
<string>Unavailable</string>
</array>
</dict>
In addition to attributes, the relationships between the objects are also defined in the schema. The properties for each relationship are shown in the following table.
|
Name |
The name of the relationship. Can be localized using the Schema.strings file located in the schema bundle. The localization key is $entity/$relationship_name. For example, the localization key for the event relationship of the com.mycompany.syncexamples.Media entity would be com.mycompany.syncexamples.Media/event. This key is required. |
|
ExcludeFromDataChangeAlert |
Set to true if you want to exclude changes to this relationship from the total count of changed relationships used in alert messages; false otherwise. |
|
Target |
An array containing the names of the target entities. Generally, a relationship has a single target. However, you can specify multiple entities as the target if the target can be a number of different types. This key is required. |
|
DeleteRule |
A value of cascade or nullify. If set to cascade, all the target records are deleted when the source record of the relationship is deleted. If set to nullify, the reference from the source’s relationship is removed when the target record is deleted. If it is a to-one relationship, the relationship is set to null. If it is a to-many relationship, it is removed from that relationship. |
|
Ordinality |
Indicates a to-one or to-many relationship; value of one or many. The default value is one. |
|
Ordering |
Value of none, weak, or strong. If the value is none, no order is maintained. If the value is strong, the order is maintained, and alert panels appear when conflicts occur. If the value is weak, the order is maintained, but alert panels do not appear when conflicts occur—the sync engine merges ordering conflicts. The default value is none. |
|
Required |
Value of yes or no. The sync engine will reject a record that doesn’t have a required relationship set. The default value is no. |
|
InverseRelationships |
An array of dictionaries specifying this relationship’s inverse relationships. |
For example, the following fragment describes the relationship between a com.zarrastudios.myApplicationSync.Source entity and many com.zarrastudios.myApplicationSync.Article entities:
<key>Relationships</key>
<array>
<dict>
<key>Name</key>
<string>articles</string>
<key>Ordinality</key>
<string>many</string>
<key>Target</key>
<array>
<string>com.zarrastudios.myApplicationSync.Article</string>
</array>
</dict>
</array>
In addition to the relationship itself, it is always best to define relationships that are two-way as opposed to just one way. To do that in the schema, an inverse relationship is required:
<key>InverseRelationships</key>
<array>
<dict>
<key>EntityName</key>
<string>com.zarrastudios.myApplicationSync.Source</string>
<key>RelationshipName</key>
<string>source</string>
</dict>
</array>
To assist the truth database in deciding whether two objects are identical, it is necessary to define identity properties for each object, which are the properties that the truth database will look at to determine whether two objects coming from two different applications, devices, or servers are in fact the same object. For example, the identity properties for the source object defined above would be the following:
<key>IdentityProperties</key> <array> <string>source</string> </array>
In this example, the identity property is simple because URLs are unique by definition.
As can be seen in these examples, a schema can very quickly become complicated and is quite prone to errors. Fortunately, Apple has provided a command-line schema verification tool that will assist in ensuring that the schema is valid. This tool is available from the developer downloads section on their website.