2021 11 schema update #305

mrshll1001 · 2021-11-09T12:07:07Z

PR made based on Planio-29617 as part of the housekeeping review and ahead of the SC meeting. This is for the changes to the schema only, documentation will be made in a separate pull request.

robredpath · 2021-11-09T12:50:18Z

schema/360-giving-schema.json

            "ZW"
          ],
-          "description": "The ISO Country Code of the location of this activity.",
+          "description": "The 2-character ISO Country Code of the location of this activity. Taken from [ISO_3166-1_alpha-2](https://www.iso.org/iso-3166-country-codes.html)",


I'm not sure why underscores are being used here - the name of the code is ISO 3166-1 alpha-2

Copied from the housekeeping doc. I'll amend.

robredpath · 2021-11-09T12:56:45Z

schema/360-giving-schema.json

            "null"
          ],
-          "description": "The latitude of a point location",
+          "description": "The latitude of a point location. Using [WGS 84](https://en.wikipedia.org/wiki/World_Geodetic_System) standard, for example 51.501502",


If one was being very pedantic, one might argue that this is a backwards-incompatible change because previously-allowed values are no longer allowed.

However, I find it incredibly unlikely that anyone is using anything other than WGS 84, so I doubt this is a real issue. I like the provision of an example.

thanks @robredpath I raised exactly this question in particular in a planio ticket - 30810 - as I believe this isn't a backwards incompatible change to the schema, but a clarification of guidance. Let me know what you think.

@KDuerden I agree - for all practical purposes, it's backward-compatible and so it's fine. I will buy, and eat, a hat if this change actually breaks anyone's use case.

The WGS 84 vs EPSG 4326 question is an even smaller nit to pick, but we might as well get it right. @Lathrisk will be able to tell us what to do.

Are there any comments about EPSG that have an impact on this PR or are they issues for separate consideration?

robredpath · 2021-11-09T12:57:30Z

schema/360-giving-schema.json

            "null"
          ],
-          "description": "A code referring to a geographical area, drawn from an established gazetteer. For example, the code for a local authority ward, or parliamentary constituency.",
+          "description": "A code referring to a geographical area, drawn from an established gazetteer such as the ONS Register of Geographic Codes in the UK. For example, the code for a local authority ward, or parliamentary constituency.",


robredpath · 2021-11-09T12:58:39Z

schema/360-giving-schema.json

        "streetAddress": {
          "type": "string",
-          "description": "Building number and street name.",
+          "description": "Recipient organisation address Building number and street name.",


The capital B on Building is grammatically incorrect with this new information prepended

(same for lines below)

Cheers Rob, this was following the Housekeeping doc and I did notice this. I'll amend appropriately.

robredpath · 2021-11-09T13:13:08Z

schema/360-giving-package-schema.json

        "issued": {
          "title": "Issued",
-          "description": "The date that this data package was issued.",
+          "description": "The date that this data package was issued. The date must be written as YYYY-MM-DD, or in full date-time format",


Could we link to JSON Schema's date-time format ?

I think this is reasonable.

We don't link to JSON schema's date formatting in any of the other parts of the schema that use this formatting so seems odd to do so in this case only. We have field guidance on date and date-time, so I think that provides sufficient supporting information.

KDuerden · 2021-11-16T08:16:42Z

schema/360-giving-schema.json

            "ZW"
          ],
-          "description": "The ISO Country Code of the location of this activity.",
+          "description": "The 2-character ISO Country Code of the location of this activity. Taken from [ISO-3166-1-alpha-2](https://www.iso.org/iso-3166-country-codes.html)",


It was agreed to use link https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 rather than ISO link because ISO is not open.

KDuerden · 2021-11-16T08:18:21Z

schema/360-giving-schema.json

            "null"
          ],
-          "description": "A code referring to a geographical area, drawn from an established gazetteer. For example, the code for a local authority ward, or parliamentary constituency.",
+          "description": "A code referring to a geographical area, drawn from an established gazetteer such as the [ONS Register of Geographic Codes](https://data.gov.uk/dataset/389511fa-eb72-4657-a2ef-b3c982ec4c0e/register-of-geographic-codes-april-2020-for-the-united-kingdom) in the UK. For example, the code for a local authority ward, or parliamentary constituency.",


Do we know if that link from ONS will persist? As it is time specific I would be more comfortable using a wiki link to generic information - eg https://en.wikipedia.org/wiki/ONS_coding_system

I'd second using a Wiki link, I can modify this PR if needed

The canonical link for the Register of Geographic Codes would be this one: https://geoportal.statistics.gov.uk/datasets/register-of-geographic-codes-june-2021-for-the-united-kingdom/about - but that changes every time they publish a new one, and the links are likely to change (plus to geoportal is a slightly rubbish js-heavy site so it's never 100% links will work anyway). So wiki probably makes sense.

KDuerden · 2021-11-22T16:46:57Z

schema/360-giving-schema.json

        "streetAddress": {
          "type": "string",
-          "description": "Building number and street name.",
+          "description": "Recipient organisation address building number and street name.",


I think these fields are shared by Recipient and Funder organisation? If so, these need to be edited to removed 'Recipient from the start of all descriptions - so it will be generic.

KDuerden · 2021-11-22T16:47:14Z

schema/360-giving-schema.json

        "addressLocality": {
          "type": "string",
-          "description": "City or town.",
+          "description": "Recipient organisation address city or town.",


Remove Recipient

KDuerden · 2021-11-22T16:47:23Z

schema/360-giving-schema.json

        "addressRegion": {
          "type": "string",
-          "description": "County",
+          "description": "Recipient organisation address county",


Remove Recipient

KDuerden · 2021-11-22T16:47:37Z

schema/360-giving-schema.json

        "addressCountry": {
          "type": "string",
-          "description": "Country",
+          "description": "Recipient organisation address country",


Remove Recipient

KDuerden · 2021-11-22T16:47:49Z

schema/360-giving-schema.json

        "postalCode": {
          "type": "string",
-          "description": "Postal code (please try and provide a post code whenever possible)",
+          "description": "Recipient organisation address postal code.",


Remove Recipient

KDuerden

I've checked these changes and I'm happy with them. I'm approving this in my capacity as member of 360Giving team, as the first stage in PATCH approval process, which requires sign off from 360Giving team and a member of the Stewardship committee.

mrshll1001 requested review from KDuerden, drkane, robredpath and stevieflow November 9, 2021 12:07

robredpath reviewed Nov 9, 2021

View reviewed changes

mrshll1001 requested a review from robredpath November 11, 2021 09:08

KDuerden reviewed Nov 16, 2021

View reviewed changes

mrshll1001 mentioned this pull request Nov 16, 2021

2021-11 Documentation Update #306

Merged

KDuerden reviewed Nov 22, 2021

View reviewed changes

Matt Marshall added 6 commits November 23, 2021 10:30

Corrected link to ISO 3166-1-alpha-2

8219942

Modified link to ONS coding system

3b493c0

Removed recipient specific language from address component definitions

86c48d2

Remove link to JSON schema documetnation in package schema for date-time

8656c43

Added descriptions for various fields

42c3126

Updated description of FundingOrg:Location

e335bb6

KDuerden approved these changes Nov 24, 2021

View reviewed changes

Merge branch 'master' into 2021-11-schema-update

baf70f4

mrshll1001 merged commit d1092f6 into master Dec 10, 2021

mrshll1001 deleted the 2021-11-schema-update branch December 10, 2021 12:50

neelima-j mentioned this pull request Mar 31, 2025

date fields are showing as "text" in the auto-generated tables. #298

Closed

2021 11 schema update #305

2021 11 schema update #305

Uh oh!

Conversation

mrshll1001 commented Nov 9, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KDuerden left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants