SData instance schemas

I’m being asked about SData instance schemas all of the time.  An instance schema is an application-specific implementation of a ‘generic’ schema.  I thought I’d post some more insight here for wider consumption:

Every application will be required to implement their own “instance schema” – This is not as daunting as it sounds as tools, such as the SIF component, can auto-generate a schema based on an SData implementation.

In an SData implementations there will be reference to a contract.  The contract segment of the URL will represent this e.g. and etc.

Each provider application (e.g. Sage 50, Sage 100, Sage 1000) would then implement their own instance schema that supports the contract.  So the following URL’s would retrieve instance schemas for each application’s implementation of the contract:$schema and$schema and so on.

The resultant XSD schema would be different based on what a particular application supports.  For example the schema for sage50 may show fixedAssets like this (i.e. unsupported):-

<xs:element name=”fixedAsset” type=”fixedAsset–type” sme:role=”resourceKind” sme:pluralName=”fixedAssets” sme:unsupported=”true”/>

Whereas Sage 100 (this application supports fixed assets) would show this:

<xs:element name=”fixedAsset” type=”fixedAsset–type” sme:role=”resourceKind” sme:pluralName=”fixedAssets” sme:compliance=”must” sme:canGet=”true” sme:canPut=”true” sme:canPost=”true” sme:canDelete=”true”/>

It is the ‘metadata’ attached to the schema (marked sme:) that distinguishes the functionality available by each application.  There is metadata for entities (resource kinds such as fixedAsset, salesInvoice, etc) such as canGet, isSyncSource, unsupported, etc. There is metadata for fields (properties) on entities.  There is a comprehensive set of metadata summarised here:-

This is crucial as it is the metadata that allows each application implementing a contract to specify its ‘uniqueness’.  It also allows generic consumers of the contract (other Sage/non-Sage applications, connected services, webpages, etc) to ‘discover’ what an application supports and behave accordingly.  So an application ‘consuming’ the contract will ‘discover’ (from the examples above) that sage50 does not support fixed assets.  However the same application could discover that sage100 does support the fixed assets, and behave accordingly.

In terms of customization – yes it is possible and entirely valid to customize the schemas to add application-specific (proprietary?) elements.  Following the rules above you could put all of this customization into one schema shared by all applications using the contract.  Applications that do not have the ‘proprietary’ elements would simply mark them as sme:unsupported=”true” in their instance schema.  Or you could add the proprietary elements to the instance schema of only those applications that have them.  Both options are valid.  The first option does make the schema bigger, but is much more clear in terms of advertising/publishing what is supported and what is not.

The generic schemas developed by Sage (such as common.xsd, famErp.xsd, etc. available on Github here) are simply provided as a base, or template, upon which to build application instance schemas.  All of the instance schemas are built using the common schema files as their starting point.  Products (such as Sage 50 UK, Sage Murano in Spain, Sage Office Line in Germany) who have implemented an SData contract based on the generic schemas have produced their own version – or instance – of the schema to reflect what that application supports.

Using tools, such as Github, allows development teams to ‘pull’ changes that are made in the ‘master’ schema files into your local/instance schema files as and when things change.  As the schemas evolve, so to would the instance schemas (the reason the generic schemas change is because multiple applications have the same resource kind or property that they want to share via an SData contract).

A ‘native’ SData contract schema, based on an applications database structure, is another example of an instance schema, albeit on a one-to-one basis (one instance for one application).  No other Sage application would support another’s native contract.


About craigpearson004

"Enabling Continuous Delivery" - Creative Agile Partners ( provides support to organisations transforming their way of working and looking to be "world class" in everything they do....
This entry was posted in SData, SIF. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s