Extending the ODS / API Data Model

The basic pattern for adding extensions to the Ed-Fi ODS / API data model is to develop and place customizations into the Ed-Fi-ODS-Implementation directory. The top levels of this directory mirror the standard functionality that is contained in the Ed-Fi-ODS directories. When developers complete the development for an extension to the ODS / API data model, re-running the initialize development environment steps (discussed in the Getting Started documentation) will use code generation to automatically add your data extensions to the Ed-Fi ODS / API.

Implementing an extension involves making changes to the following components:

Implementation details for each of these components are described below. In addition, see the the How To: Extend the ODS / API - Student Transportation Example and How To: Extend the Ed-Fi ODS / API - Student Transcript Example articles for a complete walkthrough.

XSD Schema

The Ed-Fi Data Standard provides XSD interchange schema for a number of data exchange scenarios. ODS / API Implementers can extend these schema to customize the data transfer for their particular needs. See the Ed-Fi Data Standard Developers' Guide for information on how to extend the standard. Extension schema files go in the \Ed-Fi-ODS-Implementation\Extensions\Schemas directory.

The Ed-Fi Standard Interchange Schema files required for the ODS / API system are downloaded via a NuGet feed. At build time, the schema files from the standard are copied into a working directory (Ed-Fi-ODS\Application\schema.codegen), then any extension schema files are copied on top of the files of the same directory. Extensions to the Ed-Fi schema are made in the EXTENSION-Ed-Fi-Core.xsd file, which references Ed-Fi-Core.xsd to reference the new extensions. Extension XSD file names must start with EXTENSION and all complex types in the XSD must start with EXTENSION-.

Database Scripts

The ODS database scripts are located in their respective \Database\Structure\EdFi and \Database\Data\EdFi directories. The Ed-Fi-ODS repository contains the standard (i.e., un-customized) data structures, while the Ed-Fi-ODS-Implementation repository contains extensions. During the initialize development environment process, a set of standard scripts are run against the database, followed by the implementation scripts. The structure scripts create the database objects, and the database tables are populated by the data scripts. For example, Ed-Fi type tables are populated during this process from scripts in the Ed-Fi-ODS\Database\Data\EdFi directory.

Extension schema files need to be named in this pattern: 0001-description.sql, where 0001 is incremented for each additional sql file. Each script is run in numerical order; scripts that have been previously run in a given database are skipped (by number). 

You should put CREATE or ALTER scripts in the database implementation directories that reflect the extensions to the XSD Schema. If you need to provide additional database objects to support your customization, they should be placed here as well. You may also populate descriptors and education organizations using this technique.

Populated Sample Data

Your database extension scripts are automatically run against the sample database (minimal or populated databases). The populated sample database is retrieved from a NuGet package. However, this database contains education organizations and descriptors which you may not wish to use. If you wish to provide your own sample data, the EdFi.Samples.Ods.* NuGet should not be allowed to populate the “EdFi_Ods_Populated_Template” database during the initialize development environment process.

API Metadata

Some additional information is required to tell the code generation how to generate the Ed-Fi ODS / API. The standard metadata is downloaded during build from a NuGet feed. Extensions to the standard metadata files must be located in the Ed-Fi-ODS-Implementation\Extensions\Metadata directory. Unlike the XSD Schema files, the extension metadata files must be named the same as their corresponding standard files. For additional information, see the Metadata directory referenced above for a ReadMe.md file along with a few examples.