Merge pull request #68 from DFE-Digital/elliotcm/add-docs

Add docs for countries/territories and HESA domiciles
DFE-Digital · Nov 25, 2022 · c73f348 · c73f348
2 parents 3b9d2e3 + 4b76c82
commit c73f348
Show file tree

Hide file tree

Showing 4 changed files with 145 additions and 7 deletions.
diff --git a/docs/lists_countries_and_territories.md b/docs/lists_countries_and_territories.md
@@ -0,0 +1,52 @@
+## Countries and territories
+
+- A mapping of ISO country/territory codes to country/territory names.
+- Postcode prefixes for the UK and Channel Islands grouped by country/territory.
+
+### `DfE::ReferenceData::CountriesAndTerritories::COUNTRIES_AND_TERRITORIES`
+
+```ruby
+require 'dfe/reference_data/countries_and_territories'
+```
+
+A mapping of ISO country/territory codes to country/territory names.
+
+Owner: Apply team.
+
+Users: Apply team.
+
+Source:
+https://github.com/DFE-Digital/apply-for-teacher-training/blob/78c9421d8582f63cfdec564b5c0677bfd787552c/config/initializers/countries_and_territories.rb
+https://github.com/alphagov/govuk-country-and-territory-autocomplete/blob/5214c44/dist/location-autocomplete-canonical-list.json
+
+Quality: Manually updated on an ad-hoc basis. Please submit a pull request if inaccuracies or omissions are found.
+
+This list is [autocomplete compatible](autocomplete_compatability.md).
+
+| Field  |  Type  |                       Purpose                       |
+| ------ | ------ | --------------------------------------------------- |
+| `id`   | string | The country or territory's ISO code                 |
+| `name` | string | The human-readable name of the country or territory |
+
+### `DfE::ReferenceData::CountriesAndTerritories::UK_AND_CI_POSTCODE_PREFIX_COUNTRIES`
+
+```ruby
+require 'dfe/reference_data/countries_and_territories'
+```
+
+Postcode prefixes for the UK and Channel Islands grouped by country/territory.
+
+Owner: Apply team.
+
+Users: Apply team.
+
+Source: https://github.com/DFE-Digital/apply-for-teacher-training/blob/78c9421d8582f63cfdec564b5c0677bfd787552c/app/lib/domicile_resolver.rb#L47-L59
+
+Quality: Manually updated on an ad-hoc basis. Please submit a pull request if inaccuracies or omissions are found.
+
+This list is NOT [autocomplete compatible](autocomplete_compatability.md).
+
+|   Field    |     Type     |                  Purpose                   |
+| ---------- | ------------ | ------------------------------------------ |
+| `id`       | string       | The human readable country/territory name  |
+| `prefixes` | string array | A list of postcode prefixes (letters only) |
diff --git a/docs/lists_hesa_domiciles.md b/docs/lists_hesa_domiciles.md
@@ -0,0 +1,75 @@
+## HESA domicile data
+
+- HESA-specific overrides for the countries and territories list.
+- HESA-specific overrides for ISO country/territory codes.
+- HESA codes for UK and Channel Islands countries/territories.
+
+### `DfE::ReferenceData::HESA::Domiciles::COUNTRIES_AND_TERRITORIES`
+
+```ruby
+require 'dfe/reference_data/hesa/domiciles'
+```
+
+HESA-specific overrides for the countries and territories list.  Delegates to `DfE::ReferenceData::CountriesAndTerritories::COUNTRIES_AND_TERRITORIES`.
+
+Owner: Apply team.
+
+Users: Apply team.
+
+Source: https://github.com/DFE-Digital/apply-for-teacher-training/blob/78c9421d8582f63cfdec564b5c0677bfd787552c/app/lib/domicile_resolver.rb#L29-L44
+
+Quality: Manually updated on an ad-hoc basis. Please submit a pull request if inaccuracies or omissions are found.
+
+This list is NOT [autocomplete compatible](autocomplete_compatability.md) as it
+contains a `nil` value.
+
+| Field  |    Type     |                       Purpose                       |
+| ------ | ----------- | --------------------------------------------------- |
+| `id`   | string      | The country or territory's ISO code                 |
+| `name` | string/null | The human-readable name of the country or territory |
+
+### `DfE::ReferenceData::HESA::Domiciles::SPECIAL_ISO_CODES`
+
+```ruby
+require 'dfe/reference_data/hesa/domiciles'
+```
+
+HESA-specific overrides for ISO country/territory codes.
+
+Owner: Apply team.
+
+Users: Apply team.
+
+Source: https://github.com/DFE-Digital/apply-for-teacher-training/blob/78c9421d8582f63cfdec564b5c0677bfd787552c/app/lib/domicile_resolver.rb#L3-L12
+
+Quality: Manually updated on an ad-hoc basis. Please submit a pull request if inaccuracies or omissions are found.
+
+This list is NOT [autocomplete compatible](autocomplete_compatability.md).
+
+| Field  |    Type     |          Purpose          |
+| ------ | ----------- | ------------------------- |
+| `id`   | string/null | The normal ISO code       |
+| `code` | string      | The special HESA ISO code |
+
+### `DfE::ReferenceData::HESA::Domiciles::CODES_FOR_UK_AND_CI`
+
+```ruby
+require 'dfe/reference_data/hesa/domiciles'
+```
+
+HESA codes for UK and Channel Islands countries/territories.
+
+Owner: Apply team.
+
+Users: Apply team.
+
+Source: https://github.com/DFE-Digital/apply-for-teacher-training/blob/78c9421d8582f63cfdec564b5c0677bfd787552c/app/lib/domicile_resolver.rb#L14-L27
+
+Quality: Manually updated on an ad-hoc basis. Please submit a pull request if inaccuracies or omissions are found.
+
+This list is NOT [autocomplete compatible](autocomplete_compatability.md).
+
+| Field  |    Type     |                Purpose                |
+| ------ | ----------- | ------------------------------------- |
+| `id`   | string/null | Human-readable country/territory name |
+| `code` | string      | HESA code                             |
diff --git a/lib/dfe/reference_data/countries_and_territories.rb b/lib/dfe/reference_data/countries_and_territories.rb
@@ -307,7 +307,7 @@ module CountriesAndTerritories
         },
         {
           id: :string,
-          prefixes: { schema: :string, kind: :array }
+          prefixes: { kind: :array, element_schema: :string }
         }
       )
     end

diff --git a/spec/lib/dfe/reference_data/countries_and_territories_spec.rb b/spec/lib/dfe/reference_data/countries_and_territories_spec.rb
@@ -1,11 +1,22 @@
 require 'dfe/reference_data/countries_and_territories'
 
-RSpec.describe DfE::ReferenceData::CountriesAndTerritories::COUNTRIES_AND_TERRITORIES do
-  it_should_behave_like 'a list of valid records'
-  it_should_behave_like 'a valid autocomplete-capable list'
+RSpec.describe DfE::ReferenceData::CountriesAndTerritories do
+  describe described_class::COUNTRIES_AND_TERRITORIES do
+    it_should_behave_like 'a list of valid records'
+    it_should_behave_like 'a valid autocomplete-capable list'
 
-  it 'contains mappings from ISO codes to country names' do
-    expect(described_class.one('AW').name).to eq('Aruba')
-    expect(described_class.one('UM-81').name).to eq('Baker Island')
+    it 'contains mappings from ISO codes to country names' do
+      expect(described_class.one('AW').name).to eq('Aruba')
+      expect(described_class.one('UM-81').name).to eq('Baker Island')
+    end
+  end
+
+  describe described_class::UK_AND_CI_POSTCODE_PREFIX_COUNTRIES do
+    it_should_behave_like 'a list of valid records'
+
+    it 'contains mappings from UK and Channel Island country/territory names to lists of postcode prefixes' do
+      expect(described_class.one('Wales').prefixes).to eq(['CF', 'SA'])
+      expect(described_class.one('Jersey').prefixes).to eq(['JE'])
+    end
   end
 end