Update tags section of spec

[HebaruSan]

The spec has a tags section, but it's mostly inaccurate and misleading. Now it's brought up to date with how the tags actually work.

[DasSkelett]

I was wondering about the spec version for the tags.
They are part of the schema since a long time (#2034, included in CKAN v1.24),
but on the other hand the client uses them only since v1.26.8, but didn't throw any errors or was missing anything vital when encountering them before that version.
Netkan has no special handling for the tags apart from sorting them at a specific location.

The spec isn't really clear in this case:

A vx.x string (eg: "v1.2"), being the minimum version of the reference CKAN client that will read this file.

Would it make sense to set the spec version for tags back to v1.24 as it was originally in the #2034, when they where officially introduced in the schema?
Otherwise shouldn't it be v1.27, because the client from v1.26.0 - v1.26.6 didn't do anything with them yet?

[HebaruSan]

Yes, I see no perfect answer here.

• A module containing tags can be loaded on any client and will simply be ignored on the older ones, so the spec could just omit a spec version indicator
• It was indeed added to the spec in 1.24, but the spec could have said v1.24 back then if that was the right answer, instead v<TBA> was chosen
• If we can't replace <TBA> with a real version now, then we'll never do it
• If the reader is looking at the spec to understand when the functionality becomes useful, then v1.26 is the closest right answer. Yes, some 1.26 versions ignore it as 1.24 and 1.25 did, but the functionality finally landed on this version series.

[DasSkelett]

Okay. I'd still lean more towards v1.27, because a reader can be sure that they are recognized from this version up, and the support in v1.26.8+ is basically a bonus. Otherwise we make v1.26.0 - v1.26.6 retroactively not conformant to the spec.
But I'm okay to go with either solution.

[politas]

I think the idea is that the spec version is the minimum level of client that won't mess things up for a given element. Ignoring tags is perfectly correct behaviour.

[HebaruSan]

Otherwise we make v1.26.0 - v1.26.6 retroactively not conformant to the spec.

OK, I'm convinced. Changed to 1.27.

[HebaruSan]

I think the idea is that the spec version is the minimum level of client that won't mess things up for a given element. Ignoring tags is perfectly correct behaviour.

@politas, which value would you recommend we use based on that?

[politas]

So we're making Bussard v1.27.0, then?

[HebaruSan]

That's also open to discussion. I was going to use 1.26.12, but it will be 1.27.0 if you say so.

[politas]

If we're bumping the spec, we should be bumping the client version to match, otherwise the client is not claiming to be compliant with the spec.

[politas]

That is assuming that we have tag support working in the client, now. We do, don't we? I haven't actually looked at that bit, myself.

[HebaruSan]

It was added in #2936, released in v1.26.8.

[DasSkelett]

We're not really bumping the spec version itself, just the version of one property is "in the future".
I'd argue the client comforms to the spec if it has additional features, but not if it is missing features. So if it supports the tags, while they are not in the spec yet (or not in the current spec version), it's okay, but if the spec says it supports tags, but if the client doesn't (or ignores them), it's not conforming to the spec.

But I guess making the next release v1.27 would solve most of that.

[politas]

Makes sense to me to make tags v1.27 in the spec and make Bussard v1.27.0. Let's go with that.

[HebaruSan]

Sounds good. This PR updates the spec to say tags are in 1.27, and Bussard will be 1.27.0.

[DasSkelett]

Right, almost forgot to approve this PR then :D