Problem Statement
The ODS/API supports a "Get search pattern" for retrieving documents for a resource using property values. However, the property values used for search often do not map neatly to properties in the resource document. This is because the search properties actually expose the column names of the underlying relational schema, and those names can follow complex rules.
Decision Needed
| Note |
|---|
How important is it for Meadowlark to follow the "published" (de facto) Ed-Fi API specification with respect to query strings? The Ed-Fi API Guidelines: /wiki/spaces/EFAPIGUIDE/pages/24281161 states "An Ed-Fi REST API should support querying capabilities when searching a collection of Resources." Therefore judging by the published guidelines, the query operations are not a strict requirement of an Ed-Fi compatible API. Those guidelines are neutral on the exact subject. Furthermore, the Ed-Fi API specification is not published as standard in itself; however, the API specification surfaced by the ODS/API has become a de facto standard, since it is the only widely available implementation of an API that uses the Ed-Fi Unified Data Model. Interestingly, those same API Guidelines suggest that an Ed-Fi API should implement a field selection parameter. This is not implemented by today's Ed-Fi ODS/API. |
Examples and Analysis
The expression of column naming in the search pattern examples below are in order of increasing complexity.
Example 1: Simple and Role Naming on FeederSchoolAssociation
FeederSchoolAssociation provides two naming examples around schoolId. The document itself has two schoolIds, one as part of a standard School reference named schoolReference and one as part of a School reference with a Feeder role name, named feederSchoolReference:
...
| Search Field | Document Property |
|---|---|
| schoolId | schoolReference.schoolId |
| feederSchoolId | feederSchoolReference.schoolId |
Example 2: Simple Merge on Section
Section provides an example of a merge scenario where one search field maps to multiple document properties. A Section document has three schoolIds, one each for courseOfferingReference, locationReference, and locationSchoolReference:
...
| Search Field | Document Property |
|---|---|
| locationSchoolId | locationSchoolReference.schoolId |
| schoolId | courseOfferingReference.schoolId and locationReference.schoolId |
Example 3: Prefix Variations from Merge, Role Name and Name Collapsing on Grade
Grade provides an example of four different column naming variations within a single reference. The GradingPeriod reference on Grade is itself role named with GradingPeriod. As seen in Example 1, this typically results in the prefixing of reference properties with the role name, but variations are possible.
...
| Search Field | Document Property |
|---|---|
| schoolId | gradingPeriodReference.schoolId and studentSectionAssociationReference.schoolId |
| gradingPeriodDescriptor | gradingPeriodReference.gradingPeriodDescriptor |
| gradingPeriodSequence | gradingPeriodReference.periodSequence |
| gradingPeriodSchoolYear | gradingPeriodReference.schoolYear |
...
Options from the Meadowlark Dev Team
Meadowlark can use the MetaEd relational plugin to get these column names for ODS/API-like search support. We would need to build a mapping from them to document properties for querying as shown in the tables above. In the cases where there is one field for two properties, we will either need to choose one to search on or possibly "OR" the search on both.
...