Subject: Re: [Geojson] Reserving a "version" key

From: Sean Gillies <[email-masked]>
Date: Sat, 27 Feb 2016 16:49:29 -0700

On Mon, Jan 11, 2016 at 10:27 AM, Sean Gillies <[email-masked]>
wrote:

> In https://github.com/geojson/draft-geojson/issues/95 we have a proposal
> to reserve a version key.
>
>> While I would hate to 'add' a version number to the JSON; I would not
>> mind stating in the RFC that this is version X; and that a certain
>> key/param pair is kept reserved for future version numbers and/or
>> extensions. Just so you do not dig your self into a hole or make things
>> like mimetypes of accept: http negotiation complex.
>>
>> Likewise; in some other standards; right out of the gate declaring that
>> any key or header starting with 'X-' is experimental and can always be
>> safely ignored is also goodness.
>>
> Anybody have thoughts on this one? I also would like to avoid version
> numbers in the JSON and use other ways to indicate extensions.
>

On the subject of a version member in GeoJSON objects, I propose to simply
reserve the member.  If creators of protocols and APIs that use GeoJSON
want to put the version of their protocol or API in the GeoJSON data they
serve, they will need to use a different member than "version". Defining a
default value of "version" doesn't seem necessary to me but I wouldn't be
opposed to "1.0".

See https://github.com/geojson/draft-geojson/pull/159.

We have only 3 open issues left in GitHub and only #125 has no PR that will
close it!

-- 
Sean Gillies

---

From: Martin Thomson <[email-masked]>
Date: Sun, 28 Feb 2016 21:33:59 +1100

On 28 February 2016 at 10:49, Sean Gillies <[email-masked]> wrote:
> If creators of protocols and APIs that use GeoJSON want to put the version
> of their protocol or API in the GeoJSON data they serve, they will need to
> use a different member than "version".

What do you intend to achieve by doing this?

The alternative is text to this effect (in the top of the extension section:

The GeoJSON format can be extended as defined here, but no explicit
versioning scheme is defined. A specification that alters the
semantics of GeoJSON members or otherwise modifies the format does not
create a new version of this format; instead, it defines an entirely
new format that cannot be identified as GeoJSON.

or something like that.

---

From: Erik Wilde <[email-masked]>
Date: Sun, 28 Feb 2016 12:58:47 +0100

> new format that cannot be identified as GeoJSON.

                   ^^^^^^  MUST NOT ?

---

From: "Stefan Hagen" <[email-masked]>
Date: Sun, 28 Feb 2016 13:17:01 +0100

On 2016-FEB-28 00:49:29 +01:00, Sean Gillies <<[email-masked]>> wrote:

> On Mon, Jan 11, 2016 at 10:27 AM, Sean Gillies <<[email-masked]>> wrote:
> 
> > In <https://github.com/geojson/draft-geojson/issues/95> we have a proposal to reserve a version key.
> > 
> > > While I would hate to 'add' a version number to the JSON; I would not mind stating in the RFC that this is version X; and that a certain key/param pair is kept reserved for future version numbers and/or extensions. Just so you do not dig your self into a hole or make things like mimetypes of accept: http negotiation complex.
> > > Likewise; in some other standards; right out of the gate declaring that any key or header starting with 'X-' is experimental and can always be safely ignored is also goodness.
> > > Anybody have thoughts on this one? I also would like to avoid version numbers in the JSON and use other ways to indicate extensions.
> > 
> 
> On the subject of a version member in GeoJSON objects, I propose to simply reserve the member. If creators of protocols and APIs that use GeoJSON want to put the version of their protocol or API in the GeoJSON data they serve, they will need to use a different member than "version". Defining a default value of "version" doesn't seem necessary to me but I wouldn't be opposed to "1.0".
> 
> See <https://github.com/geojson/draft-geojson/pull/159>.
> We have only 3 open issues left in GitHub and only #125 has no PR that will close it! ...
> +1 for reservation for future use by the GeoJSON spec of the member "version". As usual clients/consumers digest any object member key they parse by either ignoring or not.

"Best"^^
"Stefan"

---

From: Martin Daly <[email-masked]>
Date: Sun, 28 Feb 2016 12:36:25 +0000

> > new format that cannot be identified as GeoJSON.

Agreed. "Reserved" has (more or less) the same effect as MUST NOT, so why not just say it?

Martin

---

From: Sean Gillies <[email-masked]>
Date: Sun, 28 Feb 2016 09:30:33 -0700

> new format that cannot be identified as GeoJSON.

Thanks, Martin. This is very sensible.

-- 
Sean Gillies

---

From: Sean Gillies <[email-masked]>
Date: Sun, 28 Feb 2016 09:35:06 -0700

>> new format that cannot be identified as GeoJSON.

Erik, do you mean MUST NOT instead of "does not" in the paragraph above?
"Does not" reads okay to me there since it's about a result or effect
rather than an action or decision made by an implementer.

-- 
Sean Gillies

---

From: Sean Gillies <[email-masked]>
Date: Sun, 28 Feb 2016 09:41:05 -0700

> Agreed. "Reserved" has (more or less) the same effect as MUST NOT, so why

Martin, Erik,

If we go with a statement that "GeoJSON defines no versioning scheme and
extensions may not add one", do you think the reservation of "version" can
be dropped?

-- 
Sean Gillies

---

From: Martin Thomson <[email-masked]>
Date: Mon, 29 Feb 2016 12:12:00 +1100

> extensions may not add one", do you think the reservation of "version" can

I think so.  The provision of a "version" field suggests that there
are changes that might be made to the core that would be incompatible.
If an extension wants to use "version", they don't gain the ability to
modify semantics of fields (or they create an entirely different
format by doing so).

(As for the other matter, I've no view on MUST NOT vs cannot, I prefer
not to shout people into compliance.)

---

From: Erik Wilde <[email-masked]>
Date: Mon, 29 Feb 2016 09:27:49 +0100

On 2016-02-28 17:35 , Sean Gillies wrote:
> On Sun, Feb 28, 2016 at 4:58 AM, Erik Wilde <[email-masked]
> <mailto:[email-masked]>> wrote:
>

i guess my ASCII rendition got lost in some email clients. i meant to 
replace "that cannot be identified as GeoJSON" with "that MUST NOT be 
identified as GeoJSON", making it clear that later specs cannot hijack 
GeoJSON's "there is no explicit versioning" stance and say "but now 
there is".

cheers,

dret.

-- 
erik wilde | mailto:[email-masked] |
            | http://dret.net/netdret    |
            | http://twitter.com/dret    |

---

From: Erik Wilde <[email-masked]>
Date: Mon, 29 Feb 2016 09:31:05 +0100

> modify semantics of fields (or they create an entirely different

i agree. i think it's better to be explicit about how versioning works 
(i.e., there is no built-in mechanism other than extensibility), instead 
of trying to try to reserve keywords that might be used.

cheers,

dret.

---

From: Allan Doyle <[email-masked]>
Date: Mon, 29 Feb 2016 09:24:02 -0500

+1

> On Feb 29, 2016, at 3:31 AM, Erik Wilde <[email-masked]> wrote:
> 
> i agree. i think it's better to be explicit about how versioning works (i.e., there is no built-in mechanism other than extensibility), instead of trying to try to reserve keywords that might be used.
> 
> cheers,
> 
> dret.
> 
> -- 
> _______________________________________________
> GeoJSON mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/geojson