PATCH: Add human readable currency names, remove out of date JSON Table Schema file and add unique id for schema files

Standard
1

Hello,

The ODS and 360Giving staff teams are proposing 3 PATCH updates to the Standard, which add human-readable currency names, remove an out-of-date JSON Table Schema file, and add unique IDS for schema files. Details and links to the related pull requests are set out below.

Add human readable currency names

This PATCH adds titles to the existing Currency Codelist. This is a codelist which is managed externally by ISO 4217, which produces codes to represent currencies e.g. GBP for Pound Sterling. 360Giving performs validation on currencies by encapsulating this codelist in a csv file, which is managed as part of the Standard’s Github repository.

One of the benefits of codelist files is that while the data may contain the unambiguous code e.g. GBP, software such as Grantnav can parse that code’s associated “title” to present this in a more human-friendly manner. The 360Giving currency.csv codelist has lacked titles which would enable this feature, which this PATCH seeks to address (see Issue #349).

To address this issue, this PATCH adds the associated ISO 4217 titles to the currency.csv codelist file used in the Standard. This includes both “active codes” and “historical codes” which have been included in the 360Giving Standard’s codelist so far. The PATCH does not remove any codes, add new codes, or add titles to codes which lack them in ISO 4217. Further, it does not change the ordering of codes inside the codelist file itself.

Finally, this PATCH adds some minor formatting improvements to the codelist.csv file by wrapping each code and the titles in quotes (“”). This brings currency.csv in line with other 360Giving codelist files and makes it more robust by preventing parsing errors if titles or descriptions ever contain a comma.

The pull request in Github is PR #418.

Remove out of date JSON Table Schema file

This PATCH removes a vestigial and out-of-date JSON Table Schema file. Despite being non-canonical and not used for validation or for generating documentation, this file is protected by the governance policy. This means that we are required to follow the PATCH approval process to remove it, hence this notification.

Investigation into the use of this file (see Issue #407) indicated that it was an artefact from the very early days of the Standard, and was used to define the tabular serialisation before tools such as flatten-tool allowed all serialisations to be based on the canonical schemas.

The table schema file in question 360-summary-table-schema.json has not been updated since 2018 and has consequently lagged behind the canonical 360Giving Data Standard schema. This means it contradicts the canonical schemas and should be removed to avoid potential confusion.

The pull request in Github is PR #407.

Add unique id for schema files

This PATCH consists of some lightweight but impactful maintenance which brings the 360Giving schemas in line with JSON Schema best practices by adding unique identifiers for the schema files themselves. This does not affect the 360Giving Standard’s data models or the validation status of existing data.

JSON Schema is the technology used to define the 360Giving Standard and supports the technologies that perform validation on 360Giving data. JSON Schema supports $id properties, which act as identifiers for the schema files themselves. They are not to be confused with identifiers for grants, organisations, etc. in the Standard.

The $id property for each schema file consists of a URI which uniquely identifies the schema and also resolves to a location where that version of the schema can be retrieved. This allows for multiple things:

  1. Schemas are unambiguously identified. Without an $id property, tooling and systems which interact with the schema operate on a “de facto” version of the schema, which changes with each version. 360Giving’s Support Policy stipulates a commitment to support prior versions of the Standard in tooling, which makes uniquely identifying Schemas necessary.
  2. Tooling can become more efficient. Tooling such as the datagetter and the DQT fetch a fresh copy of the schema for each validation. Besides this inefficiency, Github recently announced updated rate limits for unauthenticated requests which affects our toolchain. Having schemas with unambiguous identifiers allows tools to fetch a copy of the schema and be confident that it hasn’t changed based on how the identifier uniquely identifies each version of the schema.
  3. Promotes interoperability with other standards. JSON Schemas are inherently interoperable, and schemas can reference each other by their identifiers. This allows 360Giving to support other Standards where they need to model a Grant, by giving them a dereferenceable unique identifier

The pull request in Github is PR #419.

In recognition of the low impact that PATCH changes can have on the whole Standard, if no objections are received within one week, the PATCH change will be considered approved.

Any questions, please post below.

Thank you

Marion

1 Like