Use PROJJSON instead of WKT2:2019

[brendan-ward]

Resolves #95 based on associated discussion in #90.

This assumes #94 is added separately, allowing crs to be explicitly set to null.

This preserves the existing optional behavior and default if unspecified of OGC:CRS84. The default value and optional vs required status will be taken up in another PR.

This includes a minor formatting change of the table including crs but only the crs row changed content.

[brendan-ward]

Note change with respect to default value from "should" to "may", but the specific term should likely follow RFC 2119 with respect to these terms as per #26

Based on discussions around this default, it may instead be appropriate to use "must" in order to prevent ambiguity regarding an unset value.

[jorisvandenbossche]

What's the reason exactly to change this?

(I am not necessarily opposed to be clear, just don't directly remember that we discussed this)

[brendan-ward]

My intent was: "may" indicates reader may do so at their own peril (i.e., if you really don't care about ellipsoid); "should" indicates we recommend that the reader do so - which seems a bit strong when the ellipsoid of the long,lat coords is not defined.

[jorisvandenbossche]

"should" indicates we recommend that the reader do so - which seems a bit strong when the ellipsoid of the long,lat coords is not defined.

It seems the last discussion seems to lean towards assuming WGS84? (which is still not a well defined ellipsoid without an epoch, but OK ;))

[kylebarron]

Pending #93 (and #64, a discussion of whether to make the json schema definition a core part of the geoparquet metadata spec), we should decide whether we want the json schema to be updated along with or after associated spec PRs. In this case, we'd want the json schema to be updated so that the crs refers to the projjson json schema to allow for validating the structure of the crs json.

[kylebarron]

nit: apply JSON syntax highlighting to the block

Suggested change

	```
	```json

[brendan-ward]

we should decide whether we want the json schema to be updated along with or after associated spec PRs

I can update the schema here once #93 is merged; I was thinking that ideally both the spec and required changes to the schema would get updated within the same PR. It may be good for us to come up with a checklist of required / recommended updates to files here as part of making a PR to update the spec.

I'm assuming that we'd want to update the script for building an example parquet file after such PRs are in place, since that corresponds more directly to a specific version of the spec rather than intermediate changes within a PR, right?

[kylebarron]

It may be good for us to come up with a checklist of required / recommended updates to files here as part of making a PR to update the spec

👍 would be a great thing for a PR template.

I'm assuming that we'd want to update the script for building an example parquet file after such PRs are in place, since that corresponds more directly to a specific version of the spec rather than intermediate changes within a PR, right?

That's true, there are really three parts:

• Spec description in markdown
• Metadata description in JSON Schema
• Script to build parquet file

I don't have a strong opinion on when to update the Parquet script, but that could also be related to #40. For example, I think STAC spec developed entirely on a dev branch and only merged that into the main branch on each release? So when a member of the public visited the repo, they'd see the state of the last release by default instead of the current WIP state between releases.

[brendan-ward]

Note: The "However..." can be removed if we instead state above that

If CRS is not provided, then all coordinates in the geometry must use longitude, latitude based on the OGC:CRS84 CRS to store their data.

But without that, lacking a crs means that coordinates are in an unspecified CRS.

[cholmes]

I'm for removing the however and stating what it should be. Though perhaps we just say 'must use longitude, latitude with the WGS84 datum' to cover both OGC:CRS84 and EPSG:4326 (with axis order flipped).

[jorisvandenbossche]

+1 on removing the "however ..". So that if CRS is not available, readers can assume WGS84

[brendan-ward]

OGC:CRS84 official has probably frozen for > 10 years

Which form should we include here? The EPSG:4326 with lon,lat ordering as we have here as a proxy for what OGC:CRS84 would be if it wasn't frozen, since that is what users get if they use PROJ to get the PROJJSON, or the form that would represent the single-datum version? Or rather, were you just suggesting that we rephrase the note?

I think one of our goals in including it here is that at some point we can also make a recommendation for non-CRS aware tools that can safely assume they are producing OGC:CRS84 referenced data to copy / paste this json to their crs field (if we require crs or at least strongly recommend it in order to make geographic coordinates less ambiguous than now).

[rouault]

For non-CRS aware tools, perhaps we should recommend the simplest minimal reasonable form of OGC:CRS84 definition

{
    "type": "GeographicCRS",
    "name": "WGS 84 longitude-latitude",
    "datum": {
        "type": "GeodeticReferenceFrame",
        "name": "World Geodetic System 1984",
        "ellipsoid": {
            "name": "WGS 84",
            "semi_major_axis": 6378137,
            "inverse_flattening": 298.257223563
        }
    },
    "coordinate_system": {
        "subtype": "ellipsoidal",
        "axis": [
        {
            "name": "Geodetic longitude",
            "abbreviation": "Lon",
            "direction": "east",
            "unit": "degree"
        },
        {
            "name": "Geodetic latitude",
            "abbreviation": "Lat",
            "direction": "north",
            "unit": "degree"
        }
        ]
    },
    "id": {
        "authority": "OGC",
        "code": "CRS84"
    }
}

[cholmes]

Note there was a comment on this in #97 - #97 (comment) That's the 'require' PR, but this one should merge first so we can cut 0.4.0 release.

[brendan-ward]

Either one could theoretically go out as 0.4.0; per the discussion I thought the intent was to compare the optional PROJJSON with OGC:CRS84 default vs required PROJJSON, rather than them being additive. But I can certainly update this PR to address comments in #97 if we'd like to see this particular PR go out sooner.

[cholmes]

Sounds good. I think the plan was to aim for 0.4.0 without it - I organized the 0.4 milestone around that - and then to be sure to solve this for 0.5. Just to be sure to make iterative progress as it seemed like that one could take longer.

I think we targeted next week for the 0.4.0 release. I'm also not opposed to get this into 0.4 release with everyone happy, and just put up a discussion in #98 to help push it forward. So maybe see where that discussion is at on monday of next week, and if it's not fully resolved then it'd be great if you could clean up this PR and we push out 0.4

[jorisvandenbossche]

Maybe not that important for this PR (can be done in a follow-up as well), but what do people think about moving the details of what the CRS repr of OGC:CRS84 and how to recognize this to a separate section towards the bottom of this file? So here we focus on the basic explanation of this metadata fields

[jorisvandenbossche]

I would somehow stress here that what follows is really optional, as IMO it is perfectly fine for a non-CRS aware implementation to only handle files that have a "proper" CRS with EPSG:4326 or OGC:CRS84 id. Being able to detect other equivalent json CRS objects without this id seems rather like a corner case (and they can give a clear error that the CRS of the data is not recognized, as they will do for files with non-WGS84 crs anyway)

[cholmes]

+1 - I think it's ok to even just remove this section. Like perhaps add it to some 'best practices' type document, but not have it in the main spec.

[cholmes]

Looks good. I put in one small comment, but I'm also happy to merge this and then tackle that in a separate PR.

[cholmes]

I'm for removing the however and stating what it should be. Though perhaps we just say 'must use longitude, latitude with the WGS84 datum' to cover both OGC:CRS84 and EPSG:4326 (with axis order flipped).

[cholmes]

Is this ready to merge? It's looking good to me. Thanks for all your awesome work on this @brendan-ward (and everyone else reviewing / suggesting).

[brendan-ward]

The only thing outstanding is what part (if any) of the "OGC:CRS84 details" section to cut out or move to a different file (if so, where?).

[cholmes]

Ah, right. I think the whole OGC:CRS84 details section could move out.

I'd probably just do something simple like just make an 'additional-info.md' file that sits right next the spec, in the same folder, and puts the crs details in it, maybe also the example file above. It could expand out in time, could also evolve to live somewhere else, like become more of a guide to geospatial for non-geo people, help explain various aspects of the spec.

I think it's also ok to just merge this and then we can do that one as a separate PR. I'd be happy to work on it.

[jorisvandenbossche]

Ah, right. I think the whole OGC:CRS84 details section could move out.

Given that it was moved to an additional section at the bottom, for me it is also fine to keep it there for now (we can move it another file later, if we prefer that), in light of getting this PR merged.

EDIT: ah, so what you said in your last sentence ;)

I think it's also ok to just merge this and then we can do that one as a separate PR. I'd be happy to work on it.