Addition of a GeoJSON profile URI (ala RFC6906)

[sgillies]

RFC4267 doesn't specify any media type parameters, but a profile
parameter is a big help to GeoJSON. Without it, we'd probably need
a custom media type. GeoJSON's use of a profile parameter does not
alter the (JSON) processing model, it only indicates that the root
object contains geographic features to be interpreted according to
the GeoJSON spec.

[sthagen]

That is a cool move. I like it!

What jumped to my eyes is, that this is incomplete (technically) as we
also need an entityref for RFC6906 in the xml and we need an actual ref
container file for RFC6906 also inside the bib folder.

For the latter see attached and for the former I suggest in template.xml

inserting:

after the one for RFC5246 around line 12/13

and inserting:
&pandocRef6906;

directly after:
&pandocRef5165;

at around lines 109/110.

That should close the loop that the "[RFC6906] reference" in the
proposed new section opens.

All the best,
Stefan.
Am 14.06.13 19:16, schrieb Sean Gillies:

RFC4267 doesn't specify any media type parameters, but a profile
parameter is a big help to GeoJSON. Without it, we'd probably need
a custom media type. GeoJSON's use of a profile parameter does not
alter the (JSON) processing model, it only indicates that the root
object contains geographic features to be interpreted according to
the GeoJSON spec.

---

    You can merge this Pull Request by running

git pull https://github.com/sgillies/draft-geojson master

Or view, comment on, or merge it at:

#11

    Commit Summary

• Clearly state that GeoJSON is a RFC6906 profile of JSON.

  File Changes
  

• M middle.mkd
  https://github.com/GeoJSONWG/draft-geojson/pull/11/files#diff-0 (40)

  Patch Links:
  

• https://github.com/GeoJSONWG/draft-geojson/pull/11.patch

• https://github.com/GeoJSONWG/draft-geojson/pull/11.diff

[dret]

So where would the profile URI when using GeoJSON? JSON has no standardized place for it in JSON payload. As sean pointed out, JSON does not have a profile media type parameter. So one place to put it would be in a Link HTTP header. Is that what you're thinking?

[adoyle]

I was just going to ask more or less the same thing.

It feels like a good idea, but also feels like it also pulls in HTTP and possibly other considerations that are really not part of GeoJSON. However, they also would probably help interoperability.

Also, why only at the FeatureCollection level?

Does this also commit us to maintaining a retrievable resource at the URI endpoint? That seems to be in the spirit of RFC6906.

RFC6906 seems to be content with pointing to anything informative, why not point back to the spec? But that means that we'd need to know the RFC number… but then if GeoSON.org goes away, it will still work.

On Jun 14, 2013, at 1:49 PM, Erik Wilde notifications@github.com wrote:

So where would the profile URI when using GeoJSON? JSON has no standardized place for it in JSON payload. As sean pointed out, JSON does not have a profile media type parameter. So one place to put it would be in a Link HTTP header. Is that what you're thinking?

—
Reply to this email directly or view it on GitHub.

[dret]

On 2013-06-14 10:59 , Allan Doyle wrote:

RFC6906 seems to be content with pointing to anything informative, why
not point back to the spec? But that means that we'd need to know the
RFC number… but then if GeoSON.org goes away, it will still work.

actually, RFC 6906 is content with not pointing to anything. the profile
URI is just an identifier, it's not a link that clients should follow.
but yes, it would be cool to make it actionable and persistent. i would
assume that the URI could be changed by the RFC editor once the number
is actually assigned, but that would mean that throughout the drafts, it
would be essentially undefined (something like
http://tools.ietf.org/html/rfcXXXX, maybe).

[sgillies]

@adoyle, I think there are potentially other profiles to be explored, not just the feature collection one. In OData, it looks like GeoJSON geometries will be employed, but not features or feature collections precisely as described in our spec. A profile that states that geometries are in use (but not nocessarily features or collections) could help there. And the Google Maps Engine API employs another profile (an object with a features item but no FeatureCollection type): https://developers.google.com/maps-engine/documentation/reference/v1/tables/features/batchPatch.

@dret, when I started this issue, I felt like link headers were too obscure, but now I've discovered that GitHub uses them for pagination (http://developer.github.com/v3/#pagination) and that they're supported by my favorite Python HTTP lib (http://www.python-requests.org/en/latest/user/advanced/#link-headers). So maybe link headers are going to be good enough.

It's worth mentioning that such a profile seems to be of no use in applications like GitHub's because GitHub only deals in files and file extensions, not general media and MIME media types. But I think that GitHub's choice to only make maps for files ending in .geojson shows that it is important to have an identifier for our profile.

[dret]

On 2013-06-17 12:23 , Sean Gillies wrote:

@dret https://github.com/dret, when I started this issue, I felt like
link headers were too obscure, but now I've discovered that GitHub uses
them for pagination (http://developer.github.com/v3/#pagination) and
that they're supported by my favorite Python HTTP lib
(http://www.python-requests.org/en/latest/user/advanced/#link-headers).
So maybe link headers are going to be good enough.

it seems like the idea of processing HTTP header information is getting
more and more popular. using HTTP-level information is becoming
something many developers are feeling comfortable with these days.
personally, i wouldn't see link headers as being obscure, but i am
definitely slanted towards treating HTTP as a way of designing services
that developers should be familiar with these day.

[sheppard]

This could work, though I still wonder if we might be better off just pushing for a new mime type. As discussed on Twitter, I'm considering a use case where I might need to be able to serve both geojson and "simple" json at the same URI, and differentiate between them based only on a client Accepts: header. I know adding a mime type is not the preferred route, but I'd argue that we're already halfway there due to GitHub's choice to only recognize .geojson files (i.e. rather than inspecting .json files for geo content). Generally, I'd say that different file extensions intuitively map to different mimetypes (though that might be because this assumption is implicitly enforced by the software I'm using).

Edit: never mind, then

[dret]

On 2013-06-21 10:15 , S. Andrew Sheppard wrote:

This could work, though I still wonder if we might be better off just
pushing for a new mime type. As discussed on Twitter, I'm considering a
use case where I might need to be able to serve both geojson and
"simple" json the same URI, and differentiate between them based only on
a client |Accepts:| header. I know adding a mime type is not the
preferred route, but I'd argue that we're already halfway there due to
GitHub's choice to only recognize |.geojson| files (i.e. rather than
inspecting |.json| files for geo content). Generally, I'd say that
different file extensions intuitively map to different mimetypes (though
that might be because this assumption is implicitly enforced by the
software I'm using).

sounds reasonable to me. profiles really are not so much about signaling
mimetype-like things. for example, it would be a stretch to say that
"Atom" is a profile of "XML". Atom has a very different processing
model, so it makes much more sense to give it its own media type (and
from my point of view, it's the right thing to do from the REST
perspective).

when you process XML, you see a tree with labels and order and a very
generic structure to it. when you process Atom, you see a feed and
entries and you have a specific metadata model for those two concepts.
it really is a very different view, so Atom should be a new media type.

however, Podcasts are really just a special case of Atom, so there it
makes much more sense to use a profile. you can process a Podcast as a
generic Atom feed and still make sense of it, because the Podcast
processing model is just an addition to Atom.

[sgillies]

Can I try to summarize the arguments for a GeoJSON media type?

1. GeoJSON docs with a FeatureCollection as root object will often be served by specialized GIS applications that don't serve any other JSON documents and are only concerned with geometries, features, and collections of features in a standard structure. The data might as well be GML or Shapefiles for some programs (GeoServer, etc).
2. Web developers may wish to serve GeoJSON and other JSON representations of the same resource. Media types (and file extensions) are still the only very well known means of communicating formats and conventions between clients and servers. Profiles don't have as much software support.
3. Companies are already standardizing on particular file extensions and will do so for media types. If they choose different vendor media types, future interoperability is going to be more difficult.

Does that sound right? Am I missing anything?

My argument against a specific GeoJSON media type is that GeoJSON, unlike some other JSON based formats, is "just" JSON. We don't include any protocols or hypermedia concerns as in Mike Amundson's Collection+JSON format (http://amundsen.com/media-types/collection/format/) and don't have a semantic web layer like JSON-LD (http://json-ld.org/spec/latest/json-ld/#interpreting-json-as-json-ld). We don't have thin JSON wrappers around mostly binary blob or plain/HTML content like the GitHub API does. GeoJSON is just strings and arrays of numbers in a particular structure.

On the other hand, perhaps the coordinate and spatial reference system concerns here are strong enough to warrant a media type; all applications are required to have at least a simple model of the Earth's surface, and applications will be broken in some cases if they aren't aware of projections.

[sheppard]

2 and 3 sum up the argument for me. I think 1 could actually be used as an argument for sticking with application/json. My use case aside, if most projects are only serving GeoJSON and not some other JSON syntax at the same time, it's fairly unlikely that there will be significant issues to sticking with the existing media type.

Now that I understand it better, I am warming up to the idea of specifying a profile as a media type parameter (though not so much the Link: variant). Since media type parameters can be used in Accept: headers, I could make it work with relatively minor changes to my existing software stack. Going the profile route would also start paving the way for other JSON profiles and potentially make the whole ecosystem more adaptable to future needs. And it's obviously backwards compatible with the existing media type.

That said, the utility of having a specific profile for FeatureCollection (or other object types) is not apparent to me. Could we keep it simple, perhaps just:

Content-type: application/json; profile=http://geojson.org

This would of course leave it to the implementer to check the 'type' parameter on the root object to figure out how to actually process it. In practice, that's probably what most existing client software is doing already.

In summary:

• Would like to HTTP headers (both request & response) in some way to differentiate GeoJSON from other JSON
• Options are to use a profile URI or a new media type - personally leaning toward (shorter) profile URI at the moment
• This decision could set a pattern for future JSON-based specs.

[dret]

On 2013-06-23 8:35 , Sean Gillies wrote:

My argument against a specific GeoJSON media type is that GeoJSON,
unlike some other JSON based formats, is "just" JSON. We don't include
any protocols or hypermedia concerns as in Mike Amundson's
Collection+JSON format
(http://amundsen.com/media-types/collection/format/) and don't have a
semantic web layer like JSON-LD
(http://json-ld.org/spec/latest/json-ld/#interpreting-json-as-json-ld).
We don't have thin JSON wrappers around mostly binary blob or plain/HTML
content like the GitHub API does. GeoJSON is just strings and arrays of
numbers in a particular structure.

i see your point, and it certainly is common for applications to use
just JSON as the media type. but that often is the case because there's
tight coupling between the consumers and the server, and the implicit
assumption is that everybody knows what the JSON is actually about.

strictly speaking, JSON's generic media type (and the ones of other
metalanguages such as XML or RDF) only makes sense for generic
applications, which in case of XML most often are XML databases. if you
are an XML database, you don't care about what the XML is about, you
just process any XML. however, XML-based applications using specific
formats and thus processing models often used application/xxx+xml, but
there is less of a habit of using application/xxx+json (so far).

[sheppard]

Okay, I rescind my comment above that GitHub's .geojson choice means we need a new mimetype:
https://github.com/blog/1541-geojson-rendering-improvements

Other arguments may still be valid?

[sgillies]

If you all don't mind, I'm going to close this pull request. We can revisit this after we submit.