Proposed Changes for v3.0

This section contains an overview of the proposed changes for the next version of the Scholar Snapp Data Standard. Some proposed changes have been drafted as part of v3.0a RFC, while other proposals are listed below for discussion and comment.

Discussed on this page:

Detail on each topic follows.

What's

Already in v3.0a? (Latest Proposed XSD)

This section outlines key proposed updates and additions in the draft Snapp v3a v3.0a RFC XSD.  Although the changes are technically valid, we are still soliciting input – so the final form may be different, or we may back out changes if implementers advise us to do so.

Ambiguity Removed from Required Elements (SSDS-1)

The v2.0 XSD specification has a logical ambiguity in many required elements: the specification allows required strings to be of zero length, meaning that the value can actually be null.

This issue tripped up field implementations (which expect "required" values to be non-null), including the Snapp UI itself (which was developed to require a non-zero-length string in "required" string fields).

Change Detail

The proposed v3.0 XSD will add a minLength=1 restriction to the ShortString and LongString types (lines 7 and 16 in the following snippet):

...
<xs:simpleType name="ShortString">	
	<xs:annotation> 			
		<xs:documentation>String used for short text fields</xs:documentation>
	</xs:annotation>
	<xs:restriction base="xs:string">
		<xs:minLength value="1"/>
		<xs:maxLength value="100"/>
	</xs:restriction>
</xs:simpleType>
<xs:simpleType name="LongString">
	<xs:annotation>
		<xs:documentation>String used for long text fields, such as essays</xs:documentation>
	</xs:annotation>
	<xs:restriction base="xs:string">
		<xs:minLength value="1"/>	
		<xs:maxLength value="4000"/>
	</xs:restriction>
</xs:simpleType>
...

The ShortString and LongString types are used as a base class for most string values in the standard. This change will force all elements that are present to have a non-zero-length string as a value.

The following snippet illustrates the practical effect of the change in XML data files:

...
<!-- Valid in v2.0, will not validate in v3.0 -->
<sds:FirstName></sds:FirstName>
...

The example above will not validate in v3.0 because FirstName is present, but doesn't meet the minimum length requirement.

References

• View ticket in the Scholar Snapp Data Standard JIRA Site (SSDS-1)
• See this change in GitHub (88e9a97)

Allow Multiple Races to be Indicated (SSDS-2)

The v2.0 Snapp Standard uses the same race list as the U.S. Census Bureau -- but unlike the census and the U.S. DoE reporting, the Snapp standard only allows a single selection for the Race enumeration.

This change allows multiple races to be indicated.

Change Detail

The proposed v3.0 XSD will add maxOccurs="unbounded" to the existing RacesList, allowing multiple selections (line 2 in the following snippet):

...
<xs:element name="Race" type="sds:RacesList" minOccurs="0" maxOccurs="unbounded">
	<xs:annotation>
		<xs:documentation>Student's race</xs:documentation>
	</xs:annotation>
</xs:element>
...

The following snippet illustrates the practical effect of the change in XML data files:

...
<!-- Not valid in v2.0, will validate in v3.0 -->
<sds:Race>AmericanIndianOrAlaskaNative</sds:Race>
<sds:Race>White</sds:Race>
...

References

Support new SAT and PSAT Test Types (SSDS-3)

The v2.0 Snapp Standard has a structured list of test types which did not account for the 2016 changes to the SAT or the 2015 changes to the PSAT. This change supports the latest College Board test types as of January 2017, and deprecates older versions of tests with similar scoring.

Change Detail

The proposed v3.0 XSD will update the values in the TestsList enumeration. 

This change also includes a minor tweak to deprecated or other old tests: v2.0 noted old test types as obsolete (e.g., SAT Verbal (Obsolete)). The proposed v3.0 changes this to indicate a timeframe (e.g., SAT Verbal (pre-2005)), which provides implementers with a more meaningful indication of what the type represents. The following snippet shows all SAT and PSAT values, with unchanged test types elided:

...
<xs:simpleType name="TestsList">
	<xs:annotation>
		<xs:documentation>The different tests that a person can take</xs:documentation>
	</xs:annotation>
	<xs:restriction base="sds:ShortString">
		<xs:enumeration value="SAT Total"/>
		<xs:enumeration value="SAT Evidence-Based Reading and Writing"/>
		<xs:enumeration value="SAT Math"/>
		<xs:enumeration value="SAT Reading Essay"/>
		<xs:enumeration value="SAT Analysis Essay"/>
		<xs:enumeration value="SAT Writing Essay"/>
		<xs:enumeration value="SAT Reading Test"/>
		<xs:enumeration value="SAT Writing and Language Test"/>
		<xs:enumeration value="SAT Math Test"/>
		<xs:enumeration value="SAT Analysis in History/Social Studies Cross-Test"/>
		<xs:enumeration value="SAT Analysis in Science Cross-Test"/>
		<xs:enumeration value="SAT Command of Evidence Subscore"/>
		<xs:enumeration value="SAT Words in Context Subscore"/>
		<xs:enumeration value="SAT Expression of Ideas Subscore"/>
		<xs:enumeration value="SAT Standard English Conventions Subscore"/>
		<xs:enumeration value="SAT Heart of Algebra Subscore"/>
		<xs:enumeration value="SAT Problem Solving and Data Analysis Subscore"/>
		<xs:enumeration value="SAT Passport to Advanced Math Subscore"/>
		<xs:enumeration value="SAT Critical Reading (pre-2016)"/>
		<xs:enumeration value="SAT Verbal (pre-2005)"/>
		<xs:enumeration value="SAT Math (pre-2016)"/>
		<xs:enumeration value="SAT Writing (pre-2016)"/>
		...unchanged values elided
		<xs:enumeration value="PSAT Total"/>
		<xs:enumeration value="PSAT Evidence-Based Reading and Writing"/>
		<xs:enumeration value="PSAT Math"/>
		<xs:enumeration value="PSAT Reading Test"/>
		<xs:enumeration value="PSAT Writing and Language Test"/>
		<xs:enumeration value="PSAT Math Test"/>
		<xs:enumeration value="PSAT Analysis in History/Social Studies Cross-Test"/>
		<xs:enumeration value="PSAT Analysis in Science Cross-Test"/>
		<xs:enumeration value="PSAT Command of Evidence Subscore"/>
		<xs:enumeration value="PSAT Words in Context Subscore"/>
		<xs:enumeration value="PSAT Expression of Ideas Subscore"/>
		<xs:enumeration value="PSAT Standard English Conventions Subscore"/>
		<xs:enumeration value="PSAT Heart of Algebra Subscore"/>
		<xs:enumeration value="PSAT Problem Solving and Data Analysis Subscore"/>
		<xs:enumeration value="PSAT Passport to Advanced Math Subscore"/>
		<xs:enumeration value="PSAT Critical Reading (pre-2015)"/>
		<xs:enumeration value="PSAT Verbal (pre-2005)"/>
		<xs:enumeration value="PSAT Math (pre-2015)"/>
		<xs:enumeration value="PSAT Writing (pre-2015)"/>
		<xs:enumeration value="PSAT Selection Index"/>
		...more unchanged values
		</xs:restriction>
	</xs:simpleType>
...

The following snippet illustrates a subset of the allowable SAT and PSAT values in XML data files:

...
<!-- High-level SAT and PSAT in v3.0 -->
<sds:TestScores>
 	<sds:Test>SAT Total</sds:Test>
 	<sds:Score>1350</sds:Score>
 	<sds:ScoreType>Highest ever score</sds:ScoreType>
 	<sds:ScoreDate>2017-01-10</sds:ScoreDate>
</sds:TestScores>
<sds:TestScores>
 	<sds:Test>SAT Math</sds:Test>
	<sds:Score>600</sds:Score>
	<sds:ScoreType>Highest ever score</sds:ScoreType>
	<sds:ScoreDate>2017-01-10</sds:ScoreDate>
 </sds:TestScores>
<sds:TestScores>
<sds:Test>SAT Evidence-Based Reading and Writing</sds:Test>
 	<sds:Score>750</sds:Score>
 	<sds:ScoreType>Highest ever score</sds:ScoreType>
	<sds:ScoreDate>2017-01-10</sds:ScoreDate>
</sds:TestScores>
<sds:TestScores>
	<sds:Test>PSAT Total</sds:Test>
	<sds:Score>1300</sds:Score>
	<sds:ScoreType>Highest ever score</sds:ScoreType>
	<sds:ScoreDate>2016-01-11</sds:ScoreDate>
</sds:TestScores>
<sds:TestScores>
	<sds:Test>PSAT Math</sds:Test>
 	<sds:Score>700</sds:Score>
	<sds:ScoreType>Highest ever score</sds:ScoreType>
 	<sds:ScoreDate>2016-01-11</sds:ScoreDate>
</sds:TestScores>
<sds:TestScores>
 	<sds:Test>PSAT Evidence-Based Reading and Writing</sds:Test>
 	<sds:Score>600</sds:Score>
	<sds:ScoreType>Highest ever score</sds:ScoreType>
 	<sds:ScoreDate>2016-01-11</sds:ScoreDate>
</sds:TestScores>
...

References

• View ticket in the Scholar Snapp Data Standard JIRA Site (SSDS-3)
• See this change in GitHub (7182b87)

Improve inline annotations (SSDS-4)

The v2.0 Snapp Standard has several annotations that are mercilessly terse. Others contain light spelling errors and typos. This proposed change makes simple corrections, all of which are non-breaking.

References

• View ticket in the Scholar Snapp Data Standard JIRA Site (SSDS-4)
• See this change in GitHub (Work In Progress)

Additional Changes Proposed

This section contains changes that are not yet in the draft data standard but are under consideration for v3.0. Presuming community agreement, the items in this section will be drafted in v3.0b of the XSD.

Remove Unused Entities and Elements (Best Practice)

RFC Status: Recommended, Open For Review and Comment

Every data field included in the standard adds cost and complexity. This change would remove those elements that were infrequently used in the 2016-2017 application cycle. An analysis was performed on over 100K profiles, with the following elements seldom containing actual data.

1. Student.Income (containing Amount, Currency elements). 4.0% data present.
2. Student.CurrentMajors.MajorRank element 3.6% data present (CurrentMajor in general is slightly higher at 5.2%).
3. Student.Activities.OrganizationAddress (containing address elements) 1.9% data present.
4. Student.StudentReferences.ReferenceAddress (containing address elements) 1.9% data present.
5. Student.GenderDetail element 1.1% data present.
6. Student.MaritalStatus element essentially 0% data present.

Exceptions abound. Some infrequently used elements are present for logical completeness, so are not included in the above. These include text fields that contain an explanation when an "Other" value is selected from an enumeration, standard-but-infrequent elements such as Address Line 2, or the Salutation for the Student name type, and similar.

Other elements not recommended for removal are present to support key partners and future use cases. For example, several FAFSA-related fields are seldom used, but Snapp has future plans for these elements.

The Student.StudentReferences.YearsKnown, Student.GovernmentAidParticipation, and various College Readiness Program elements are seldom present, but they're a key eligibility criterion for current implementers.

Acknowledge Snapp is U.S.-Centric, Remove Half-Baked International Support (Governance Committee Suggestion)

RFC Status: Recommended, Open For Review and Comment

Snapp can, theoretically, be used internationally, but in its current state it makes many U.S.-centric assumptions. In addition to not supporting certain international address formats, the standard has many elements for FAFSA (a distinctly U.S.-based concept), reliance on NCES codes (another U.S.-based concept), and similar.

This proposed change would acknowledge that Snapp implementers are U.S.-based, and make simplifying assumptions. For example:

• Remove CurrencyType
• Change StateOrProvince to enumeration
• Change Country to enumeration

We will also consider changes like removing ApplicationLanguage from Context and similar.

Change StateOrProvince and Country to Enumeration (Implementer Suggestion)

RFC Status: Recommended, Open For Review and Comment

Snapp currently allows open text values in StateOrProvince and Country. This makes it easy for implementers to export data to Snapp, but is problematic for those importing files. For example, the U.S. could be any of the following: U.S., U.S.A., United States, US, U. S. A., U. S. of A., and so forth.

This change would modify the StateOfProvince and Country elements to enumerations.

This change relates to the recommendation to make Snapp U.S.-Centric. It may be done as part of that effort – but should be considered independently, even if we continue to offer light international support in the standard.

Specify Limits to Attachment File Sizes and Overall File Size (Best Practice)

RFC Status: Recommended, Open For Review and Comment

This would primarily affect the API, and will have at least an annotation/documentation impact on the XSD.

The Snapp Data Standard currently allows for MIME Base-64 attachments, but doesn't specify a file size limit. This has practical problems in API data exchange and implementation. This change would specify a maximum size for individual files and an overall size limit for the XML Data File.

The Snapp Central API currently does not transfer attachments by default. We expect that to continue as the norm.

Specify Norms for Common Attachments Like Student Portraits (Implementer Suggestion) 

RFC Status: Open For Review and Comment

The Snapp Data Standard currently supports attachments and allows users to specify what the file represents. Implementers have suggested that Snapp provide standards and/or guidance for certain common types of attachments. For example, many scholarship applications request a portrait of a certain pixel dimension and similar.

Expand ClassTypeList to indicate "General" classes (SSDS-6)

The v2.0 Snapp Standard contains a ClassTypeList that used in the Transcript to indicate special characteristics of a class (e.g., Honors, AP, IB, Dual enrollment).

Implementers have suggested that a "Regular" entry would be useful for data exchange. This would allow systems importing profiles to differentiate between classes that are "Regular" classes and classes that have no indication because the sending system simply doesn't collect class type information or didn't include that information in the profile.

We considered values such as "General" or "Regular" or "Standard" or similar.

Change Detail

Both CEDS and the Ed-Fi Data Standard use "General" for this purpose, so we propose that option for v3.0. The following code snippet shows the complete ClassTypeList with the added value on line 7:

...
	<xs:simpleType name="ClassTypeList">
		<xs:annotation>
			<xs:documentation>The type of student courses</xs:documentation>
		</xs:annotation>
		<xs:restriction base="sds:ShortString">
			<xs:enumeration value="General"/>
			<xs:enumeration value="Senior"/>
			<xs:enumeration value="Honors"/>
			<xs:enumeration value="AP"/>
			<xs:enumeration value="IB"/>
			<xs:enumeration value="Dual enrollment"/>
			<xs:enumeration value="Special education"/>
			<xs:enumeration value="Remedial"/>
			<xs:enumeration value="Other"/>
		</xs:restriction>
	</xs:simpleType>
...

The following snippet illustrates a the use of the new General option in XML data:

...
<!-- The General value indicates a non-AP, non-IB, non-Remedial, plain old everyday class -->
<sds:SimpleTranscript>
	<sds:ClassName>Calculus</sds:ClassName>
	<sds:Year>High School Grade 12</sds:Year>
	<sds:Status>In progress</sds:Status>
	<sds:Grade>B</sds:Grade>
	<sds:Scale>Alphabetic</sds:Scale>
	<sds:Type>General</sds:Type>
	<sds:SchoolName>Austin High School</sds:SchoolName>
</sds:SimpleTranscript>
...

References

• View ticket in the Scholar Snapp Data Standard JIRA Site (SSDS-6)
• See this change in GitHub (9eb65cc)

Additional Changes Proposed

This section contains changes that are not yet in the draft data standard but are under consideration for v3.0. Presuming community agreement, the items in this section will be drafted in v3.0b of the XSD.

Remove Unused Entities and Elements (Best Practice)

RFC Status: Recommended, Open For Review and Comment

Every data field included in the standard adds cost and complexity. This change would remove those elements that were infrequently used in the 2016-2017 application cycle. An analysis was performed on over 100K profiles, with the following elements seldom containing actual data.

1. Student.Income (containing Amount, Currency elements). 4.0% data present.
2. Student.CurrentMajors.MajorRank element 3.6% data present (CurrentMajor in general is slightly higher at 5.2%).
3. Student.Activities Hours/Week and Weeks/Year ranging from 2.4% to 1.8% data present. (Activities overall is widely used.)
4. Student.Activities.OrganizationAddress (containing address elements) 1.9% data present.
5. Student.StudentReferences.ReferenceAddress (containing address elements) 1.9% data present.
6. Student.GenderDetail element 1.1% data present.
7. Student.ClassRank.OtherRank and OtherRankDescription 0.9% and 0.7% data present, respectively.
8. Student.Essays.EssayTypeOtherDesc 0.7% data present.
9. Student.Relatives.DisabilityDescription 0.7% data present.
10. Student.Activities.YearOtherDesc 0.7% data present.
11. Student.GovernmentAidParticipation.ProgramOtherDesc 0.7% data present.
12. Student.GPA.CumulativeGPA.ScaleOther 0.5% data present.
13. Student.DisabilityDesc 0.4% data present.
14. Student.StudentReferences.ReferenceContactInfo.AlternatePhoneNumber and IsAlternatePhoneNumberTextCapable 0.3% and 1.2% data present respectively (presumably, the non-applicable boolean was present, but set to false vs. omitting the element).
15. Student.MaritalStatus essentially 0% data present.
16. Student.GPA.CurrentSchoolCalculatesGPA essentially 0% data present.
17. Student.ApplyingForOtherScholarships essentially 0% data present (ironically). 
18. Student.POWDesc essentially 0% data present. Note that the Student.POW element was present, but is a boolean and so may have been present-but-false by default; if the value is always false, we may want to consider removing this element in v3.0, and add back upon request.

Exceptions abound. Some infrequently used elements are present for logical completeness, so are not included in the above. These include text fields that contain an explanation when an "Other" value is selected from an enumeration, standard-but-infrequent elements such as Address Line 2, or the Salutation for the Student name type, and similar.

Other elements not recommended for removal are present to support key partners and future use cases. For example, several FAFSA-related fields are seldom used, but Snapp has future plans for these elements.

The Student.StudentReferences.YearsKnown, Student.GovernmentAidParticipation, and various College Readiness Program elements are seldom present, but they're a key eligibility criterion for current implementers.

Acknowledge Snapp is U.S.-Centric, Remove Half-Baked International Support (Governance Committee Suggestion)

RFC Status: Recommended, Open For Review and Comment

Snapp can, theoretically, be used internationally, but in its current state it makes many U.S.-centric assumptions. In addition to not supporting certain international address formats, the standard has many elements for FAFSA (a distinctly U.S.-based concept), reliance on NCES codes (another U.S.-based concept), and similar.

This proposed change would acknowledge that Snapp implementers are U.S.-based, and make simplifying assumptions. For example:

• Remove CurrencyType
• Change StateOrProvince to enumeration
• Change Country to enumeration

We will also consider changes like removing ApplicationLanguage from Context and similar.

Change StateOrProvince and Country to Enumeration (Implementer Suggestion)

RFC Status: Recommended, Open For Review and Comment

Snapp currently allows open text values in StateOrProvince and Country. This makes it easy for implementers to export data to Snapp, but is problematic for those importing files. For example, the U.S. could be any of the following: U.S., U.S.A., United States, US, U. S. A., U. S. of A., and so forth.

This change would modify the StateOfProvince and Country elements to enumerations.

This change relates to the recommendation to make Snapp U.S.-Centric. It may be done as part of that effort – but should be considered independently, even if we continue to offer light international support in the standard.

Specify Limits to Attachment File Sizes and Overall File Size (Best Practice)

RFC Status: Recommended, Open For Review and Comment

This would primarily affect the API, and will have at least an annotation/documentation impact on the XSD.

The Snapp Data Standard currently allows for MIME Base-64 attachments, but doesn't specify a file size limit. This has practical problems in API data exchange and implementation. This change would specify a maximum size for individual files and an overall size limit for the XML Data File.

The Snapp Central API currently does not transfer attachments by default. We expect that to continue as the norm.

Specify Norms for Common Attachments Like Student Portraits (Implementer Suggestion) 

RFC Status: Open For Review and Comment

The Snapp Data Standard currently supports attachments and allows users to specify what the file represents. Implementers have suggested that Snapp provide standards and/or guidance for certain common types of attachments. For example, many scholarship applications request a portrait of a certain pixel dimension and similar.

This makes conceptual sense, but the Snapp team doesn't have a sense for the norms. Our recommendation for Snapp Data Standard v3.0 is to address this issue in documentation as non-normative guidelines for implementers, and revisit this issue based on feedback from this application cycle.

Use the School Entity (which contains NCES/CEEB Codes) vs. Free Text SchoolName Throughout (Implementer Suggestion)

RFC Status: Recommended, Open for Review and Comment

The Snapp Data Standard primarily uses an entity called School to signify a specific educational institution. The entity includes the option for an NCES code and/or a CEEB code in addition to a School Name, which allows unambiguous identification of a particular school. However, some entities, including the SimpleTranscript and GraduationInfo, simply allow for free-form entry of a school name.

This proposed change would change all references to School Names to the School entity.

Worth noting is that the SchoolName in the School entity is still a free-form text field with NCES code and CEEB code both optional. So, implementers that, for whatever reason, require free-form text can still use Snapp as flexibly as v2.0; this change simply supports (and implicitly encourages) implementers to be precise when indicating a school.

Evaluate Additional Support for Home Schooling (Implementer Suggestion)

RFC Status: Open for Review and Comment

The Snapp Data Standard v2.0 only contains light support for home schooling. This has been raised as a potential issue by implementers (e.g., because NCES code lists do not appear to have an option for homeschooling). The SchoolType enumeration has a "Home school" value, so it is currently possible to make the selection explicit.

This change would create additional support for home schooling in the standard (e.g., by specifying a placeholder NCES code and specific School Name value in the School Entity to indicate home schooling).

Evaluate Additional Support for Home Responsibilities (Implementer Suggestion)

RFC Status: Open for Review and Comment

The Snapp Data Standard v2.0 contains minimal support for indicating home responsibilities, but it forms a major part of a few implementers' selection criteria. Consider options for adding additional, structured support.

A lightweight approach might be as simple as adding values to the existing ActivityTypeList (which contains values such as "Athletics" and "Hobby" in addition to a general "Home and family responsibilities" item). Alternately, a new, optional 0-n type might be indicated. We will solicit comment during the RFC and consider inclusion in the next XSD draft. 

Consider Structuring the College Readiness Program Name (Implementer Suggestion)

RFC Status: Open for Review and Comment

The Snapp Data Standard v2.0 uses a free-form text field to capture the College Readiness Program name. However, implementation partners that use the CRP for eligibility require a structured list for the field to have value.

The Dell Scholars Program has a fairly extensive, structured list of many nationwide programs. Consider using that list as a starting point for an enumeration and supporting an Other / OtherCRP element pair.

If not implemented for v3.0, consider at least supporting a structured list in the UI and providing guidance in the data handbook/documentation.

References

• View ticket in the Scholar Snapp Data Standard JIRA Site (SSDS-5)

Add Adjusted Gross Income (Implementer Suggestion)

Add Option for Weighted or Unweighted GPA (Implementer Suggestion)