RFC: Don't register a separate media type

[m-mohr]

JSON FG is meant to be an extension to GeoJSON, a primary goal seems to be that it's a drop-in replacement with added functionality.
The standard is mostly written in a way that a GeoJSON client can easily read JSON FG.
Unfortunately, this is not quite consistent when it comes to the planned new media type (and .jsonfg file extension).
Existing clients will have issues to identify GeoJSON if it's advertised as JSON FG.

The intended media type application/fg+json is not compatible in any way with the application/geo+json having in mind that many implementations just check equality of media type strings.

I'd like to propose to not register a separate media type for JSON FG and also remove the .jsonfg file extension.
Instead as media type application/geo+json or application/json shall be used and .json or .geojson should be used as file extensions.

This would greatly improve the compatibility with existing clients.

For example, all existing STAC clients I've checked of would not support reading the GeoJSON part of JSON FG due to the new media type. That will likely be the same in other ecosystems.

[cportele]

Meeting 2024-05-27: This is a good point. Whether a separate media type is helpful or not depends on the use case. A separate media type helps in a content negotiation scenario where an API can provide GeoJSON (without JSON-FG extension), JSON-FG (with or without the GeoJSON compatibility mode). In the case of a weblink with the "type" attribute, a GeoJSON media type would be more helpful for a GeoJSON-aware software (which does not know JSON-FG).

Since we cannot do both at the same time, the question which is which is the more important use case.

This would be simpler, if the GeoJSON media type would support parameters to express extensions, but this is not the case.

Additional input is welcome.

[m-mohr]

If servers support JSON FG and GeoJSON, what would be a reason to not deliver JSON FG by default so that content negotiation would be required?
Having that question in mind but not an obvious answer in mind, I'd say the compatibility is more important.

[cportele]

Meeting 2024-08-19:

We are leaning towards not registering a new media type. Clients can use to "conformsTo" member to determine that the content is JSON-FG.

However, this would require that we also allow to include non-WGS84 coordinates in "geometry" to conform to OGC API Features Part 2 when the GeoJSON geometry is requested in a non-WGS84 CRS.

We need to find a way that does not make the split between "geometry" and "place" even more complex/confusing. We should create a table that lists all the different cases and see, if we can provide guidance what to create when. Maybe this can be accommodated using additional API building blocks. Maybe we can use the "profile" query parameter, because all the variations are valid for the GeoJSON media type.

[cportele]

I think that we can and should use the profile query parameter in OGC API Features to distinguish the variations in the GeoJSON representation when requesting application/geo+json:

• profile=rfc7946: response conforms to the GeoJSON RFC; coordinates in "geometry" can be in another CRS, if this is part of the request (prior arrangement); no JSON-FG conformance class will be stated in "conformsTo" (if provided) and no "place" member.
• profile=jsonfg: response conforms to JSON-FG Core.
• profile=jsonfg-plus: same as jsonfg; in addition, if the "place" member of a feature is provided / not null a valid non-null "geometry" member will also be provided. This is the same as the current media type "application/fg+json; compatibility=geojson".

"rfc7946" should be the default since this is the current behavior, if "application/geo+json" is requested. Existing APIs may also continue to support the current draft media types for backwards compatibility.

We should add a discussion about this in the clause on media types.

In addition, JSON-FG should formally define the profiles and the values for the HTTP query parameter profile, that is, the relevant API building blocks. This could be in a separate requirements class with Web API as the standardization target type. APIs can include the associated conformance class in their conformance declaration, if they support JSON-FG.

[cportele]

Meeting 2024-09-30: @cportele will implement this in the current pull request.

[cportele]

Meeting 2024-11-25:

"rfc7946" should be the default since this is the current behavior, if "application/geo+json" is requested

This only applies, if the API supports that profile. If only JSON-FG is supported, the API will use another profile as the default.

[cportele]

@jerstlouis - To follow-up on our discussion in the call, the profile of the response will be expressed using a link with rel="profile" according to RFC 6906. This is what is currently specified in OGC API Features Part 5.

[m-mohr]

I'm not sure I understand how a rel="profile" in a link relates to media types?
I understand that media types sometimes add a profile such as application/geo+json; profile=jsonfg but I'm not sure I understand how that relates to a link relation type. It may even conflict with other use-cases where a specific relation type is required, I think.

[cportele]

• To add a parameter "profile" to a media type, that parameter must be specified in the media type registration. application/geo+json does not specify any parameters so you cannot add a "profile" parameter to the media type. OK, you can of course add one, but the semantics are undefined and you should not expect that anyone will process that parameter.
• RFC 6906 adds a link relation type "profile" so that a resource can add links to all profiles that the resource conforms to for the content type (including in the HTTP headers). Read the RFC. I do not see how this could add conflicts, this does not limit that other links are provided with different link relation types and other links should not use the "profile" link relation type with another semantics.

[jerstlouis]

@cportele from a quick glance at RFC 6906 (I did not read the whole thing in detail), it's not immediately obvious was this means, may also be what @m-mohr is not sure about.

My guessed-understanding is that an FG-JSON response to a GET request would include a link response header like this:

Link: <http://www.opengis.net/spec/json-fg-1/0.2/conf/core>; rel="profile"

Is this correct? Thanks.

(i.e., it's not the link relation type used to link to the FG-JSON resource -- that would still be "items").

I do find this use of a link relation type quite confusing (is that the primary purpose of RFC 6906, or a side-purpose of it?).

[cportele]

@jerstlouis

It should be something like:

Link: <http://www.opengis.net/def/profile/ogc/0/json-fg>; rel="profile"

Profiles should be registered with the Naming Authority.

There are, for example, profiles registered for the GML Simple Features profiles. The one for Level 0 is: http://www.opengis.net/def/profile/ogc/2.0/gml-sf0.

I do find this use of a link relation type quite confusing (is that the primary purpose of RFC 6906, or a side-purpose of it?).

It is the primary purpose. The title of the RFC is: "The 'profile' Link Relation Type".

I find it pretty straightforward. A profile is a concept identified by a URI. The link relation type allows to add links to a resource that state that the resource representation conforms to the referenced profiles. This is no different to a "license" link to states a license that applies to the resource.

[jerstlouis]

@cportele Thanks for the clarifications.

I find it pretty straightforward.

I guess a question related to my confusion (relating to how that profile link relation type is used) is whether the profile link should (shall?) be in the "links" of the JSON content, the response headers, or both?

[cportele]

@jerstlouis

In the JSON-FG case it SHALL be in the "links" array of the document and when returned from an OGC Web API it SHOULD also be in the headers.

See OGC API Features Part 5 Requirement 26 and Recommendation 3.

[jerstlouis]

@cportele

In Requirement 25:

The GET operation on selected resources

I'm curious what's the plan to make this profile parameter apply to /items and /items/{itemId} whereas here it was intended to target /schema.

To me it's quite ambigious what selected resources mean (not sure what that would translate to in the still-missing ATS either).

Would this profile parameter be added as a new requirement (and/or req.class) to the Core req. class of Part 1 in a revision, in addition to being a requirement of Part 5 - Schemas?

(also does not really make sense to rely on Part 5 to support an FG-JSON representation of Part 1 resources).

Thanks.

[cportele]

@jerstlouis

This really should be discussed in OGC API Features as it is not related to JSON-FG. JSON-FG will not depend on OGC API Features. In JSON-FG we will add a requirement for the profile link in the JSON content. This is unrelated to the query parameter "profile" used in an API (unless you request JSON-FG via the API).

I'm curious what's the plan to make this profile parameter apply to /items and /items/{itemId} whereas here it was intended to target /schema.

I don't understand. Requirements Class "Profile query parameter" is the basic requirements class for the "profile" parameter without identifying the resources to which is applies. This is the job of additional requirements classes depending of this requirements class.

The Requirements Class "Profiles for feature references" is an example, which defines the parameter for the Features and Feature resources.

I am not aware that we are using the parameter on Schema resources yet.

Would this profile parameter be added as a new requirement (and/or req.class) to the Core req. class of Part 1 in a revision, in addition to being a requirement of Part 5 - Schemas?

It might be an option to move the basic, general requirements class for the "profile" parameter to Part 1.

[jerstlouis]

This really should be discussed in OGC API Features as it is not related to JSON-FG.

Right, sorry this is turning into a side discussion. Not sure we need to open a new issue though...

I am not aware that we are using the parameter on Schema resources yet

My bad, sorry, somehow I had the impression that this section 14 was changing the profile of the schema rather than the features... (this has been confusing me since the start of the Part 5 discussions, most likely because the ability to profile the items/features resources would feel natural to be something in Part 1. I'm not sure the specific feature references aspect is actually that closely related to the Schema definition? Since it's clear that the schema is logical, it implies that profiles can do things such as changing how features are referenced, but that should not be tied to the schema definition.).

Requirements Class "Profile query parameter" is the basic requirements class for the "profile" parameter without identifying the resources to which is applies.

I guess for me I see "Section 13" as a ModSpec "Requirement Module" which is like an abstract requirement class (not tied to particular resource paths), in this case for a web API query parameter building block (which can be defined on the building block register -- if that's still a thing), which really does not need to be defined as a requirement class at all, but instead can be re-used and tailored for specific resources, like Section 14 does for /items and /items/{data} (and a more general one targeting these resources should probably also be in Part 1), and which should also correspond to what we specify in OGC API - DGGS for /dggs/{dggrsId}/zones/{zoneId}/data.

i.e., the abstract requirement module not attached to particular resources does not need to be a req. class in any OGC Standard document or have its own URI (unless there's a Web API query parameter building block URI). Sorry for the digression -- let's open a new issue in Features if we need to discuss further.

[m-mohr]

I still don't get it, sorry.

Let's say I have a STAC Item and want to link to it:

{
  "href": "./item.json",
  "type": "application/geo+json",
  "rel": "item"
}

Let's assume that STAC Item is also a valid JSON-FG and I want to express that through the media type, how would I do that?
That's also where my confusing comes from. I initially thought I'd have to set "rel": "profile" which would conflict with "rel": "item".

I guess it somehow works that the item.json from the example would include the <http://www.opengis.net/def/profile/ogc/0/json-fg>; rel="profile" in the header (and/or in the links array of the JSON response), but not sure how that would solve it in other contexts. Also, what's the difference between having a link with "profile" relation type in the body compared to exposing a conformace class?

Note: I'm fine with not having a separate media type, that was the main target of the issue. But this "compromise"(?) seems to be confusing to me. Maybe due to a lack of examples?

PS: IANA seems to be a bit of a burden. Why don't they just allow profiles for all media types? It just leads to situations where people just do what they want, e.g. for the COG media type. The community added parameters to "image/tiff" and it's very commonly used, although not registered with IANA.

[cportele]

@m-mohr

You cannot have it both ways. The original comment was that "./item.json" in JSON-FG should declare its media type as "application/geo+json" and not a JSON-FG media type since it is also GeoJSON, which we agreed to. There is no way that I know to express in the same link that it is also JSON-FG (unless we introduce OGC-specific extensions to links).

What you can do is to add another link with an anchor to state the profile of the anchor resource:

{
  "href": "http://www.opengis.net/def/profile/ogc/0/json-fg",
  "anchor": "./item.json",
  "rel": "profile"
}

[jerstlouis]

@cportele "anchor" is not in the common (or Features) link schema either, is that a non-OGC-specific extension that should be included there?.

Seems like it would be a lot cleaner (and easier for clients) to embed the profile information in a "profile" key within the same link than needing 2 links to link to one resource in a fully qualified manner (assuming that could be as non-OGC-specific as anchor).

[m-mohr]

Okay, understood. That anchor thing seems heavily breaking to me. The actual href should be item.json and then you don't have a rel to describe the purpose. I think this is a bad idea honestly.

If at all, this should probably be something like:

{
  "href": "./item.json",
  "type": "application/geo+json",
  "profile": "http://www.opengis.net/def/profile/ogc/0/json-fg",
  "rel": "item"
}

Otherwise you break semantics of the rel type and also the usability of an href.

[jerstlouis]

It would be good to decide on what the values of those /def/profile/ogc/0/ should be.
The proposed values for the profile parameter above were:

• rfc7946
• jsonfg
• jsonfg-plus

But the examples provided so far use json-fg for the profile URIs.

In addition to that, I am still utterly confused whether the most official shorthand for Features & Geometry JSON is FG-JSON or JSON-FG or both (and this repo is extremely difficult to find as feat-geo-json, with no match for features or geometry or json-fg or fg-json or jsonfg or fgjson).

Looking at the latest spec I guess the correct thing is JSON-FG and I somehow got it wrong and need to fix all references to FG-JSON :)

We would like to reflect all this as properly as made possible by the timing in the Candidate DGGS API.

P.S.: Shouldn't the shorthand form match the order of the full name of the candidate Standard and be changed to FG-JSON (which mirrors the GeoJSON order to which it is more related than e.g., JSON-LD where a suffix is used).
(it also happened to match the application/fg+json media type even though that's no longer being specified).

Alternatively the full title could be changed to something like OGC JSON encoding for Features & Geometry? :)

[cportele]

"anchor" is a standard link parameter (like "rel"), see RFC 8288. I do not understand what would be broken by using "anchor" in a link, this is just using the standard web conventions for links and their semantics. I understand that parsing two links can be more complex for clients.

Inventing a link target attribute "profile" is another approach. However, this information would only be understood by OGC-aware clients as it introduces OGC-specific semantics that nobody else uses (AFAIK).

[m-mohr]

RFC 8288 doesn't really describe a JSON encoding of links, so it'a bit of a stretch to argue with it. But from a practical perspective, what I see usually is that clients expect a href to be the actual resolvable link to follow. So it eventually ends up in html as e.g. <a href="link.href" rel="link.rel">link.title</a> If the link.href is now something different this totally breaks user applications. All such links would point to http://www.opengis.net/def/profile/ogc/0/json-fg, which results in an error 400. I'm not even sure how to distinguish in which case to use anchor and href. So I really think this is a bad design, at least for the link objects.

[cportele]

Meeting 2024-12-09:

• We will add "profile" as an additional link attribute as a hint indicating what the profile of the result of dereferencing the link should be. It should only be used in combination with the "type" attribute (since the value identifies the profile of a media type). The "profile" link attribute should be added to the OGC Link schema consistently. In Features Part 1 we will add it in the planned revision 1.1.
• In the chapter that discusses media types we will describe how to request a specific profile when requesting a resource via an API as well as how to identify the profile in a link to a static resource.
• The JSON-FG representation will include a link to the profile. The profile URIs need to be registered with the Naming Authority and the URIs have to resolve. The fact that a document is a JSON-FG document can also be identified by inspecting the "conformsTo" member.

[m-mohr]

Question: Let's say we want to use this profile property outside of OGC spec (e.g. openEO and STAC), can we make use of it although we don't register our profiles to the OGC NA due to not being OGC standards / having no access to OGC NA? Or do we need our "custom_profile" property (which seems like a bad idea)?

[cportele]

The value of "profile" won't be restricted to OGC URIs. That is, openEO and STAC can mint their own URIs for profiles.

[jerstlouis]

Sorry to bring this back again, but since we're trying to finalize OGC API - DGGS and its DGGS-JSON-FG encoding, would the SWG consider changing the title of the Standard to "OGC JSON encoding for Features & Geometry", to avoid the confusion on the acronym being "JSON-FG" rather than "FG-JSON"?

The current title really continuously have us confused that the acronym is "FG-JSON".
(I made the mistake twice just while writing this comment).

[m-mohr]

@jerstlouis How is this related to media types?

[jerstlouis]

@m-mohr Only tangentially, as it is somewhat related to the order of json and fg appearing in the name of the media type or profile ;) I could file a new issue, but brought this up earlier in the discussion

[cportele]

@jerstlouis - The SWG has always used JSON-FG and there are no plans to change that. Whoever uses FG-JSON has invented his/her own acronym.

[jerstlouis]

@cportele That might well be me (sorry), but I do recall that it was used a lot in the earlier Testbed discussions (again perhaps only by us). We just fixed everything to be JSON-FG for DGGS-JSON-FG. (It also was how the media type application/fg+json was read)

But would the SWG be willing to consider renaming the title of the candidate Standard to OGC JSON encoding for Features & Geometry so that the acronym letters appear in order in the title? Should I file a separate issue to discuss that? Thanks.