Overview
Since VSI began to support multiple SIF versions with its products, we have had an issue with properly managing the many different sets of database definitions that have been required by each of the different SIF versions. As of the writing of this article, there are 22 distinct versions of the SIF specification that have been published across the three regions of the world.
VSICentralService — Public Information
The VSICentralService web service is an oData web service that returns useful information about the SIF specification in electronic form that can be consumed through programming libraries, databases or by applications such as Excel, PowerPivot or CMS systems. Each record is time-stamped so that agents and applications can be kept up-to-date without needing to continually reload the entire database.
This database contains some information already available in electronic form but mostly contains that which is maintained by Visual Software staff. This is because much of the information published in the specification is not published in tabular form — it is either published as XSD files, PDFs or Excel files meant for people to read and are not easily convertible for use by software applications.
We have found that whenever we make assumptions in our environment that anything is "fixed" in nature, it changes. Because of this dynamic nature, we have created several different services, one each providing information about:
- The SIF Specification — Public
- Countries (regions)
- Localities — places that define local extensions
- Locality References — specifications managed at a locality
- Specification versions (combinations of data model and infrastructure versions)
- SIF Objects
- SIF Entities — these are all the elements and attributes defined in the specification
- SIF Code Values
- SIF Extended Elements
The VSICentral database contains information about all versions of the SIF specification (as of Jan 2014, there are 16 versions in the database and over a million different code values). In order to prevent a single consumer from monopolizing all the resources of the single shared server, the web service itself limits return values from queries to 20,000 items.
So, when making requests from this web service, it is recommended that you filter your requests to limit the information to only that which you need. This can be done when calling the web service using the oData URL conventions defined in oData URI Conventions. Good examples can also be found at: Filter Examples.
SIF CodeValues
This repository contains the standard SIF code values as well as those locally defined by states and other localities.
SIF Code Values Query — Example
In the following example, we use the following URL to call the web service, asking it to return information about code values used in the SIF Object 'StudentSectionEnrollment' for the DataModelVersion '2.0R1'. Since only the US has a data model with that version number, no other countries will represented in the returned information. The URL will be:
Once executed, the returned information will look like this in a browser window:
(note: some browsers do not (or no longer) display XML messages properly or need a plug-in before they are able to display formatted XML.
Information Stored for Each Code Value
The following is the definition of the table in the supporting database that contains the information returned about each returned code value.
Key | Name | Data Type | Max Length (Bytes) | Allow Nulls | Identity | Default |
![]() | RecordID Unique identifier in the code values table | int | 4 | False | 1 — 1 | |
![]() | CountryCode Data Model Country — US, UK, AU or GLOBAL | varchar(10) | 10 | True | ||
![]() | DataModelVersion Data Model Version | varchar(10) | 10 | True | ||
![]() | InfrastructureVersion Infrastructure that supports this data model for this country (useful for queries) | varchar(10) | 10 | True | ||
![]() | LocalityName If extension, the name of the locality maintaining this code value | varchar(50) | 50 | True | ||
LocalityReference If this is a local code value, this refers to the local specification that provides more detail for this code | varchar(75) | 75 | True | |||
![]() | ObjectName SIF object related to the element/attribute that uses this code value | varchar(255) | 255 | True | ||
ItemType E=Element, A=Attribute | varchar(5) | 5 | True | |||
![]() | ItemName Base element name associated with this code value (even if the code value is directly associated with an attribute) — this is useful for searching | varchar(75) | 75 | True | ||
SIFIdentifier - this is a hexadecimal value assigned to this code value to make these values compatible with the SIF 3.* specifications. | varchar(50) | 50 | True | |||
![]() | XPATH XPATH of item associated with this code value (element or attribute) | varchar(255) | 255 | True | ||
CodeValue The code value as defined in the specification (originated by an outside authority such as the NCES) | varchar(255) | 255 | True | |||
CodeMeaning Description — useful in applications for lookup tables | varchar(max) | max | True | |||
CodeDescription | varchar(max) | max | True | |||
DateCreated Date this entry was first created | datetime | 8 | True | (getdate()) | ||
LastUpdated Date this entry was last edited | datetime | 8 | True | (getdate()) | ||
IsDeprecated This code value will be removed in a future release of the SIF specification | bit | 1 | True | ((0)) | ||
LastAction This may either be 'Add" or 'Change" | varchar(10) | 10 | True | ('Add') | ||
CreatedBy Name of the account that created this code value table entry | varchar(255) | 255 | True | ('admin') | ||
MaintainedBy Name of the account that has authority to maintain this table entry — this has significance when the code value is locally maintained; it will correspond to an account name of the locality-assigned user responsible for maintaining these entries | varchar(255) | 255 | True |
The XML returned by the web service has a 1–1 correspondence to the values in this table.
SIF Entities — Object Detail
This method returns information from the SIF specification. We have found it helpful for populating dropdown boxes and keeping other parts of the SIF agent up to date.
SIF Entities Query— Example
In the following example, we use the following URL to call the web service, asking it to return information about the SIF Object 'StudentSectionEnrollment' for the DataModelVersion '2.0R1'. Since only the US has a data model with that version number, no other countries will represented in the returned information. The URL will be:
Once executed, the returned information will look like this in a browser window:

(note: some browsers do not (or no longer) display XML messages properly or need a plug-in before they are able to display formatted XML.
Countries (regions)
This table contains information about the regions (countries) for which information is maintained by this service. This method should be called first and this information should be used to filter other calls to reduce the amount of information returned.
The following table defines the values returned by this web service method:
Name | Data Type | Max Length (Bytes) | Description |
RecordID | int | 4 | |
CountryCode | varchar(10) | 10 | The short code as most commonly used to reference the country |
CountryName | varchar(50) | 50 | The full name of the country or region |
DateCreated | datetime | 8 | |
LastUpdated | datetime | 8 | |
IsDeprecated | bit | 1 | |
LastAction | varchar(10) | 10 | |
CreatedBy | varchar(255) | 255 | |
MaintainedBy | varchar(255) | 255 |
SIF Countries— Example
SIF Versions (combinations of data model and infrastructure versions)
This method returns information about the combinations of Country /Infrastructure / Data Model versions for which information is available from this service. This method should be called first and this information should be used to filter other calls to reduce the amount of information returned.
The following table defines the values returned by this web service method:
Name | Data Type | Max Length (Bytes) |
RecordID | int | 4 |
CountryCode | varchar(10) | 10 |
InfrastructureVersion | varchar(50) | 50 |
DataModelVersion | varchar(50) | 50 |
DateCreated | datetime | 8 |
LastUpdated | datetime | 8 |
IsDeprecated | bit | 1 |
LastAction | varchar(10) | 10 |
CreatedBy | varchar(255) | 255 |
MaintainedBy | varchar(255) | 255 |
SIF Versions— Example
Localities — places thatdefine local extensions
This method returns information about the localities about which Extended Elements and Code Values are maintained. This method should be called first and this information should be used to filter other calls to reduce the amount of information returned.
The following table defines the values returned by this web service method:
Name | Data Type | Max Length (Bytes) | Description |
RecordID | int | 4 | |
LocalityName | varchar(50) | 50 | Code used as a reference in other tables |
LocalityDescription | varchar(255) | 255 | A full description of the locality |
DateCreated | datetime | 8 | |
LastUpdated | datetime | 8 | |
IsDeprecated | bit | 1 | |
LastAction | varchar(10) | 10 | |
CreatedBy | varchar(255) | 255 | |
MaintainedBy | varchar(255) | 255 |
SIF Localities — Example
Locality References — specifications managed at a locality
This method returns detailed information about the specifications referred to in the Locality Definitions.
The following table defines the values returned by this web service method:
Name | Data Type | Max Length (Bytes) | Description |
RecordID | int | 4 | |
LocalityName | varchar(50) | 50 | state (or other locality) name |
LocalityReference | varchar(50) | 50 | the name of the specification from which this value was taken (abbreviation) |
sifCodesetId | varchar(50) | 50 | hex unique value for this codeset |
Description | varchar(254) | 254 | the name of the specification from which this value was taken (full) |
DateCreated | datetime | 8 | |
LastUpdated | datetime | 8 | |
IsDeprecated | bit | 1 | |
LastAction | varchar(10) | 10 | |
CreatedBy | varchar(255) | 255 | |
MaintainedBy | varchar(255) | 255 |
SIF Locality References—Example
SIF Objects
This method returns information about the objects that are available with each version of the SIF specification. Remember to apply filters for the CountryCode and specification versions when calling this method.
The following table defines the values returned by this web service method:
Name | Data Type | Max Length (Bytes) | Description |
RecordID | int | 4 | |
CountryCode | varchar(10) | 10 | |
DataModelVersion | varchar(10) | 10 | |
InfrastructureVersion | varchar(10) | 10 | |
LocalityName | varchar(50) | 50 | This would be only used if an entire custom object were being created. |
ObjectName | varchar(175) | 175 | |
WorkingGroup | varchar(175) | 175 | This is optional (some regions do not assign objects to working groups) |
EventsReported | bit | 1 | A flag indicating that this is an object where events are generated. All objects support requests and responses. |
Description | varchar(max) | max | Full description of the object |
DateCreated | datetime | 8 | |
LastUpdated | datetime | 8 | |
IsDeprecated | bit | 1 | |
LastAction | varchar(10) | 10 | |
CreatedBy | varchar(255) | 255 | |
MaintainedBy | varchar(255) | 255 |
SIFObjects— Example
SIF Extended Elements
Calling this method will return information about Extended Elements registered with Visual Software for the Locality specified.
The following table defines the values returned by this web service method:
Name | Data Type | Max Length (Bytes) | Description |
RecordID | int | 4 | |
CountryCode | varchar(10) | 10 | Country or region where defined |
DataModelVersion | varchar(10) | 10 | |
InfrastructureVersion | varchar(10) | 10 | |
LocalityName | varchar(50) | 50 | Where this EE is being used |
LocalityReference | varchar(50) | 50 | The name of the local specification that gives more detail about how this EE works |
ObjectName | varchar(175) | 175 | SIF object where this EE is attached |
ExtendedElementName | varchar(255) | 255 | Name of EE as will be used in the XML message |
ExtendedElementType | varchar(max) | max | O (Optional), M (Mandatory, C (Conditional) |
Description | varchar(max) | max | Full description of the EE — this will not be transmitted with the data |
DateCreated | datetime | 8 | |
LastUpdated | datetime | 8 | |
IsDeprecated | bit | 1 | |
LastAction | varchar(10) | 10 | |
CreatedBy | varchar(255) | 255 | |
MaintainedBy | varchar(255) | 255 |
SIF Extended Elements — Example
vsiCentralService — oData Information Access
The format of the XML returned by this web service is defined by the oData specification. According to the www.odata.org web site, the Open Data Protocol is defined as follows:
OData is a standardized protocol for creating and consuming data APIs. OData builds on core protocols like HTTP and commonly accepted methodologies like REST. The result is a uniform way to expose full-featured data APIs.
By making use of the oData output format, the output of this web service can be used as input in many ways.
- There are many freely available libraries available that accept oData input sources, including
- .NET
- Javascript
- Java
- PHP
- Ruby
- C++
- Silverlight
- Telerik environments
- There are CMS and other applications that accept oData input, including:
- Joomla
- Drupal
- WebSphere
- PowerPivot, Excel
- Dynamics
- SAP
- Webnodes
- eBay
- Nuget
- Databases
- SQL Server
- MySQL
- Azure, others
As confirmation that this service has passed all the requirements for an oData endpoint, we ran the code service through the oData validation tool (the closest thing they have to certification):
..and it passed all the validity tests.
Consuming Web ServiceData
Through the OData interface, the data from the VS SIF Information Web Service may be consumed by a host of other interfaces. For an up to date list of providers, consumers, live services and programming libraries that support OData (and, hence this web service), see: OData Ecosystem
ImportingInto Excel
As an example, this series of screen shots illustrate how this web service data may be imported into an Excel spreadsheet. First, on Excel's "Data" tab, choose to import data from the web. This feature has been available (at least) from Office 2010. (Click image to see full view).
Enter the URL of the web service, including filters into the "Address" input box and click the "Go" button. If the URL you specified will return many rows of data, expect to wait a few minutes.
Excel will display the output of the web service in its XML form in the window. Click the "right arrow" button shown here in this picture to select the entire contents.
When the XML has been selected, Press the 'Import' button. Depending on how much data has been loaded from the web service, this may take a few minutes.
This screen will ask you if you want to add this data to the current worksheet or to a new worksheet.
This is a typical error — since this web service will always output some numeric columns and since Excel will always translate them to text columns, this is warning you that it is doing so. If you want to use them as numeric columns in Excel, you will need to manually change them back. Your data has been imported. Notice that ALL of the web service output has been imported, including some columns that you will not need in Excel. If you are going to use this same OData output for input to programming controls, however, they will need this information, so we need to display it. If you don't want to see it, manually remove the columns you don't need.