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 very complex rules. The 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:
These two schoolIds are searched on in the ODS/API as schoolId and feederSchoolId:
This is because in the database implementation role names are used as prefixes to column names, here to differentiate the column names that refer to the two different Schools.
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:
These three schoolId document properties map to only two schoolIds in the search properties, schoolId and locationSchoolId:
This is because in the database implementation the schoolId column is unified as part of the foreign key reference to both the CourseOffering and Location tables.
Example 3: Prefix Variations from Merge and Role Name Collapsing on Grade
Grade provides an example of naming variations within a single reference. Grade has a schoolId on both gradingPeriodReference and studentSectionAssociationReference:
In the definition of Grade in the model, the GradingPeriod reference is itself role named with GradingPeriod. As seen in Example 1, this typically results in the prefixing of reference properties with the role name. Note that in the document, gradingPeriodReference has the additional properties gradingPeriodDescriptor, periodSequence, and schoolYear:
In the search properties, there is an inconsistency of prefixing in relation to these document properties. schoolYear and gradingPeriodDescriptor are unchanged while a "grading" prefix has been added to periodSequence and a "gradingPeriod" prefix has been added to schoolYear:
Prefixing with properties gradingPeriod
schoolId is unchanged because there is a merge between the schoolId in gradingPeriodReference and studentSectionAssociationReference, so they share the same column in the database.