Should the JSON encoding follow closely the abstract model?

[desruisseaux]

PROJJSON has been derived from Well Known Text (WKT) 2. However, WKT 2 was constrained by WKT 1 compatibility, which followed a model that predated ISO 19111. Consequently, PROJJSON diverges from what would be a CRS JSON derived from ISO 19111 abstract model. Examples of incompatible divergences are:

• In the names of elements.
• In the way that coordinate system types are identified (Should coordinate system subtypes be defined? #63).
• In the structure where scope and geographic/vertical/temporal extents are stored.
• In the structure of identifiers.

Between following the abstract model or preserving compatibility with PROJJSON, what should prevail?

Arguments in favor of PROJJSON compatibility

The main argument against following the OGC Topic 2 / ISO 19111 model is that it would be incompatible changes compared to PROJJSON, and the later is already used for 5 years.

We have two communities in the balance: the galaxy of projects around PROJ (admittedly large), and the rest of the geospatial community. Making life easier for one creates complications for the others. Some impacts of PROJJSON compatibility are discussed in the next sections. Whether they should be considered important or not has not been discussed yet.

Arguments in favor of CRS-JSON following the abstract model

Reduce the conceptual weight

Following closely the abstract model would make the specification simpler. The specification could give the general rules, keep the list of departures (special cases or exceptions to the rules) shorter, and provides some examples of CRS and coordinate operation definitions. By contrast, an encoding that diverges from the abstract model would need more explanations about how to map JSON elements to the abstract model. It would also require that users keep two models in mind: the abstract model and its encoding.

Reduce the dissemination of deviations from abstract model

If the encoding diverges from the abstract model, users will likely not look at the abstract specification and rather think that the encoding is the model. This confusion, where WKT 2 is interpreted as the model, is already observed on GitHub issues and mailing lists, and in PROJJSON itself (while the latter was maybe a conscious choice). The consequences are more limited with WKT 2 than it would be with JSON, because WKT 2 requires specialized libraries to be read and those libraries have a smaller scope than JSON or XML tools. But if OGC publishes CRS schema in JSON, because there is tools for generating automatically codes in various programming languages from XML and JSON schema, it is very likely that some users will use those tools for generating their codes and take the output as the state-of-the-art OGC model, as it happened 10 years ago with XML. The risk is larger for JavaScript developers, since they can read JSON documents directly as JavaScript objects (JSON is derived from JavaScript). If the JSON encoding is made closer to the abstract model (even if not identical, as some departures may be unavoidable), the divergences between those automatically generated codes and the abstract model will be smaller. Reducing those divergences is less cosmetic than it seems, because we have observed users attributing to Topic 2 / ISO 19111 issues that were actually WKT 2 shortcomings, without realizing that the encoding is not the model.

Convenience for developers using dynamic programming languages

Java and C# are semi-static and semi-dynamic programming languages. Their dynamic aspect makes possible to parse an XML or JSON document easily if the document structure matches the objects in the programming language. For example, a Java class could be defined as below (ignoring the complexity of GML particularities in this first example):

@XmlAccessorType(XmlAccessType.FIELD)
class CoordinateSystemAxis {
    String axisAbbrev;

    AxisDirection axisDirection;

    double minimumValue;

    // etc.
}

The @XmlAccessorType(XmlAccessType.FIELD) annotation instructs JAXB (a Java tool for parsing XML, but equivalent technologies exist for JSON) to automatically assign the values of axisAbbrev, axisDirection, minimumValue, etc. XML elements to the fields of the same names. It makes easy to read those documents with very few codes. In the simplest cases, nothing more than the above is needed. Even if there is some divergences between the XML/JSON encoding and the programmatic model, those divergences can still be handled if they are not too large. For example, if the names are different and if GML particularities must be supported:

@XmlRootElement(name = "CoordinateSystemAxis")
class Foo {
    @XmlJavaTypeAdapter(CS_AxisDirection.class)   // For handling the GML-way to encode XML
    @XmlElement(name = "axisDirection")
    AxisDirection bar;

    // etc.
}

However, above approach does not work anymore, or become complicated, if the encoding diverges too much from the programmatic model. This argument may apply to all dynamic or semi-dynamic programming languages. This argument is less relevant to fully static programming languages such as C/C++ since they need to write or generate codes for explicit assignments to those fields anyway.

[desruisseaux]

The question about PROJJSON implementations has been asked on the PROJ mailing list. We got the following replies:

• The spatialreference.org web site generates PROJJSON output.
• The rasterio's command line programs accept PROJJSON since 2021.
• Digital Coast Data Access Viewer (NOAA).
• Pyproj for custom CRS building.
• PROJJSON to WKT2 converter.
• Port in JavaScript of the above.

Some replies said that they extract information directly from PROJJSON, without using a geospatial library such as PROJ. This was expected, as one of the main arguments advanced in favor of PROJJSON was to allow exactly that:

• Spatialreference.org for axes info.
• Digital Coast Data Access Viewer (from my reading of the reply).
• PROJJSON to WKT2 converters (I presume, didn't verified).

Conversely, Pyproj seems to write CRS definitions directly to PROJJSON, then use PROJ for parsing that definition. In other words, PROJJSON is their API for creating custom CRS in PROJ.

When they are not extracting information directly from PROJJSON, the replies do not said explicitly which geospatial library they are using. My understanding is:

• As far as I know, spatialreference.org is based on PROJ.
• Since rasterio accepts PROJ4 key/value pairs, I presume that it is based on PROJ.
• Pyproj is a set of Python interfaces to PROJ.

[desruisseaux]

Analysis

My personal analysis of above results is that the current implementations fall in two categories:

1. Projects using PROJ as their geospatial library.
2. Projects extracting information directly from the JSON document, for example information about the axes.

For projects in category 1, if PROJ developers accept to add CRS JSON support, then PROJ users would automatically inherit this service with no effort on their side. I'm not aware of any software other than PROJ supporting PROJJSON, so PROJ may be the only geospatial library needing such upgrade. On the Java side, the project most likely to support a JSON encoding is probably Apache SIS, and that project has a strong focus on OGC/ISO standards.

Projects in category 2 may be broken if CRS JSON is incompatible with PROJJSON. Such compatibility problems happened in XML too, which addressed them with XSLT. For example, ESRI provided XSLT for converting documents from the old metadata schema to the new one (ISO 19115-3), and conversely. The same thing may be possible in JSON. However, there are many projects doing that and I'm not aware of agreement on a standard (contrarily to XML).

For many developers, the encoding is the model

Projects in category 2 show that developers leverage the fact that it is easy to extract information directly from a JSON document, without using a geospatial library. These developers are likely to structure their code in a way influenced by the structure of the JSON document. I think that only a minority of developers read the abstract model. It seems that a majority of developers get their understanding of ISO 19111 from the WKT definitions (or equivalent) that they are used to see. With JSON being easier to read than WKT, this phenomenon is likely to become more acute.

We can split this "encoding is the model" issue in two parts:

1. Do we agree that there is a risk that a CRS JSON encoding become the de facto CRS model?
2. If above is true, is it a problem?

In support of above point 1, the "Reduce the dissemination of deviations from abstract model" section in this issue's description gives the example of what happened with XML. It was the equivalent of what we are observing now with projects in category 2, only in a more convolved way (through classes compiled by JAXB).

On the "is it a problem" question, there are examples of overlapping between OGC standards caused in part by lack of familiarity with OGC Topic 2 / ISO 19111. For example, not everyone knew that Topic 2 covers coordinate operations in addition of CRS definitions. Since the coordinate operations are hard to miss when looking at the OGC Topic 2 / ISO 19111 document, is it tempting to conclude that people's understanding came from another source, maybe WKT definitions in contexts where most of them are about CRSs. Another example has been the difficulty to use Topic 2 in coverage specifications, caused in part by an understanding of the model which was not the Topic 2 intend, maybe for reasons similar than the previous example.

[desruisseaux]

Note: the question of positioning JSON as a possible replacement for GML is not covered in this thread. This is the topic of a separated issue: #64

[rouault]

where WKT 2 is interpreted as the model

Not sure why I write this, since all the above is about excuses covering a choice that you've already made, similarly to the 6+ month series of meetings about the apparent open choice of GeoTIFF vs netCDF for GGXF whereas it was already sealed. End result: nobody uses GGXF, wheras geodetic agencies produce GTG files now.
The deviations of WKT 2 compared to the model are very minor, for any practical purpose. WKT 2 comes from the same group than the one that produced Topic 2, or did I miss something ...? No, I didn't miss anything, since in PROJ I implemented both and can't recall any significant gap when ingesting WKT2 to the C++ classes and vice versa. The differences are only of interest for the most purists of purists...
Anyway there will be a new revision cycle for ISO 19111 in coming months, so the "pure" model might change, once again.
Such a loss of time arguing about the sex of angels and making standards that hardly anybody will read (adding a new one will just make https://xkcd.com/927/ even more true), as you rightfully mention

Besides 99% of WKT circulating in the wild being indeed CRS definitions, small hint why people only think that WKT only covers CRS and not coordinate operations... Its short name "WKT CRS", URL ( https://www.ogc.org/fr/publications/standard/wkt-crs/ ) and long name "Geographic information — Well-known text representation of coordinate reference systems ". You have to read more to know that coordinate operations are included. "CRS JSON" is about to have the same issue, if that's actually one... Conveying coordinate operations is already something that only advanced users will understand.

[desruisseaux]

The choice is not up to me. I expose arguments, and the choice will be up to the group. We talked with OGC Chief Standards Officer this morning about raising this question to a wider audience. We are considering organizing a special session on this topic at the next Member Meeting, while should be somewhere in Europe around March or April (the CRS SWG group has not yet decided if we will wait until then).

WKT 2 was produced by the same group than the one who produced OGC Topic 2 / ISO 19111, but with the constraint that a valid WKT 1 string shall be, as much as possible, also a valid WKT 2 string. There was also the constraint to be more compact than, e.g., a GML document. Those two constraints imposed significant deviations, e.g. in the way to define projection parameters, coordinate systems, and metadata. Note: I'm also an implementer who did the WKT 2 ↔ ISO 19111 mapping in Apache SIS.

On the "For many developers, the encoding is the model" topic, I'm aware that my arguments may be considered irrelevant by some. This is the reason why my above comment splits the question in two parts: 1) observation of what happened, is happening and may happen, and 2) does it matters? That latter question has not been decided yet by the CRS SWG (or wider OGC audience if we go with a special session).

[m-mohr]

The question about PROJJSON implementations has been asked on the PROJ mailing list. We got the following replies:

I think specifications are also implemementations, as such I add:

• STAC has adoptied PROJJSON in the commonly used projection extension, which has lead to downstream implementations.
• openEO has adopted PROJJSON in the API and process specifications, which has lead to downstream implementations.

Both these specification are very likely to become OGC community standards. Both are unlikely to adopt a OGC CRS JSON that is not 100% backward-compatible with PROJJSON.

[desruisseaux]

The current plan is to hold a special session (wider than CRS working group) dedicated to CRS JSON in the next OGC meeting, somewhere in Europe in March or April 2025. The issue of STAC and OpenEO CRS encoding can be raised during that session. I presume that which balance to chose between compatibility and consistency with OGC guidelines will be discussed there.

[m-mohr]

OGC MM are probably not the best place if you want to talk to the non-OGC community, too. As a non-member, I'm not sure how someone can raise that issue during an OGC MM, participation needs to be paid for afaik. Generally, OGC MM are potentially biased towards OGC initiatives, too.

[hobu]

OGC MM are probably not the best place if you want to talk to the non-OGC community

That the OGC community hasn't historically valued the needs of the non-OGC's community is why external-to-OGC implementation-forward standards like GeoJSON, PROJJSON, and to some degree, STAC, have taken hold.