Make NCES ID mandatory for US schools

Gemfile.lock

@@ -558,6 +558,7 @@ GEM
 PLATFORMS
   aarch64-linux
   arm64-darwin-24
+  arm64-darwin-25
   x86_64-linux
 
 DEPENDENCIES

app/controllers/api/schools_controller.rb

@@ -22,7 +22,10 @@ def create
         @school = result[:school]
         render :show, formats: [:json], status: :created
       else
-        render json: { error: result[:error] }, status: :unprocessable_entity
+        render json: {
+          error: result[:error],
+          error_types: result[:error_types]
+        }, status: :unprocessable_entity
       end
     end
 

app/jobs/school_import_job.rb

@@ -128,7 +128,10 @@ def build_school_params(school_data)
       creator_agree_authority: true,
       creator_agree_terms_and_conditions: true,
       creator_agree_responsible_safeguarding: true,
-      user_origin: 'experience_cs'
+      user_origin: 'experience_cs',
+      district_name: school_data[:district_name],
+      district_nces_id: school_data[:district_nces_id],
+      school_roll_number: school_data[:school_roll_number]
     }.compact
   end
 

app/models/school.rb

@@ -16,12 +16,21 @@ class School < ApplicationRecord
   validates :address_line_1, presence: true
   validates :municipality, presence: true
   validates :country_code, presence: true, inclusion: { in: ISO3166::Country.codes }
-  validates :reference, uniqueness: { case_sensitive: false, allow_nil: true }, presence: false
-  validates :district_nces_id, uniqueness: { case_sensitive: false, allow_nil: true }, presence: false
+  validates :reference,
+            uniqueness: { conditions: -> { where(rejected_at: nil) }, case_sensitive: false, allow_blank: true, message: I18n.t('validations.school.reference_urn_exists') },
+            format: { with: /\A\d{5,6}\z/, allow_nil: true, message: I18n.t('validations.school.reference') },
+            if: :united_kingdom?
+  validates :district_nces_id,
+            uniqueness: { conditions: -> { where(rejected_at: nil) }, case_sensitive: false, allow_blank: true, message: I18n.t('validations.school.district_nces_id_exists') },
+            format: { with: /\A\d{12}\z/, allow_nil: true, message: I18n.t('validations.school.district_nces_id') },
+            presence: true,
+            if: :united_states?
+  validates :district_name, presence: true, if: :united_states?
   validates :school_roll_number,
-            uniqueness: { conditions: -> { where(rejected_at: nil) }, case_sensitive: false, allow_nil: true },
-            presence: { if: :ireland? },
-            format: { with: /\A[0-9]+[A-Z]+\z/, allow_nil: true, message: I18n.t('validations.school.school_roll_number') }
+            uniqueness: { conditions: -> { where(rejected_at: nil) }, case_sensitive: false, allow_blank: true, message: I18n.t('validations.school.school_roll_number_exists') },
+            format: { with: /\A[0-9]+[A-Z]+\z/, allow_nil: true, message: I18n.t('validations.school.school_roll_number') },
+            presence: true,
+            if: :ireland?
   validates :creator_id, presence: true, uniqueness: true
   validates :creator_agree_authority, presence: true, acceptance: true
   validates :creator_agree_terms_and_conditions, presence: true, acceptance: true
@@ -129,6 +138,14 @@ def should_format_uk_postal_code?
     country_code == 'GB' && postal_code.to_s.length >= 5
   end
 
+  def united_kingdom?
+    country_code == 'GB'
+  end
+
+  def united_states?
+    country_code == 'US'
+  end
+
   def ireland?
     country_code == 'IE'
   end

config/locales/en.yml

@@ -15,7 +15,12 @@ en:
   validations:
     school:
       website: "must be a valid URL"
+      reference: "must be 5-6 digits (e.g., 100000)"
+      reference_urn_exists: "URN number already exists"
+      district_nces_id: "must be 12 digits (e.g., 010000000001)"
+      district_nces_id_exists: "NCES ID already exists"
       school_roll_number: "must be numbers followed by letters (e.g., 01572D)"
+      school_roll_number_exists: "School roll number already exists"
     invitation:
       email_address: "'%<value>s' is invalid"
   activerecord:

db/migrate/20251208134354_change_reference_and_nces_id_indexes_to_partial.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class ChangeReferenceAndNcesIdIndexesToPartial < ActiveRecord::Migration[7.2]
+  def change
+    # Convert reference (UK URN) index to partial index
+    # This allows rejected schools to release their URN for reuse
+    remove_index :schools, :reference
+    add_index :schools, :reference, unique: true, where: 'rejected_at IS NULL'
+
+    # Convert district_nces_id (US NCES ID) index to partial index
+    # This allows rejected schools to release their NCES ID for reuse
+    remove_index :schools, :district_nces_id
+    add_index :schools, :district_nces_id, unique: true, where: 'rejected_at IS NULL'
+  end
+end
+

lib/concepts/school/operations/create.rb

@@ -11,6 +11,8 @@ def call(school_params:, creator_id:)
       rescue StandardError => e
         Sentry.capture_exception(e)
         response[:error] = response[:school].errors
+        response[:error_types] = response[:school].errors.details
+
         response
       end
 

lib/tasks/seeds_helper.rb

@@ -16,15 +16,23 @@ module SeedsHelper
   def create_school(creator_id, school_id = nil)
     School.find_or_create_by!(creator_id:, id: school_id) do |school|
       Rails.logger.info 'Seeding a school...'
+      country_code = Faker::Address.country_code
       school.name = Faker::Educator.secondary_school
       school.website = Faker::Internet.url(scheme: 'https')
       school.address_line_1 = Faker::Address.street_address
       school.municipality = Faker::Address.city
-      school.country_code = Faker::Address.country_code
+      school.country_code = country_code
       school.creator_id = creator_id
       school.creator_agree_authority = true
       school.creator_agree_terms_and_conditions = true
       school.creator_agree_to_ux_contact = true
+      # Country-specific required fields
+      school.reference = format('%06d', rand(100_000..999_999)) if country_code == 'GB'
+      if country_code == 'US'
+        school.district_nces_id = format('%012d', rand(10**12))
+        school.district_name = Faker::Address.community
+      end
+      school.school_roll_number = "#{rand(10_000..99_999)}#{('A'..'Z').to_a.sample}" if country_code == 'IE'
     end
   end
 

spec/concepts/school/create_spec.rb

@@ -10,6 +10,7 @@
       address_line_1: 'Address Line 1',
       municipality: 'Greater London',
       country_code: 'GB',
+      reference: '100000',
       creator_agree_authority: true,
       creator_agree_terms_and_conditions: true,
       creator_agree_to_ux_contact: true,

spec/factories/school.rb

@@ -7,6 +7,7 @@
     address_line_1 { 'Address Line 1' }
     municipality { 'Greater London' }
     country_code { 'GB' }
+    sequence(:reference) { |n| format('%06d', 100_000 + n) }
     school_roll_number { nil }
     creator_id { SecureRandom.uuid }
     creator_agree_authority { true }

spec/features/admin/schools_spec.rb

@@ -79,7 +79,7 @@
 
     describe 'when the school is in the United States and has a postal code' do
       before do
-        school.update(country_code: 'US', postal_code: '90210')
+        school.update(country_code: 'US', postal_code: '90210', district_name: 'Some District', district_nces_id: '010000000001', reference: nil)
         get admin_school_path(school)
       end
 

spec/features/school/creating_a_school_spec.rb

@@ -19,6 +19,7 @@
         address_line_1: 'Address Line 1',
         municipality: 'Greater London',
         country_code: 'GB',
+        reference: '100000',
         creator_agree_authority: true,
         creator_agree_terms_and_conditions: true,
         creator_agree_to_ux_contact: true,

spec/jobs/school_import_job_spec.rb

@@ -17,15 +17,19 @@
           address_line_1: '123 Main St',
           municipality: 'Springfield',
           country_code: 'US',
-          owner_email: '[email protected]'
+          owner_email: '[email protected]',
+          district_name: 'Some District',
+          district_nces_id: '010000000001'
         },
         {
           name: 'Test School 2',
           website: 'https://test2.example.com',
           address_line_1: '456 Oak Ave',
           municipality: 'Boston',
           country_code: 'US',
-          owner_email: '[email protected]'
+          owner_email: '[email protected]',
+          district_name: 'Other District',
+          district_nces_id: '010000000002'
         }
       ]
     end
@@ -124,7 +128,9 @@
             'address_line_1' => '123 Main St',
             'municipality' => 'Springfield',
             'country_code' => 'us',
-            'owner_email' => '[email protected]'
+            'owner_email' => '[email protected]',
+            'district_name' => 'Some District',
+            'district_nces_id' => '010000000001'
           }
         ]
       end