Merge pull request #356 from ThreeSixtyGiving/location-scope-update

Location scope update

codelists/locationScope.csv

@@ -0,0 +1,8 @@
+Code,Title,Description
+GLS010,Global,"The location scope is global."
+GLS020,Supranational,"The location scope is a supranational region or continent."
+GLS030,National,"The activity scope covers a country, as defined by ISO 3166."
+GLS040,Subnational region,"The activity scope covers a first-level subnational administrative area."
+GLS050,Local authority,"The activity scope covers a second-level subnational administrative area."
+GLS060,Local area,"Location scope covers a small area."
+GLS099,Undefined,"The location scope is undefined."

documentation/guidance/location-guide.md

@@ -3,19 +3,22 @@
 ## Why is location data important?
 Location data helps users to understand where organisations are based or activities are happening, which helps to build a more complete picture of where funding is going geographically.
 
-Finding out where in the UK grants go is a key question that 360Giving data can be used to answer, but this is only possible when good quality and consistent location data - also known as geodata - is shared. 
+Finding out where in the UK grants go is a key question that 360Giving data can be used to answer, but this is only possible when good quality and consistent location data – also known as geodata – is shared. 
 
-Location is not one of the [ten core fields](https://standard.threesixtygiving.org/en/latest/guidance/plan-the-process/#decide-what-information-to-share), so the 360Giving Data Standard does not require geodata to be included. However, location information is so useful that we do recommend including it whenever possible. When data also includes geographic codes, it makes the data more comparable, and allows the data to be visualised in maps or analysed alongside other datasets.
+Location is not one of the [ten core fields](https://standard.threesixtygiving.org/en/latest/guidance/plan-the-process/#decide-what-information-to-share), so the 360Giving Data Standard does not require geodata to be included. However, location information is so useful that we do recommend including it whenever possible. When data also includes geographic codes, it makes the data more comparable, and allows the data to be visualised in maps or analysed alongside other datasets such as Indices of Multiple Deprivation.
 
 ## The basics
-The 360Giving Data Standard includes a range of ways to describe locations which are split into three types of fields: recipient, funder and beneficiary location. 
+The 360Giving Data Standard includes a range of ways to describe locations which are split into four types of fields: recipient, funder and beneficiary location, and location scope. 
 
 - **Recipient location** is where the recipient of a grant is based.
 - **Funder location** is where the funder of a grant is based.
-- **Beneficiary location** is where the funded work is being delivered or the people who access the funded work are based. 
+- **Beneficiary location** is where the funded work is being delivered or the people who access the funded work are based.
+- **Location scope** is the geographical scope of the funded work.
 
 Recipient, funder and beneficiary locations can be shared in the form of place names and geographic codes. Recipient and funder locations can also be shared in the form of an address.
 
+Location scope is shared in the form of codes from a codelist.
+
 ### About geographic codes
 A geographic code, or geocode, is a unique identifier that represents a location or geographic object. These geocodes allow geographic entities to be distinguished from each other and provide a more consistent way to identify a place than using the location name.
 
@@ -27,14 +30,19 @@ Whenever possible, geocodes should be shared by funders publishing on 360Giving
 
 **Types of geographic codes**
 
-**Country codes** - two-letter country codes taken from <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2" target="_blank">ISO_3166-1_alpha-2.</a> For example the code for the United Kingdom is **GB**, the code for Spain is **ES**.
+**Country codes** - two-letter country codes taken from <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2" target="_blank">ISO_3166-1_alpha-2</a> codelist. For example the code for the United Kingdom is **GB**, the code for Spain is **ES**.
 
 **ONS codes** - nine character codes managed by the <a href="https://en.wikipedia.org/wiki/ONS_coding_system" target="_blank">Office for National Statistics</a> which describe a wide range of geographical areas in the UK - including the four nations of the UK, regions in England, local authority areas, electoral wards and <a href="https://www.ons.gov.uk/methodology/geography/ukgeographies/censusgeography#output-area-oa" target="_blank">Census output areas.</a> 
 
 **Postal Codes** - full or partial postal codes associated with a UK postal address, or the equivalent codes used in other countries.
 
 **Latitude and Longitude** - coordinates that indicate a point on the globe, using the <a href="https://en.wikipedia.org/wiki/World_Geodetic_System" target="_blank">World Geodetic System.</a>
 
+### About Location scope codes
+Location scope codes are drawn from a codelist developed and managed by 360Giving which provides a short name, description and code for each Location scope value. These codes allow funders to share consistent information about the geographical scope relevant to each grant. For example the code GLS030 can be used to indicate that a grant is intended to have a national impact.
+
+See our [Codelist guide](../technical/codelists) for more detailed guidance on what codelists are and how they are used in the 360Giving Data Standard.
+
 ## Recipient organisation location
 **Recipient location** fields indicate where the grant recipient is based. It could be the location of a main office or branch, whatever is most appropriate for the grant. 
 
@@ -307,6 +315,86 @@ Using this method, there should be a row for each location, repeating the grant
     </table>
 </div> 
 
+
+```eval_rst
+.. _location-scope-guide:
+```
+
+## Location scope
+The 360Giving Data Standard allows funders to share a **Location scope** for each grant, which describes the geographical scope of the funded work.
+
+### About the codelist
+The codelist includes seven codes that should be used to describe the geographical scope of the funded work. The codes represent the different scopes a grant can have, from global to local areas. There is also a code to indicate when a grant has an undefined location, for example because the funded activity is online with no restrictions to who can access it.
+
+The location scopes were designed to align with international geographical divisions so the codelist can be applied consistently in all contexts. This means that there are areas grouped into a single scope in the codelist that have more sub-divisions in the UK.
+
+### Location scope codelist
+
+```eval_rst
+.. csv-table::
+   :file: ../../codelists/locationScope.csv
+   :header-rows: 1
+   :widths: auto
+```
+
+### Explanation of terms
+
+#### Global
+**Code to use:** GLS010
+
+**When to use this code:**
+Grants which have a global scope, meaning the area where the funded work is being delivered or the people who access the funded work are based all around the world.
+
+#### Supranational
+**Code to use:** GLS020
+
+**When to use this code:**
+Grants which have a scope which is a supranational region or continent, for example the European Union, North America or Africa.
+
+#### National
+**Code to use:** GLS030
+
+**When to use this code:**
+Grants which have a scope which covers a country, as defined by ISO 3166, for example the United Kingdom, France or Sierra Leone.
+
+#### Subnational region
+**Code to use:** GLS040
+
+**When to use this code:**
+Grants which have a scope which covers a first-level subnational administrative area, for example English Regions, Scotland, Wales or Northern Ireland.
+
+#### Local authority
+**Code to use:** GLS050
+
+**When to use this code:**
+Grants which have a scope which covers a second-level subnational administrative area, for example Districts (England), Principal Areas (Wales), Council Areas (Scotland), Local Government Districts (Northern Ireland), Metropolitan Counties, Non-Metropolitan Counties and Unitary Authorities (England).
+
+#### Local area
+**Code to use:** GLS060
+
+**When to use this code:**
+Grants which have a scope which covers a small area below local authority level, for example a Ward, MSOA, LSOA, parish, town, village, estate or park.
+
+#### Undefined
+**Code to use:** GLS099
+
+**When to use this code:**
+Grants which have a scope which is undefined, where location is not relevant, for example for online activities with no geographical focus.
+
+### Deciding which code to use
+The code descriptions and guidance provide examples of which codes to use to categorise grants’ location scope, focused on the UK context. If the grant you want to categorise could fit into more than one scope - for example the grant is funding a local pilot and UK-wide awareness raising campaign - label using the broadest applicable scope GLS030 (National).
+
+If the grant is funding activity in multiple different areas which are within a single scope – for example funding a project operating in two or more English Regions or activities which are England-wide – the location scope would be GLS040 (Subnational region).
+
+If you are not sure which category is appropriate for your grant, contact <[email protected]> for further guidance.
+
+### Guidance on using the codelist
+To start including **Location scope** codes in 360Giving data, add the Location scope field to the file, and then add the relevant code to your grants wherever possible.
+
+**Please note:** Only codes from the **Location scope** codelist should be included in the **Location scope** field. Do not add any other codes or text into this field. Be aware that these codes are case sensitive and should be reproduced exactly as they appear in the codelist.
+
+When it is not possible to provide a Location scope value for a grant, the field must be left blank.
+
 ## Funding organisation location
 In addition to providing location information for recipients and beneficiaries, the location of the funding organisation itself can be included, either using the address or location fields.
 

documentation/technical/codelists.md

@@ -39,11 +39,15 @@ These are intended to be representative, but not comprehensive.
 
 When a codelist is open it means that publishers may use a new code outside those in the codelist, if there is no appropriate code for them to use.
 
+```eval_rst
+.. _codelists-used:
+```
+
 ## The codelists used in the Standard
 
-There are six codelists used in 360Giving Data Standard.
+There are seven codelists used in 360Giving Data Standard.
 
-Two codelists, Currency and Country code are managed by ISO and the four remaining codelists are managed directly by 360Giving.
+Two codelists, Currency and Country code are managed by ISO and the five remaining codelists are managed directly by 360Giving.
 
 Managed externally
 
@@ -54,6 +58,7 @@ Managed by 360Giving
 
 * [GeoCode Type](#geocode-type)
 * [Regrant Type](#regrant-type)
+* [Location Scope](#location-scope)
 * [Grant to Individuals Purpose](#grant-to-individuals-purpose)
 * [Grant to Individuals Reason](#grant-to-individuals-reason)
 
@@ -105,25 +110,57 @@ The Geocode Type fields are part of objects which are an array. This means that
    :widths: auto
 ```
 
+```eval_rst
+.. _regrant-type:
+```
+
 ### Regrant Type
 
 A codelist with values to specify that a grant is intended for redistribution, broken down into seven types of regrant.
 
 The codes from this codelist can be published in the field **For Regrant Type**. The **For Regrant Type field** can only be included once with a single code per grant.
 
+For further explanation of how to use the Regrant Type codelist, including examples, read the [360Giving guide to regranting](../guidance/regranting).
+
 ```eval_rst
 .. csv-table::
    :file: ../../codelists/regrantType.csv
    :header-rows: 1
    :widths: auto
 ```
+
+```eval_rst
+.. _location-scope:
+```
+
+### Location Scope
+
+A codelist with values to specify a grant's geographical scope, broken down into seven levels.
+
+The codes from this codelist can be published in the field **Location Scope**. The **Location Scope field** can only be included once with a single code per grant.
+
+For further explanation of the location scope codelist, including examples, read the [360Giving guide to location data](../../guidance/location-guide/#location-scope).
+
+```eval_rst
+.. csv-table::
+   :file: ../../codelists/locationScope.csv
+   :header-rows: 1
+   :widths: auto
+```
+
+```eval_rst
+.. _grant-purpose:
+```
+
 ### Grant to Individuals Purpose
 
 A codelist with values to specify the purpose of the grant, in terms of what the funding will be used for. This codelist is intended for use in grants to individual recipients only.
 
 The codes from this codelist can be published in the field **To Individuals Details:Grant Purpose**.
 
-As the **To Individuals Details:Grant Purpose** field is an array. This means that multiple iterations of the field can be included when a publisher has more than one code to share per grant.
+The **To Individuals Details:Grant Purpose** field is an array. This means that when a grant has more than one purpose it is possible to include multiple codes in this field, separated by a semi-colon.
+
+**Please note:** This is the only codelist field that is an array. All other fields in the 360Giving Data Standard which use codelists only allow a single code per field.
 
 ```eval_rst
 .. csv-table:: 
@@ -132,6 +169,10 @@ As the **To Individuals Details:Grant Purpose** field is an array. This means th
    :widths: auto
 ```
 
+```eval_rst
+.. _grant-reason:
+```
+
 ### Grant to Individuals Reason
 
 A codelist with values to specify the reason that the grant was awarded to the recipient. This codelist is intended for use in grants to individual recipients only.
@@ -145,11 +186,15 @@ The codes from this codelist can be published in either of two fields, **To Indi
    :widths: auto
 ```
 
+```eval_rst
+.. _codes-how-to:
+```
+
 ## How to use codelists in 360Giving data
 
 Only codes from the codelists may be used. Any other code included in the data will result in invalid data. Please be aware that the codes are also case sensitive. Reproduce uppercase and lowercase letters in the codes correctly or the code will not be recognised and your data will be invalid.
 
-Only one code is allowed per field, and it is not possible to include comma separated lists of codes in a single field. If the field is an array (see [Reference](reference)) then you may use more than one code from the codelist in a spreadsheet by adding columns utilising the [Numbering](reference#numbering) technique, which is used elsewhere for describing multiple occurrences of e.g. Locations.
+Only one code is allowed per field, and it is not possible to include comma separated lists of codes in a single field. If the field is an array (see [Reference](reference)) then you may use more than one code from the codelist in a spreadsheet by adding columns utilising the [Numbering](numbering) technique, which is used elsewhere for describing multiple occurrences of e.g. Locations.
 
 Codes may not be applicable to all grants. When a grant has no relevant code, the field must be left blank. Do not use filler values such as N/A — a codelist field must only be populated with valid codes or left blank.
 
@@ -178,7 +223,7 @@ Regrant Type
         <td>360G-ExampleFdn-001</td>
 	<td>Contribution to pooled fund for charities supporting local residents</td>
 	<td>50000</td>
-	<td>FRG030</td>
+	<td>FRG040</td>
       </tr>
       <tr>
         <td>360G-ExampleFdn-002</td>
@@ -217,13 +262,13 @@ Grant To Individuals Codelists
         <td>360G-ExampleFdn-001</td>
 	<td>GTIR010</td>
 	<td>GTIR030</td>
-	<td>GTIP070</td>
+	<td>GTIP070;GTIP080</td>
       </tr>
       <tr>
         <td>360G-ExampleFdn-002</td>
 	<td>GTIR010</td>
 	<td>GTIR100</td>
-	<td>GTIP020</td>
+	<td>GTIP020;GTIP030;GTIP040</td>
       </tr>
     </tbody>
   </table>

documentation/technical/reference.md

@@ -49,7 +49,7 @@ The [Additional fields](additional-fields) section provides details of all other
 ```
 
 ### Meta Sheet
-We also provide a version of the <a href="../../_static/360-giving-schema-titles-with-meta-tab.xlsx">360Giving Spreadsheet Template with the Metadata template included</a>. The 'Meta' sheet may be used to publish authoritative metadata about the publisher, the file or dataset. The term we use for this is a 'data package'. The 'Meta' sheet includes sections for:
+We also provide a version of the <a href="../../_static/360-giving-schema-titles-with-meta-tab-2023.xlsx">360Giving Spreadsheet Template with the Metadata template included</a>. The 'Meta' sheet may be used to publish authoritative metadata about the publisher, the file or dataset. The term we use for this is a 'data package'. The 'Meta' sheet includes sections for:
 
 * The version of the 360Giving Schema used for the file
 * The title and description of the file
@@ -83,6 +83,7 @@ The main grants sheet also includes fields for including codes to indicate:
 
 * Grants intended for redistribution
 * The grant purpose and grant reason for grants to individuals
+* The location scope of the grant
 
 For further information read our [Guide to codelists](codelists).
 
@@ -266,6 +267,10 @@ Use the other sheets in the <a href="../../_static/summary-table/360-giving-sche
 
 For the Funding Org: Location and Recipient Org: Location there is also an extra column for the Identifier of the relevant Funding or Recipient Org.
 
+```eval_rst
+.. _numbering:
+```
+
 ##### Numbering
 
 You can describe multiple occurrences within the Grants sheet by having multiple columns. Use `:<num>:` instead of a `:`. This imitates JSON Pointer's approach.

schema/360-giving-schema.json

@@ -470,7 +470,7 @@
           "description": "A name for this location.",
           "weight": 1.1,
           "title": "Name"
-        },
+        },	
         "countryCode": {
           "type": [
             "string",
@@ -1409,6 +1409,13 @@
       "type": "string",
       "codelist": "regrantType.csv",
       "openCodelist": false
+    },
+    "locationScope": {
+	  "type": "string",
+	  "title": "Location Scope",
+	  "description": "A code referring to the location scope applicable to this grant. The value for this field should be drawn from the Location Scope codelist.",
+	  "codelist": "locationScope.csv",
+	  "openCodelist": false
     }
   }
 }