Synopsis

The Survey API is a set of API endpoints for the exchange of education organization survey data in both K–12 and higher education. The API includes representations of surveys, survey questions, survey responses, as well as aggregated numeric responses.

The API is designed to support many use cases related to exchange of survey data. The API design specifically includes the data models, transactional surface, and other structures necessary to support the most common surveys and survey provider features in use in these education domains.

Contents

Overview

The Survey API specification provides a blueprint for capture and exchange of survey data for K–12 and higher education organizations. The survey domain model described in this RFC is currently a part of the Teacher Preparation Data Model (TPDM)

The survey domain closely models the information domains of many of the larger, well known survey vendors such as SurveyMonkey, SurveyGizmo and Qualtrex. 

Use Cases

An education organization has an existing survey provider with surveys and responses to those surveys. They want to be able to report on the results of the surveys given the context of other data points. The organization has a number of surveys; some of them include:

• Student Perception Survey. This is a survey sent to students generally near the end of a school year and measures student perceptions on a variety of topics including: classroom engagement, classroom climate, and student teacher relationships
• Employment Satisfaction Surveys. This survey may be given to the staff at an organization and is meant to determine staff satisfaction at a given institution.
• Principal Effectiveness Survey. This is a survey generally given by a state agency to the principals of schools to evaluate teachers on their first year of teaching after receiving their teaching certification. 

Each of these surveys have a varying number of questions, and some questions might vary in form. Some questions expect a free text answer, others use a Likert scale to rate the responses. Another could employ a Likert scale but incorporate multiple similar questions as a single matrix question. Each of these survey and question types may be transferred via API from the organizations existing survey platform directly into the Ed-Fi Survey domain using endpoints within the survey domain.

Model

The Ed-Fi Unifying Data Model (UDM) harmonizes data definitions across technology published by the Ed-Fi Alliance. This section describes the Ed-Fi UDM structure for the proposed Survey API model. 

Figure 1. Ed-Fi Survey domain representation

Model Overview

The Survey domain is composed of two sections, the inquiry side (Survey, SurveySection, SurveyQuestion) and the response side (SurveyResponse, SurveySectionResponse, SurveyQuestionResponse).

On the inquiry side, the primary entity is the Survey entity. The Survey entity acts to create a template for questions to be presented to a survey taker. The Survey can optionally be attached to an Education Organization, School Year, or Term. Surveys can also be categorized via the SurveyCategoryDescriptor. 

Adding an optional SurveySection to a survey allows for further grouping of questions within a survey. This enables the survey designer to create a survey with multiple topics but still organized in a way that makes sense to the survey taker. SurveySection also enables a more complete analysis of the completed survey.

The SurveyQuestion entity is the heart of the survey domain. These are the questions that make up the survey. Each SurveyQuestion has a field for the text of the question being asked. Each question can expect the answer in a number of different forms, the most common of which are:

• Free Form Text. A question is asked and the answer is expected as a typed entry:
  • Question: "What color is the sky?"
  • Answer: Blue 
• Numeric Choice. An example would be a rating question:
  • Question: "How would you rate class X? 1 is Least satisfied, 5 is Most Satisfied"
  • Answer: 5 - Most Satisfied
• Text Choice. Similar to numeric choice, text choice is a question with pre-defined text values for answers:
  • Question: "What color is the sky?" with choices A - Blue, B - Green, C - Red, D - Yellow
  • Answer: A - Blue

The other section of the Survey domain captures survey responses.

The SurveyResponse entity is a response to a survey, and holds information about the respondent such as full name, e-mail address, date survey was taken, and the amount of time it took to complete the survey. The SurveyResponse entity also has holds a link to the person-type entity that took this survey (Student, Staff, or Parent). Survey responses can also target a person type (Student, Staff) as well as an Education Organization.

The SurveySectionResponse entity brings together a survey response with a survey section, again allowing for a specific grouping of survey question answers. The SurveyResponse entity also adds a rating field, so that that section of the survey can be rated against other SurveySectionResponses for that survey. Like the SurveyResponse entity above, the SurveySection entity can also target a person type (Student, Staff) as well as an Education Organization.

The SurveyQuestionResponse entity contains the response to an individual SurveyQuestion as well as a link back to the original SurveyQuestion asked (this way, the text of the question being answered is always available). The responses can take many forms, including free text, numeric responses, and matrix responses.

Mapping Assessments to the Survey Domain

The Survey domain and current Ed-Fi Assessment domain have many similarities and for many use cases are interchangeable. This overlap has generated a healthy debate within the Ed-Fi community and ecosystem as to whether the two models should be combined into a single API and data model.

This RFC takes the position that these APIs and data models should not be combined. Assessments in K–12 and higher education are highly domain-specific constructs and generally apply to students, those enrolled and receiving instruction in an education organization. For example, assessments are often indexed to learning standards and include detailed question telemetry, while these use cases rarely if ever apply to surveys. Likewise in the provider ecosystem, we observe that survey providers have emerged as a specific class of providers and appear distinct from assessment providers.

Accordingly, this RFC proposes an independent model in in order to allow the two models to evolve independently. However, this RFC acknowledges overlap and common use cases, and therefore describes below how mapping between the two data models should work.

Assessment

• The top level entity of Assessments is assessment. The analog on the survey side is the survey entity, The fields in the table below can be mapped directly between the two domains. 

  Assessment	Survey
  AssessmentIdentifier	SurveyIdentifier
  Namespace	Namespace
  AssessmentTitle	SurveyTitle
  EducationOrganization	EducationOrganization
  AssessmentCategory	SurveyCategory

• All required survey fields can be mapped successfully.
• AcademicSubject is required for assessment. Surveys can be associated to programs and courses but does not provide an support for academic subject.
• The following optional fields on the Assessment entity have no direct mapping to the survey entity: AdaptiveAssessment, AssessmentFamily, AssessmentForm, AssessmentIdentificationCode, AssessmentPerformanceLevel, AssessmentPeriod, AssessmentScore, AssessmentVersion, ContentStandard, GradeLevel, Language, MaxRawScore, Nomenclature, PlatformType, RevisionDate, SectionOrProgramChoice.

AssessmentItem

• The analog for AssessmentItem is the SurveyQuestion. The fields in the table below can be mapped directly between the two domains. 

  AssessmentItem	SurveyQuestion
  IdentificationCode	QuestionCode
  AssessmentItemCategory	QuestionForm
  ItemText	QuestionText
  PossibleResponse	ResponseChoice

• All required survey fields can be mapped successfully, assuming that ItemText for an AssessmentItem is provided. SurveyQuestion requires QuestionText, where ItemText is optional.
• IdentificationCode is required on AssessmentItem but has no analog in the survey domain.
• The following fields on the AssessmentItem entity have no direct mapping to the SurveyQuestion entity: CorrectResponse, ExpectedTimeAssessed, LearningStandard, MaxRawScore (unless mapped as a Matrix question in Survey).

StudentAssessment

• This is the top level entity for the measurement side of assessments. The analog for a StudentAssessment is a SurveyResponse.

  StudentAssessment	SurveyResponse
  StudentAssessmentIdentifier	SurveyResponseIdentifier
  GradeLevel	SurveyLevel
  Description	Comment

• AdministrationDate and AdministrationEndDate can be mapped via calculation. Both AdministrationDate and AdministrationEndDate are Datetime values, meaning they have the date and the time associated with it. SurveyResponse has a ResponseDate, (the date the survey was started) and a ResponseTime (the duration of the survey). Using the date from AdministrationDate and differences between the two times will give duration.
• The student to which an assessment pertains can be tracked via the student reference on SurveyResponse.
• SchoolYear is found on the Survey entity.
• The following fields on StudentAssessment have no direct mappings to SurveyResponse: SerialNumber, Language, AdministrationEnvironment, Accommodation, RetestIndicator, ReasonNotTested, ScoreResult, GradeLevel, PerformanceLevel, EventCircumstance, StudentObjectiveAssessment, PlatformType.

StudentAssessmentItem

• The analog for StudentAssessmentItem is the SurveyQuestionResponse.

  StudentAssessmentItem	SurveyQuestionResponse
  AssessmentResponse	TextResponse
  DescriptiveFeedback	Comment

• SurveyQuestionResponse has a complex object collectiom (SurveyQuestionResponseValue) to handle the various responses. This object requires a integer identifier for the given response. SurveyQuestionResponse was modeled this way to handle questions that have multiple correct answers. The StudentAssessmentItem.Assessment Response would get mapped to SurveyQuestionResponse.SurveyQuestionResponseValue.TextResponse.
• The following fields on StudentAssessmentItem have no direct mappings to SurveyQuestionResponse: ResponseIndicator, AssessmentItemResult, RawScoreResult, TimeAssessed.

Differences Between Survey Domain in TPDM and the Survey API

In preparation for releasing the Survey API RFC, reviews were done on the survey model within TPDM. These reviews were looking for obvious errors within the survey domain but also to verify that the domain met standard Ed-Fi design principals. The following suggestions came out of those reviews:

• Namespace. The Ed-Fi ODS / API uses namespace-based authorization to secure the data entities within many domains. The survey domain within TPDM was not originally designed with use of namespaces in mind. For the Survey RFC, A namespace field has been added to the survey entity. Namespace is a string field 255 characters in length, is required and is part of the key for all survey entities within this RFC. Namespace is meant to hold a URI identifying whom has read and write access to that particular row of data within the survey domain.
• Term Descriptor. The term descriptor was included originally because it was an easy way of determining the time period that a survey was meant to be administered. The term descriptor is slowly being phased out within Ed-Fi. so we have removed the term descriptor from survey and replaced it with a session  object. The session object is a more robust way of defining the time period but is not so complex that it would be skipped in general. The session object is optional on the survey.
• Survey Question Text and Numeric Value Lists. Survey question within TPDM's survey domain has a list of numeric choices (1, 2, 3, 4, 5) and a list of text choices (Extremely Unsatisfied, Unsatisfied, Neutral, Satisfied, Extremely Satisfied). In many cases, there will only be one or the other (i.e., either text or numeric). But, in some cases, it may be desired to have both lists with values and have those values correlated. This specification adds an object, ResponseChoice, which contains both lists of numeric and text values as well as a sort order. This allows the two lists to work independently or be dependent based on the particulars of the use case.
• Survey Question Response Values. In field use, it was observed that answers to some of the more complex question types (e.g., multiple choice, multiple selection) could not be mapped into the survey response entity as it has been designed as if there were only a single text and numeric response on SurveyQuestionResponse. To resolve this issue, we created an entity called SurveyQuestionResponseValue. This object contains a text and numeric response and is added to SurveyQuestionResponse as a collection, so there is the option to have multiple responses on a single question response.