WI DPI WISEdata Ed-Fi Docs
WISEdata Validations API
- Jaidaa Shafaei
- heather.kluck
Introduction
This document is to describe a specification for the Ed-Fi validation endpoint for vendors to consume L2 validations results. These L2 validations results are produced downstream from the API in a validation engine (opposed to L1 validations created by the Ed-Fi API). These validations are to help support data quality based on business rules provided by an agency (ex. Wisconsin DPI).
The original specification for validations was written by Arizona and Ed-Fi ESIG https://techdocs.ed-fi.org/display/ESIG/Ed-Fi+Validation+API+Design. The scope of the original document was greater than just a Validations API because it included rules engine, rules repository, validation results repository, etc. Most of those topics will be glazed over with the validation API specification being the primary focus of this document.
The reason to focus on the validation API specifically is SEAs (ex. Wisconsin DPI) likely have an existing validation engine in place. Additionally, there have been SIS vendors interested in consuming the validation results thru the API, ultimately helping districts with their data quality journey.
Summary of Changes
The original specification had two primary endpoints- ‘Validation Rule Run’ and ‘Validation Result’. We propose three endpoints- ‘ValidationRun’, ‘Rules’, and ‘Validation Results’. ‘ValidationRun’ is optional. ‘Rules’ returns the individual rules that are run which result in a validation result. ‘ValidationResults’ eliminates the rules metadata which is now exposed in ‘Rules’. Additionally ‘ValidationResults’ is made more generic to allow for a broader range of errors to be reported, not just those tied to a specific resource.
Vocabulary
Term | Definition |
Validation Rule | A validation rule is a logical expression that specifies the conditions that will raise a validation result. |
Validation Result | A validation result is a specific example of an instance that was triggered by a validation rule. The term 'validation result' as a generic term is used for any type of result that can be generated with the terms 'major validation error', 'minor validation error', and 'validation warning' used to denote specific severity levels for the validation results as described in the functional requirements section 1.2. |
Validation Engine | The validation engine is the 'actor' that is using validation rules to find validation results. |
Resource | A resource is a tangible core data element. Examples of resources include Student, EducationOrganization, School, and Section. Every resource will have a table associated with it in an Ed-Fi ODS database (but not every table is associated with an entity). |
Validation API Architecture
The validation API will need to exist in the Ed-Fi API to allow vendors to easily consume validation results. The validation engine and results will likely be stored in a separate system/database than the Ed-Fi API/ODS. The Ed-Fi validation API code will need to read the external validation results.
There are various approaches to accomplish this which include loading the validation results back to the Ed-Fi API, using MetaEd to wrap the validation result as an Ed-Fi resource, and hosting that resources as part of the “core” data model or an extension. The benefit of this method is the validation API would automatically use the Ed-Fi resource pipeline (including authorization). However, moving data from the downstream validation repository back to the Ed-Fi ODS adds extra complexity, breaking points, and latency to the end consumer experience.
Another approach is similar to the identity model which has been dubbed the pass thru model. This would require a controller/interface which returns a standard validation result. The details of how the validation results are gathered and returned thru the controller is owned by the specific Ed-Fi implementation.
The pass thru approach seems the most logical because it gives the most benefits to the vendor, district, and schools. The downfall is that it bypasses the normal Ed-Fi API pipeline including authentication. So, the Ed-Fi host (SEA) / Validation API implementer will be required to filter results by the education organization which is provided by the ApiKey context. This filter is to limit results so different districts cannot see each other's validation results.
Finally, because Validation API will be using the pass thru model the full implementation details will not be derived in this document. However, a high level implementation details, assuming the validation results are stored in a database, include reading the validation results via a stored procedure (which has filter parameters like educationOrganizationId, RuleId, and ResourceType) and mapping the data to the validation results specifications below.
Validation Rule Run
This element will track the runs of the validation rules. This endpoint should at least provide the current state if implemented. Providing a history of runs is optional.
DATA ELEMENT | DATA TYPE / OPTIONALITY | DESCRIPTION |
ValidationRunId* | INTEGER MANDATORY | This is a unique Id for each run, most likely sequential. |
ValidationRunStartDateTime | DATETIME MANDATORY | This is the time that the validation run was started. |
ValidationRunFinishDateTime | DATETIME Optional | This is the time the validation run finished. |
ValidationRunStatus | Restricted-list VARCHAR MANDATORY | This will denote the status of the validation run. Possible values include 'Running','Finished','Stopped-manual','Stopped-Error' |
EducationOrganizationId | Integer OPTIONAL | This is useful for limiting what systems can consume the validation runs and routing the validation runs within the consuming system. |
Namespace | Integer OPTIONAL | This is useful for limiting what systems can consume the validation runs and routing the validation runs within the consuming system. |
Validation Rule
This is the structure for the validation rule which will produce the validation result.
DATA ELEMENT | DATA TYPE / OPTIONALITY | DESCRIPTION |
RuleId* | VARCHAR MANDATORY | This is the unique id for a validation rule. |
ResourceType | Ed-Fi Resource Type OPTIONAL | The primary resource in the ODS that is used to identify the data involved. Examples include edfi.StudentSchoolAssociation or edfixfinance.LocalBudget. |
HelpUrl | VARCHAR
OPTIONAL | A link to more information about the rule and how to resolve it (ex Wisconsin DPI Knowledge Based Article) |
Short Description | VARCHAR
OPTIONAL | This is non-structured ASCII text that will include the short details that were used in the evaluation of the validation rule. |
Description | VARCHAR MANDATORY | This is non-structured ASCII text that will include the details that were used in the evaluation of the validation rule. |
Status | Restricted-list VARCHAR MANDATORY | The current status of if the rule. Examples are “Active”, “Under Analysis”, Inactive”, “Deprecated”. |
Severity | Restricted-list VARCHAR MANDATORY | This specifies whether the validation result is a 'Warning', 'Minor Validation Error', 'Validation Error', or 'Major Validation Error'. |
Category | Restricted-list VARCHAR OPTIONAL | This is a category for the type of validation rule. Examples might be 'Student Demographics', 'Special Education', or 'Attendance' |
Validation Rule Example
{
"RuleId": "200005",
"ResourceName": "edfi.StudentSchoolAssociation",
“HelpLink”: “https://crmportal.dpi.wi.gov/article?id=KBA-01034-F9H4T5”,
"ShortDescription": "Student entered before school begin date",
"Description": "Student entered before school begin date. Please change the student enterDate on the enrollment/SSA to be after the school begin date.",
“Status”: “Active”,
"Severity": "Major Validation Error",
"Category": "Enrollment"
}
{
"RuleId": "6821",
"ResourceName": "edfixfinance.LocalBudget",
“HelpLink”: “https://dpidynamicsprd.powerappsportals.com/knowledgebase/article/KA-03622/en-us” ,
"ShortDescription": "Interfund Transfer Error - Operating 27 to 10",
"Description": "The revenue (10 R 127 411000) and expenditure (27 E 810 411000) for the reported operating transfer do not match.",
“Status”: “Active”,
"Severity": "Warning",
"Category": "Budget"
}
Validation Rule Endpoint
The base endpoint returns all validation rules.
https://apps.dpi.wi.gov/EdFiWebAPI/validations/v1/2022/validations/rules/
Additional filtering capabilities are done via the query string. The following endpoint includes the validation ruleId filter and will only return that rule.
https://apps.dpi.wi.gov/EdFiWebAPI/validations/v1/2022/validations/rules?ruleId=6739
Validation Result
This is the actual results from the validation rule.
DATA ELEMENT | DATA TYPE / OPTIONALITY | DESCRIPTION |
ResultId* | VARCHAR MANDATORY | This is a unique id. This id value may or may not be repeated when subsequent validation results from the same rule and the same target entity are produced. This is part of the validation result signature.
|
RuleId* | VARCHAR MANDATORY | This is a unique id that points back to the validation rule that caused the result to be produced. If a validation rule caused multiple results (for example multiple students with the same condition) they would share this id. This is part of the validation result signature. |
RunId | INTEGER OPTIONAL | This refers (foriegn key) back up to the validation rule run if implemented. |
EducationOrganizationId | Integer CONDITIONAL | This is useful for limiting what systems can consume the validation results and routing the validation results within the consuming system. Either an EducationOrganizationId or a Namespace is required.
|
Namespace | Integer CONDITIONAL | This is useful for limiting what systems can consume the validation results and routing the validation results within the consuming system. Either an EducationOrganizationId or a Namespace is required.
|
ResourceId | Ed-Fi Resource Id OPTIONAL | This is the unique identifier in the ODS that is used to reference a specific resource. Examples include StudentUniqueId or EducationOrganizationId. |
ResourceType | Ed-Fi Resource Type OPTIONAL | This is the name of the primary resource relevant to the validation result. Examples include edfi.StudentSchoolAssociation or edfixfinance.LocalActual. |
CreatedDate | TIMESTAMP MANDATORY | This is useful for determining the age of the validation. It is also useful for filtering delta/changes. |
AdditionalContext | Array of name/value pairs OPTIONAL | This is useful for providing any additional context. |
Validation Result Example
{
"educationOrganizationId": 7533,
"resultId": “F560D839-1080-479D-B2B9-446F7AC0376A”,
"ruleId": "200005",
"runId": 4387,
"resourceId": "D3DD2338-9DC4-4479-A43A-C491EEE2DDF7",
"resourceName": "edfi.StudentSchoolAssociation",
"createdDate": "2022-01-01",
"additionalContext": [
{
"name": "StartDate",
"value":"2020-09-12"
},
{
"name": "Acknowledge",
"value": "false"
}
]
}
{
"educationOrganizationId": 7533,
"resultId": “2ACED62C-3BE2-442B-9905-4AD14FA1E641”,
"ruleId": "6821",
"runId": 4395,
"resourceName": "edfixfinance.LocalBudget",
"createdDate": "2022-01-01",
"additionalContext": [
{
"name": "Revenue",
"value": 12345678.90
},
{
"name": "Expenditure",
"value": 123789456.91
},
{
"name": "Acknowledge",
"value": "true"
}
]
}
Validation Result Endpoint
The base endpoint returns all validations for the contextual school year (provided by the URL) and education organizations (provided by the ApiKey).
https://apps.dpi.wi.gov/EdFiWebAPI/validations/v1/2022/validations/results/
Additionally, filtering capabilities are done via the query string. The following endpoint includes the validation rule code filter and will only return validation results for that validation rule:
https://apps.dpi.wi.gov/EdFiWebAPI/validations/v1/2022/validations/results?ruleId=6739
The following endpoint includes the validation resource type filter and will only return validation results for the specified entity:
https://apps.dpi.wi.gov/EdFiWebAPI/validations/v1/2022/validations/results?resourceType=edfi.Student
The following endpoint includes paging using the offset and limit parameters like a standard Ed-Fi endpoint.
Offset - Indicates how many items should be skipped before returning results.
Limit - Indicates the maximum number of items that should be returned in the results.
https://apps.dpi.wi.gov/EdFiWebAPI/validations/v1/2022/validations/results?offset=100&limit=100
Authorization
The Validations API will implement authorization based on either Education Organization or Namespace as appropriate. This is the responsibility of the implementer and should follow patterns similar to established authorization strategies.
Authorization for ValidationResults is expected to follow a pattern similar to RelationshipsWithEdOrgsOnly or NamespaceBased as appropriate to the client accessing the Validations API.
Authorization for ValidationRuns will depend on the implementation. If validation runs cover the whole of the ODS, then NoFurtherAuthorizationRequired is appropriate, otherwise RelationshipsWithEdOrgsOnly or NamespaceBased would be expected.
Rules should follow NoFurtherAuthorizationRequired.
Wisconsin Department of Public Instruction