Schools and Geographies Proposal

[darnjo]

The Schools and Geographies Subgroup has reached the point where its work can be written in the form of a Transport proposal, so here is a first draft for discussion. It rests on the subgroup's coverage analysis of the certification pool and on two motions from the 2026-08-21 call: CityGeoid and CountyOrParishGeoid as new Data Dictionary fields, and geospatial query capability for Web API Core 2.2.0. It follows the RCP template; when the group is ready it becomes a proposal pull request and receives an RCP number. The questions the subgroup still has to settle are at the end.

Status	DRAFT for discussion
Dependencies	Data Dictionary 2.2+ (Sections 2.1 and 2.2, additive; the presence rule of Section 2.2 in Data Dictionary 3.0); Web API Core 2.2.0 (Section 2.5)
Related	Schools and Geographies Subgroup; Universal Parcel Identifier (GEOID precedent); RCP-55 Organization and System Identifiers (authoritative and local identifier model)

Summary of Changes

• Adds two linking identifiers to the Property Resource, CityGeoid and CountyOrParishGeoid, carrying the U.S. Census GEOID for the values already sent in City and CountyOrParish. Additive; no existing field changes. Data Dictionary 2.2.
• Adds a School Resource, anchored on National Center for Education Statistics (NCES) identifiers, with a Schools expansion from the Property and Building Resources. Additive: the six existing school fields (ElementarySchool, MiddleOrJuniorSchool, HighSchool and their …District companions) stay and name the first school of each level; Data Dictionary 2.2. A later rule that the School Resource MUST be present whenever those fields are served is a new rule on existing fields and waits for Data Dictionary 3.0.
• Adds a geospatial query capability to Web API Core 2.2.0, the next minor version (Section 2.5): geo.distance and geo.intersects over Edm.GeographyPoint and Edm.GeographyPolygon, plus filter and sort on the linking identifiers.

Introduction

Listings carry geography and schools in free text and open enumerations. The subgroup's analysis of the certification pool (29 endorsed providers, Industry Aggregates) found geography close to externally standardizable – CountyOrParish matches the Census county file at 86.6%, StateOrProvince and Country are already being corrected to ISO 3166 through Fast Track – while school data is bare names with no external identifier, so a school cannot be resolved to one real school without at least its district and state. Two principles came out of that work and out of the subgroup's calls of 2026-07-17 and 2026-08-21: prefer external standards where they exist, and be additive rather than corrective – leave the values providers send today alone and add the identifier that makes them resolvable. The same pattern carries the Universal Parcel Identifier (Census GEOID), the Unique Licensee Identifier and the Organization and System Identifiers.

Section 1: Purpose

• Give City and CountyOrParish a resolvable external identity without changing the values providers transmit.
• Allow more than one school of each level to be attached to a listing, carry the school's district, level, type and grade span, and let a school's name change without disturbing the feeds that reference it.
• Anchor school identity on NCES identifiers so that one real school is one record, referenced by many listings and standardized once.
• Make geography and schools searchable and sortable through the Web API.

Section 2: Specification

Section 2.1: Geographic Linking Identifiers

Two fields are added to the Property Resource. Each carries the U.S. Census Bureau GEOID of the place or county the existing field names. A GEOID is a concatenation of FIPS codes, so the identifier carries the FIPS decomposition; it is the identifier family the Universal Parcel Identifier already uses.

Field	Type	Nullable	Max length	Definition
CityGeoid	String	Yes	7	The U.S. Census Bureau GEOID of the incorporated place or census-designated place named in City: the two-digit state FIPS code followed by the five-digit place code.
CountyOrParishGeoid	String	Yes	5	The U.S. Census Bureau GEOID of the county or county equivalent named in CountyOrParish: the two-digit state FIPS code followed by the three-digit county FIPS code.

Rules:

• The identifiers are additive. City, CountyOrParish, StateOrProvince and PostalCode keep their current definitions and values; nothing in this section requires a provider to change them.
• When CityGeoid is present, its first two digits MUST equal the FIPS state code of the StateOrProvince value; the same holds for CountyOrParishGeoid. When both identifiers are present, their first two digits MUST match.
• A GEOID MUST be one that exists in the Census reference RESO publishes (Section 2.3). A provider MUST NOT invent an identifier for a place the reference lacks; the field is left null and the human-readable value stands.
• StateOrProvince and PostalCode receive no companion field: the state is enforced to ISO 3166-2 through Fast Track mappings, and the ZIP Code is already the USPS identifier.
• Outside the United States the fields are null. A companion identifier for other national gazetteers is out of scope for this version.

Naming: the fields are spelled CityGeoid and CountyOrParishGeoid. GEOID is the Census Bureau's single term for its geographic identifier, so under the Data Dictionary's PascalCase rule for acronyms it is one word with one capital, as Ansi in GrossLivingAreaAnsi, Leed in LeedCertificationLevel and Nces in NcesSchoolId, not a Geo base with RESO's Id suffix (see Appendix C). The subgroup's motion of 2026-08-21 recorded the names as CityGeoId and CountyOrParishGeoId; the spelling here applies the convention to that motion. The display names are City Geoid and County Or Parish Geoid.

Example, a listing in Colorado Springs, El Paso County, Colorado:

{
  "ListingKey": "12345",
  "City": "Colorado Springs",
  "CityGeoid": "0816000",
  "CountyOrParish": "El Paso",
  "CountyOrParishGeoid": "08041",
  "StateOrProvince": "CO",
  "PostalCode": "80903"
}

Section 2.2: School Resource

A School is a top-level resource. RESO maintains the authoritative list of schools from the NCES reference (Section 2.3) and hosts it as a queryable School Resource, in the way it maintains the authoritative organization and system identifiers. A provider serves its own School Resource on the same model as the Organization and System resources of the Organization and System Identifiers proposal: each record has a local key (SchoolKey) and carries the well-known RESO identifier (SchoolId) when the school is in the authoritative list, and the provider MAY carry its own values on that record, such as the name its market uses. A provider MAY also host schools that are not in the authoritative list, identified under its own issuer, exactly as it hosts local organizations and systems. A listing references its schools through a Schools expansion; how a provider associates listings with schools is its own concern, there is no join resource in this version, and a consumer that wants a listing's schools calls $expand=Schools. The subgroup discussed on 2026-08-21 whether the new structure should replace the flattened school fields and had not chosen between a resource and a shape. This draft keeps the existing fields and adds the resource beside them (see the coexistence rule below), and takes the resource form because school identity is shared across listings and the record must be reachable and updatable on its own. The shape form is recorded in Appendix A.

Field	Type	Nullable	Max length	Lookup	Definition
SchoolKey	String	No	255		The unique local key of the school record. The key of the resource.
SchoolId	String	Yes	255		The well-known RESO identifier of the school, when applicable: a URN in the form the Organization and System Identifiers proposal defines, with school as the identifier type, issued by RESO for a school in the authoritative list or by a provider for a school it hosts locally.
SchoolName	String	No	255		The name of the school.
SchoolLevel	String List, Single	No		SchoolLevel	The level of instruction the school provides.
SchoolType	String List, Single	Yes		SchoolType	The governance of the school: public, charter, magnet or private.
SchoolDistrict	String	Yes	255		The name of the local education agency the school belongs to.
NcesSchoolId	String	Yes	12		The NCES identifier of the school: the 12-digit Common Core of Data school ID for a public school or the 8-character Private School Survey ID for a private school.
NcesDistrictId	String	Yes	7		The NCES identifier of the school's local education agency: the 7-digit Common Core of Data LEA ID. Null for a private school.
StateSchoolId	String	Yes	50		The identifier the state education agency assigns to the school, as carried in the NCES Common Core of Data (the state school ID). Unique within the state.
StateDistrictId	String	Yes	50		The identifier the state education agency assigns to the school's local education agency, as carried in the NCES Common Core of Data (the state LEA ID). Unique within the state.
GradeLow	String	Yes	2		The lowest grade the school serves, as PK, KG or 1 through 13.
GradeHigh	String	Yes	2		The highest grade the school serves, as PK, KG or 1 through 13.
SchoolOfChoiceYN	Boolean	Yes			Whether attendance at the school is by choice or application rather than by assignment. A null value means the provider has not stated it.
ModificationTimestamp	Timestamp	No	27		The date and time the school record was last changed.
OriginatingSystemName	String	Yes	255		The name of the system from which the record originated.

SchoolLevel lookup values:

Lookup Value	Definition
Elementary	An elementary or primary school.
Middle Or Junior	A middle or junior high school.
High	A high or secondary school.
Combined	A school serving more than one of the levels above, such as K–8 or K–12.

SchoolType lookup values:

Lookup Value	Definition
Public	A school operated by a public local education agency.
Charter	A publicly funded school operating under a charter.
Magnet	A public school with a specialized curriculum drawing students beyond an attendance zone.
Private	A school not operated by a public agency.

Rules:

• SchoolKey MUST be unique within the system serving the resource. SchoolId and NcesSchoolId, when present, MUST each be unique across the system's School records: one real school is one record.
• A RESO-issued SchoolId resolves against the authoritative list; a provider-issued one resolves against that provider's School Resource. A provider that issues its own school identifiers MUST host the School records for them.
• For a public school (SchoolType Public, Charter or Magnet) with an NcesSchoolId, the first seven characters of NcesSchoolId MUST equal NcesDistrictId, because the CCD school ID is the LEA ID followed by the school code.
• StateSchoolId and StateDistrictId carry the identifiers the state assigns, which is what many districts, MLSs and school-locator services use day to day; the Common Core of Data lists both beside the NCES identifiers, so a record that carries an NcesSchoolId can be completed from the reference. They are unique only within a state, so a consumer joins on them together with the state, which the NCES identifier's first two digits or the listing's StateOrProvince supplies.
• GradeHigh MUST NOT be lower than GradeLow in the order PK, KG, 1 … 13. The subgroup listed a single GradesServed; this draft carries two fields so the span is comparable and sortable (Question 2).
• The Property Resource carries a Schools navigation to the School Resource, Collection(School), expanded with $expand=Schools. A listing MAY reference zero or more schools of any level. The Building Resource carries the same navigation.
• The existing fields ElementarySchool, ElementarySchoolDistrict, MiddleOrJuniorSchool, MiddleOrJuniorSchoolDistrict, HighSchool and HighSchoolDistrict on Property and Building stay as they are. Where a provider serves both, each existing field names the first school of its level among the listing's expanded schools, and the …District field that school's district; the ordering among a listing's schools of one level is the provider's, and where attendance is by choice the first school is one of the choices, not a ranking. From Data Dictionary 3.0, a provider that serves the existing school fields MUST also serve the School Resource and the Schools expansion, so that every named school resolves to an identified record; that is a new rule on existing fields and is why it waits for a major version.
• School boundaries and catchment assignment are out of scope. The resource states which schools serve a listing; how that was determined is the provider's.

Example, a listing served by two elementary schools and one high school:

GET https://api.example.com/Property('12345')?$expand=Schools($select=SchoolName,SchoolLevel,SchoolType,NcesSchoolId,GradeLow,GradeHigh)

{
  "@odata.context": "https://api.example.com/$metadata#Property/$entity",
  "ListingKey": "12345",
  "Schools": [
    { "SchoolKey": "S-001", "SchoolName": "Cheyenne Mountain Elementary", "SchoolLevel": "Elementary", "SchoolType": "Public", "NcesSchoolId": "080399000276", "GradeLow": "KG", "GradeHigh": "5" },
    { "SchoolKey": "S-002", "SchoolName": "Skyway Elementary", "SchoolLevel": "Elementary", "SchoolType": "Public", "NcesSchoolId": "080399000283", "GradeLow": "KG", "GradeHigh": "5" },
    { "SchoolKey": "S-003", "SchoolName": "Cheyenne Mountain High", "SchoolLevel": "High", "SchoolType": "Public", "NcesSchoolId": "080399000278", "GradeLow": "9", "GradeHigh": "12" }
  ]
}

(The NCES identifiers in the example are illustrative and are to be verified against the CCD before publication.)

Section 2.3: Reference Data

RESO publishes and maintains the reference data the identifiers resolve against, pinned to a dated snapshot so the standard does not depend on an agency's release cadence:

• The Census place and county files (GEOIDs and names) for CityGeoid and CountyOrParishGeoid.
• The NCES Common Core of Data school and LEA directories and the Private School Survey directory for NcesSchoolId and NcesDistrictId. From these RESO maintains the authoritative School list and hosts it as a queryable School Resource, the records a provider's SchoolId values resolve to.

Both sources are works of the United States government and, subject to confirmation of the posted terms of the exact datasets, are treatable as public domain. Each snapshot is versioned; certification tests use the snapshot current at the time of the test.

Section 2.4: Version Impact

• Section 2.1 adds fields and removes nothing: a minor Data Dictionary change, targeted at Data Dictionary 2.2.
• Section 2.2 adds a resource, an expansion and two lookups and changes no existing field: a minor Data Dictionary change, targeted at Data Dictionary 2.2. Its presence rule (the School Resource MUST accompany the existing school fields) adds a testing rule to existing elements, which is major under RESO's versioning rules and is targeted at Data Dictionary 3.0.
• Section 2.5 is a Web API Core change carried into Web API Core 2.2.0, the next minor version. It is a new capability with its own testing rules, not a new rule on an existing capability: a provider that passed 2.1.0 without geography-typed fields passes 2.2.0 unchanged, and a provider that already serves geography its own way is tested only if it declares the capability. As with any new capability, it carries DRAFT status in 2.2.0 until two providers have implemented it; because it is opt-in, nothing else in 2.2.0 waits on it.
• Path: the proposed elements go to the Fast Track Subgroup first and then to the Data Dictionary Workgroup, as the subgroup set on 2026-07-17.

Section 2.5: Geospatial Query in the Web API

The subgroup moved on 2026-08-21 to add geospatial query capability to Web API Core. It is part of this proposal: the capability is defined here and is added to Web API Core 2.2.0, independent of the Data Dictionary sections above.

OData 4.01 defines geospatial support through the geography primitive types Edm.GeographyPoint, Edm.GeographyLineString and Edm.GeographyPolygon (with their multi and collection forms) and the canonical functions geo.distance, geo.intersects and geo.length. Web API Core cites this material as background today; nothing in it is required or certified.

The capability is opt-in: a provider declares it and certifies against it:

• A provider that offers the capability serves the listing's location as a field of type Edm.GeographyPoint (the existing Latitude and Longitude fields stay as they are; the name of the point field is settled through the Data Dictionary naming convention, Question 6). Boundaries a provider chooses to publish, such as a school attendance area or an MLS area, are served as Edm.GeographyPolygon.
• The provider MUST accept geo.distance and geo.intersects in $filter and geo.distance in $orderby on its geography-typed fields, with geography literals in the OData form and SRID 4326 (WGS 84) as the coordinate reference system. OData leaves the unit of geo.distance to the coordinate reference system of the points (Part 2, Section 5.1.1.11.1); for SRID 4326 the geography implementations in general use return meters, and this endorsement requires meters so that a consumer can rely on it. A consumer working in miles converts: one mile is 1,609.344 meters, three miles 4,828.
• The provider MAY support geo.length and the multi and collection types. A geography function the provider does not support is rejected with 501 Not Implemented, as Web API Core already requires for unsupported query options.
• The linking identifiers of Section 2.1 MUST be filterable and sortable with eq and $orderby, which is the sorting capability the subgroup asked for on 2026-09-18.

Examples:

GET https://api.example.com/Property?$filter=geo.distance(Location, geography'SRID=4326;POINT(-104.8214 38.8339)') lt 4828&$orderby=geo.distance(Location, geography'SRID=4326;POINT(-104.8214 38.8339)')

Listings within three miles (4,828 meters) of a point, nearest first.

GET https://api.example.com/Property?$filter=geo.intersects(Location, geography'SRID=4326;POLYGON((-104.90 38.80,-104.75 38.80,-104.75 38.90,-104.90 38.90,-104.90 38.80))')

Listings inside a drawn boundary.

GET https://api.example.com/Property?$filter=CountyOrParishGeoid eq '08041'&$orderby=CityGeoid

Listings in El Paso County, Colorado, ordered by place.

Section 3: Certification

Testing rules are written in the specification stage, after the Workgroup approves the direction of this discussion. A first cut exists for the linking identifiers (format, state-prefix consistency with StateOrProvince, resolvability against the RESO-published Census snapshot, filter and sort) and for the School Resource (types and lookups, key and NcesSchoolId uniqueness, the LEA-prefix rule, state identifiers consistent with the NCES snapshot, grade-span order, $expand=Schools resolving by key, the first-school agreement between an existing field and the expanded schools, and from 3.0 the presence rule) and for the geospatial capability (geo.distance and geo.intersects accepted with SRID 4326 literals; 501 for unsupported functions) and comes with the proposal.

Section 4: Contributors

This draft was prepared for the RESO Schools and Geographies Subgroup from its call notes of 2026-07-17 and 2026-08-21 and the subgroup's coverage analysis. The contributor table is completed when the draft becomes a proposal.

Section 5: References

• U.S. Census Bureau – Geographic Identifiers (GEOIDs)
• U.S. Census Bureau – Gazetteer Files
• NCES Common Core of Data
• NCES Private School Survey
• ISO 3166 Country Codes
• RESO Universal Parcel Identifier
• RESO Data Dictionary 2.1 – Property Resource
• OData Version 4.01 Part 2: URL Conventions – Geo Functions
• OData Version 4.01 Part 3: CSDL – Simple Identifier
• RESO Style Guide and RESO Standards Development and Certification Policies and Procedures (Data Dictionary naming: PascalCase, acronyms as one word with one capital)
• Microsoft .NET Capitalization Conventions (acronyms of three or more letters take one capital)

Section 6: Appendices

Proposed Data Dictionary elements

The elements this endorsement defines are in Section 2.1 (the two linking identifiers) and Section 2.2 (the School Resource, the Schools expansion and the SchoolLevel and SchoolType lookups). Nothing is deprecated: the six existing school fields on Property and Building stay, related to the School Resource by the coexistence rule in Section 2.2.

Appendix A: The Shape Alternative

The same fields could be carried as a School complex type on Property.Schools, Collection(School), loaded with the listing rather than expanded. It needs no key and no endpoint, and it is the lighter form when schools are per-listing descriptors. It gives up shared identity: the same school appears once per listing, a name change is a change to every listing and the school cannot be retrieved or maintained on its own. The subgroup's analysis pointed at shared, NCES-keyed identity as the value, which is why the resource form leads.

Appendix B: Web API Geospatial Query

The geospatial query capability is defined in Section 2.5 and is carried into Web API Core 2.2.0.

Appendix C: Naming of the Identifiers

The Data Dictionary names its elements in PascalCase and treats an acronym as one word with only its first letter capitalized – MemberAor, ListAgentMlsId, Hvac – a rule the RESO Style Guide and the Standards Development and Certification Policies and Procedures set and that the .NET capitalization conventions also state for acronyms of three or more letters. GEOID is the Census Bureau's one-word term for its geographic identifier ("GEOID" in every Census publication), so it is cased Geoid, as Ansi in GrossLivingAreaAnsi, Leed in LeedCertificationLevel and Nces in NcesSchoolId. It is not a Geo base carrying RESO's Id suffix, which is what GeoId would assert. The display name follows the Style Guide's Title Case: City Geoid, County Or Parish Geoid. The machine names satisfy the OData Simple Identifier constraint.

Open Questions

1. Resource or shape (Section 2.2, Appendix A), and whether the existing school fields are kept beside it as this draft has it, or replaced later.
2. GradesServed (the subgroup's list) or GradeLow and GradeHigh (this draft): one string is easier to send, two fields are comparable.
3. Does the School Resource carry an address and coordinates (for the geospatial track), or is that left to the provider's own fields?
4. Which Data Dictionary version carries the identifiers and the resource (2.2 proposed) and the presence rule (3.0 proposed).
5. Who maintains the Census and NCES snapshots and on what cadence.
6. The name and placement of the Edm.GeographyPoint location field the geospatial capability needs (Property; Building; School too, if Question 3 is yes).
7. Whether a listing-to-school join resource (PropertySchools, on the pattern of the association resources) is wanted, now or later, for attributes that belong to the pair rather than to the school: the basis of assignment (zoned, choice, nearest) and distance. Without it, SchoolOfChoiceYN describes the school, not a listing's assignment to it.
8. Identifier naming: the subgroup's list has SchoolDistrictId and today's agenda floats NcesSchoolDistrictId; this draft uses NcesDistrictId beside NcesSchoolId, and StateSchoolId and StateDistrictId for the state-assigned identifiers, following the source-first form of NcesSchoolId.