Skip to content

Commit

Permalink
Merge branch 'master' into 2021-11-schema-update
Browse files Browse the repository at this point in the history
  • Loading branch information
@mrshll1001
mrshll1001 authored Dec 10, 2021
2 parents e335bb6 + e8ee286 commit baf70f4
Show file tree
Hide file tree
Showing 5 changed files with 154 additions and 111 deletions.
87 changes: 61 additions & 26 deletions documentation/identifiers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@
Identifiers are an important part of any dataset. They let a computer uniquely identify and refer to specific grants, organisations, transactions and so-on.
Whilst a human being may be good at recognising that "Big Lottery Fund", "BLF", and "big-lottery-fund" all refer to the same organisation, computers cannot make this connection unless a unique identifier is provided.
Whilst a human being may be good at recognising that “R S P B”, “Royal Society for the Protection of Birds” and “The RSPB” all refer to the same organisation, computers cannot make this connection unless a unique identifier is provided.
```

360Giving asks you to give identifiers to any of the following elements that you include in your data:
The 360Giving Data Standard asks you to give identifiers to any of the following elements that you include in your data:

* [Grants](grant-identifier)
* [Organisations](organisation-identifier);
Expand All @@ -29,15 +29,15 @@ These go in an ```Identifier``` column alongside accessible text descriptions of

You may already have identifiers in your own data. For example, a number for each application or grant. You can use these existing **internal identifiers** as part of your published data.

*However,* because there might be an overlap between the internal identifiers you use, and the internal identifiers another funder uses, you need to add a **prefix** to avoid this possible clash.
However, to avoid overlap between the internal identifiers you use and the internal identifiers another funder uses, you need to add a **prefix**.

```eval_rst
.. admonition:: For example
If Indigo Trust have a grant called 'Grant27', and Nominet Trust also have a grant called 'Grant27' the two will get confused when combining the two datasets. But if, when publishing, each one adds a prefix, then we end up with two unique identifiers: '360G-indigotrust-Grant27' and '360G-Nominet-Grant27'
If Indigo Trust have a grant called 'Grant27', and the Dulverton Trust also have a grant called 'Grant27' the two will get confused when combining the two datasets. But if, when publishing, each one adds a prefix, then we end up with two unique identifiers: '360G-indigotrust-Grant27' and '360G-dulverton-Grant27'
```

For grants, and other identifiers particular to your organisation, you use can use a **360G prefix**.
For grants, and other identifiers particular to your organisation, you use can use a **360Giving prefix**.

For organisation identifiers, we strongly encourage you to use an officially recognised identifier for the organisation, following the [organisation identifier](organisation-identifier) guidance below.

Expand All @@ -48,10 +48,9 @@ For organisation identifiers, we strongly encourage you to use an officially rec

## Get your prefix

To register a prefix for your organisation see the [publisher guidance](https://www.threesixtygiving.org/support/publish-data).

All registered prefixes should start with 360G unless you have been advised otherwise by the support team.
To register a prefix for your organisation see the <a href="https://www.threesixtygiving.org/support/publish-data" target="_blank"> publisher guidance</a>.

All registered prefixes should start with 360G.
```eval_rst
.. _grant-identifier:
```
Expand All @@ -61,7 +60,7 @@ All registered prefixes should start with 360G unless you have been advised othe
To create your grant identifiers:

1. Make sure you have asked for a 360Giving prefix.
2. Look for an existing internal identifier given to your grants (for example, a sequential number assigned to each grant at the point of application). The important thing is that the identifier should be unique inside your organisation, so adding the prefix will make it unique across the whole world.
2. Look for an existing internal identifier given to your grants (for example, a sequential number assigned to each grant at the point of application). The important thing is that the identifier should be unique **inside your organisation**, so adding the prefix will make it unique across the whole world.
3. Add your 360Giving prefix in front of your identifier.

```eval_rst
Expand All @@ -76,6 +75,19 @@ To create your grant identifiers:

``360G-xyztrust-123_ABC``

```eval_rst
.. admonition:: Hint
If you do not have a unique grant reference to use, or the ones you have should not be shared in open data due to privacy or security issues, then you will need to create an identifier for each grant.
If you need to create identifiers you can use sequential numbers. Also including the year in which the grant was awarded helps to group the grants and makes it possible to restart the sequential numbers at the beginning of each year.
You can use any reference you choose as long as it is unique within your organisation. The 360Giving prefix will then be added to make the identifier globally unique.
```



```eval_rst
.. _organisation-identifier:
```
Expand All @@ -92,22 +104,22 @@ There are many different kinds of organisations that give, receive or benefit fr
* Schools, universities and other educational establishments
* Individuals

Most organisations (with the exception of unregistered voluntary and community groups) have some sort of official registration number that can be used as a unique identifier and used to look up their details from an official registers or public list.
Most organisations (with the exception of unregistered voluntary and community groups) have some sort of official registration number that can be used as a unique identifier and used to look up their details from an official register or public list.

There are two parts to an organisation identifier:

* **A list code**: a prefix that describes the list the identifier is taken from.
* **An identifier** taken from that list.

In 360Giving data we ask publishers to use a list code prefix taken from the [org-id list locator](http://org-id.guide/). This provides an open, maintained list of codes for many different lists around with world, giving a way to identify almost any organisation.
In 360Giving data we ask publishers to use a list code prefix taken from the <a href="https://org-id.guide/" target="_blank"> org-id list locator</a>. This provides an open, maintained list of codes for many different lists around with world, giving a way to identify almost any organisation.

```eval_rst
.. admonition:: For example
A charity registered in England and Wales with the Charity Commission of England and Wales, with the charity number '1070468' will use a list code prefix of ``GB-CHC``.
A charity registered in England and Wales with the Charity Commission of England and Wales, with the charity number '1164883' will use a list code prefix of ``GB-CHC``.
This gives an unique organisation identifier of ``GB-CHC-1070468``
This gives an unique organisation identifier of ``GB-CHC-1164883``
```

Expand All @@ -127,7 +139,7 @@ Some organisations have more than one identifier: they might be a charity **and*

If you have more than one type of identifier for an organisation recorded in your system, it will be necessary to pick which one to use when creating an Organisation identifier.

[org-id.guide](http://org-id.guide) ranks identifier lists by relevance and quality to help you pick the best identifier, based on what information you hold.
<a href="https://org-id.guide/" target="_blank"> org-id.guide</a> ranks identifier lists by relevance and quality to help you pick the best identifier, based on what information you hold.

```eval_rst
Expand All @@ -137,29 +149,52 @@ If you have more than one type of identifier for an organisation recorded in you
* Quality: are the identifiers in this list stable and linked to open, accessible contextual data, and can they be easily mapped to other identifiers.
```

Search on [org-id.guide](http://org-id.guide) for identifier sources for [UK organisations](http://org-id.guide/?structure=&coverage=GB&subnational=&sector=), [UK charities](http://org-id.guide/?structure=charity&coverage=GB&sector=), or [any other organisation type](http://org-id.guide/).
Search on <a href="https://org-id.guide/" target="_blank"> org-id.guide</a> for identifier sources for <a href="https://org-id.guide/?structure=&coverage=GB&subnational=&sector=" target="_blank"> UK organisations</a>, <a href="https://org-id.guide/?structure=charity&coverage=GB&sector=" target="_blank"> UK charities</a>, or <a href="https://org-id.guide/" target="_blank"> any other organisation type</a>.

### Commonly used identifier lists

The following identifier lists are often used in 360Giving publication.

* UK Company Number - [GB-COH](http://org-id.guide/list/GB-COH)
* Charity Numbers - [GB-CHC](http://org-id.guide/list/GB-CHC), [GB-SC](http://org-id.guide/list/GB-SC), [GB-NIC](http://org-id.guide/list/GB-NIC)
* Education establishments - [GB-EDU](http://org-id.guide/list/GB-EDU) and [GB-UKPRN](http://org-id.guide/list/GB-UKPRN)
* Local authorities - [GB-LAE](http://org-id.guide/list/GB-LAE) (England), [GB-LAS](http://org-id.guide/list/GB-LAS) (Scotland), [GB-PLA](http://org-id.guide/list/GB-PLA) (Wales)
* Mutual societies - [GB-MPR](http://org-id.guide/list/GB-MPR)
* HMRC-recognised charities - [GB-REV](http://org-id.guide/list/GB-REV)
* UK Company Number - <a href="https://org-id.guide/list/GB-COH" target="_blank">GB-COH</a>
* Charity Numbers - <a href="https://org-id.guide/list/GB-CHC" target="_blank">GB-CHC</a> (Eng & Wales), <a href="https://org-id.guide/list/GB-SC" target="_blank">GB-SC</a> (Scotland), <a href="https://org-id.guide/list/GB-NIC" target="_blank">GB-NIC</a> (Northern Ireland)
* Education establishments - <a href="https://org-id.guide/list/GB-EDU" target="_blank">GB-EDU</a> and <a href="https://org-id.guide/list/GB-UKPRN" target="_blank">GB-UKPRN</a>
* Local authorities - <a href="https://org-id.guide/list/GB-LAE" target="_blank">GB-LAE</a> (England), <a href="https://org-id.guide/list/GB-LAS" target="_blank">GB-LAS</a> (Scotland), <a href="https://org-id.guide/list/GB-PLA" target="_blank">GB-PLA</a> (Wales), <a href="https://org-id.guide/list/GB-LANI" target="_blank">GB-LANI</a> (Northern Ireland)
* Mutual societies - <a href="https://org-id.guide/list/GB-MPR" target="_blank">GB-MPR</a>
* HMRC-recognised charities - <a href="https://org-id.guide/list/GB-REV" target="_blank">GB-REV</a>

If you have a registered number from some other scheme, including overseas registrars, check the [org-id List Locator](http://org-id.guide/) for a list code prefix to use. If the list code prefix you need is not listed, [contact the support team](https://www.threesixtygiving.org/contact/).
If you have a registered number from some other scheme, including overseas registrars, check the <a href="https://org-id.guide/" target="_blank"> org-id List Locator</a> for a list code prefix to use. If the list code prefix you need is not listed, [contact the support team](https://www.threesixtygiving.org/contact/).

If you do not have any external registration numbers for the organisation, use your 360Giving prefix and any internal identifier you have for this organisation. For guidance about how to create unique internal identifiers, [contact the support team](https://www.threesixtygiving.org/contact/).
### Organisations without official registration numbers

Not all organisations have an official registration number to use, including small unregistered groups and individuals.

When there isn’t an official registration number for a recipient then you must provide an internal identifier instead, combining your 360Giving publisher prefix with any internal identifier you have for this organisation. This could be the organisation’s account record reference from your database.

If no account record reference is available, or there are security or privacy reasons that mean this information should not be published, the internal identifier can be created using the recipient name. The name can be turned into an identifier by removing the spaces between words or replacing spaces with dash or underscore.

```eval_rst
.. admonition:: Additional 360Giving fields for charity and company number
.. admonition:: Hint:
Example internal organisation identifiers using the publisher prefix and either an account reference from the organisation record or recipient name.
360Giving publisher prefix: 360G-XYZFunder
Recipient Org:Name: ABC Recipient
Account ID: 123456
Because 'Company Number' and 'Charity Number' are so important for analysing grantmaking in the UK, the 360Giving Standard includes additional fields these on their own (without the prefixes), to help users of the data.
If using the account ID: 360G-XYZFunder-123456
If using the recipient name: 360G-XYZFunder-ABC-Recipient
If you have these details, you should fill them in, **in addition to** providing the unique organisation identifier using the method above.
```

### Additional 360Giving fields for charity and company number

Because 'Company Number' and 'Charity Number' are so important for analysing grantmaking in the UK, the 360Giving Data Standard includes additional fields these on their own (without the prefixes), to help users of the data.




If you have these details, you should fill them in, **in addition to** providing the unique organisation identifier using the method above.
60 changes: 13 additions & 47 deletions documentation/index.md
View file
Original file line number Diff line number Diff line change
@@ -1,60 +1,25 @@
The 360Giving open data Standard
The 360Giving Data Standard
================================

**For open data to be really useful it has to follow an agreed format – *a standard* – so it can be easily compared with data from other organisations.**

For UK grantmakers, we have developed the 360Giving Standard for this purpose. We use this Standard to make sure that when all your data is linked to the 360Giving Registry, it can be easily “read” by different applications. This is how we make sure that when you use the data, the results that come up can be compared.
For UK grantmakers, we have developed the 360Giving Data Standard for this purpose. We use this standard to make sure that when all your data is linked to the [360Giving Data Registry](https://data.threesixtygiving.org/), it can be easily “read” by different applications. This is how we make sure that when you use the data, the information can be collated and compared.

The 360Giving data standard is:
* **Open data driven:** providing a common way to share transparent and interoperable information on grant-making.
* **Easy to use:** offering a simple spreadsheet format for publishing and consuming data, backed up by a structured data model, developer-friendly JSON serialisation, and conversion tools.
* **Comprehensive:** providing a 360 degree view of grantmaking. Describing the whole grantmaking process and supporting in-depth analysis of grants, grantees and beneficiaries.


## Templates

Two standard templates are available.

<div class="prose__section">
<section class="grid grid--two-columns">
<div class="grid__1">
<div class="prose-card prose-card--orange">
<div class="prose-card__content">
<img class="prose-card__image" src="_static/images/icon-spreadsheet.svg" alt="">
<div class="align-left">
<h3 class="prose-card__title"><a href="_static/summary-table/360-giving-schema-titles.xlsx">Spreadsheet Template (Excel)</a></h3>
<p class="prose-card__text">With user-friendly column headings, summary sheet and tabs for additional information. <br>
<strong><a href="templates-csv">(CSV versions also available.)</a></strong></p>
</div>
</div>
</div>
</div>
<div class="grid__1">
<div class="prose-card prose-card--orange">
<div class="prose-card__content">
<img class="prose-card__image" src="_static/images/icon-json.svg" alt="">
<div class="align-left">
<h3 class="prose-card__title">
<a href="reference/#json-format">360Giving JSON Schemas</a>
</h3>
<p class="prose-card__text">Provide the canonical definition of fields, as well as developer-friendly structure for working with 360Giving data.</p>
</div>
</div>
</div>
</div>
</section>
</div>
* **Open data driven:** providing a common way to share transparent and interoperable information on grantmaking.
* **Easy to use:** offering a simple spreadsheet format for publishing and consuming data, backed up by a structured data model, developer-friendly JSON serialisation, and conversion tools.
* **Comprehensive:** supporting in-depth analysis of grants, grantees, and beneficiaries to provide a 360 degree view of grantmaking.

Free support, helping you to publish and use 360Giving data is [available from our data support team](https://www.threesixtygiving.org/contact/).
Free support is <a href="https://www.threesixtygiving.org/contact/" target="_blank"> available from our support team</a> to help you to publish and use 360Giving data.

Full schema documentation is [available on the reference page](reference).
Full schema documentation is [available in the Reference section](reference).

## An open standard

The 360Giving data standard is an open standard. You can get involved in shaping the development of the standard through:
* [The 360 Discourse forum](https://forum.threesixtygiving.org): open for general discussions of the standard and proposed updates to the standard..
* [The issue tracker for the standard](https://github.com/ThreeSixtyGiving/standard/issues): for bug reports.
You can also contact the 360Giving data support team with your questions and suggestions.
The 360Giving Data Standard is an open standard. You can get involved in shaping the development of the standard through:
- <a href="https://forum.threesixtygiving.org/" target="_blank">The 360Giving forum</a>: open for general discussions about the standard and proposed updates.
- <a href="https://github.com/ThreeSixtyGiving/standard/issues" target="_blank">The issue tracker for the standard</a>: for bug reports.You can also contact the 360Giving support team with your questions and suggestions via <[email protected]>
- The [Governance and Revision Control](governance) section provides further information about how proposed updates to the 360Giving Data Standard are assessed and prioritised for implementation.

## Contents

Expand All @@ -67,6 +32,7 @@ You can also contact the 360Giving data support team with your questions and sug
data-protection
licensing
governance
getdata
sc-tor
using-data
```
Loading

0 comments on commit baf70f4

Please sign in to comment.