Advertising a version of TAXII at a CSD level is not currently possible

[jordan2175]

Given the way we advertise the TAXII version via the API Root and Media Types, it is not clear how one would go about saying they are using TAXII 2.1 CSD01 for example.

[jordan2175]

I propose that we look at changing the version parameter to be a string instead of a float so we can do "2.1-csd01" or "2.1-csd-01" or "2.1.1" where the 3rd digits is the CSD version.

[johnwunder]

This general idea makes sense to me but the proposed approach in the draft needs work. For example, it calls out CSD specifically when you can also have multiple CS versions for a given major.minor release. Does that matter? Also, that means 2.1 is a later release than 2.1.01, which is pretty unintuitive.

We need to discuss this one more.

[allant0]

I suggest we use a string with a normalized string structure.

..[-CSD][-WD] and the version string *always* has major.minor.patch so that it makes it easy for systems to do version matching. So 2.0 would be 2.0.0 working draft of 2.1.1 would be 2.1.1-WD CSD of 2.1 would be 2.1.0-CSD Without -CSD or -WD then it would be considered the CS version.

[allant0]

For weird reason the major.minor.patch stuff got edited out by github above.

major.minor.patch[-CSD][-WD]

[jordan2175]

After thinking about this a lot more, here are some thoughts. One of the concerns I have is I think we need a strictly increasing version number. For example, we may release say 4 CSDs: 2.1.1-csd, 2.1.2-csd, 2.1.3-csd, 2.1.4-csd

and then we release a CS and it would have 2.1.1-cs or would it be 2.1.5-cs? Then what happens if we get public comments that require a material change we have to issue a new CSD. Would it be CSD05 or would it then be 2.1.5-csd or 2.1.6-csd? What happens if we need to issue multiple CSs, either based on the same CSD or on a different CSD?

I think this will be completely confusing for people. I mean, this all makes sense to us, in the TC, however, I am afraid people outside the TC will not know or understand the nuances of WD, CSD, CS, etc. They will not know which comes next.

A slightly over engineered solution would be to assign a number to each level of the OASIS process, then it would keep increasing.

WD01 = 2.1.1.1-wd WD02 = 2.1.1.2-wd CSD01 = 2.1.2.1-csd CSD02 = 2.1.2.2-csd CS01 = 2.1.3.1-cs CS02 = 2.1.3.1-cs OASIS Standard 01 = 2.1.4.1

A last option, the one I prefer, would be to decouple the OASIS process number from our advertised version numbers and also treat anything and everything that the TC does not classify as done as a "draft". Example:

WD01 = 2.1.1-draft WD02 = 2.1.2-draft CSD01 = 2.1.3-draft CSD02 = 2.1.4-draft CS01 = 2.1.5-draft CS02 = 2.1.6-draft CS03 (final version) = 2.1.7 OR if we went to a full OASIS standard instead of another CS, it would still be 2.1.7. Basically, once the TC says we are done and no longer going to work on that branch anymore. Now in the future if we decided to go back and add something, we would just go CSD03 = 2.1.8-draft CSD04 = 2.1.9-draft CS (final) = 2.1.10

Basically the third value is ALWAYS increasing. All versions that are not classified as "done" by the TC will have a suffix of "-draft". We would also say that content must get to at least a CS before the TC can classify it as "done".

We would need to decide what happens if the TC wants to go to a full OASIS standard. Does the CS versions keep the "-draft" suffix until the full OASIS standard version is submitted ?

[MarkDavidson]

If we had 4 CSDs, I would rather see:

• 2.1-CSD1
• 2.1-CSD2
• 2.1-CSD3
• 2.1-CSD4

I think packing the draft number into the specs version number will be confusing for people.

[johnwunder]

I agree with @MarkDavidson that we should either:

1. Just use 2.1 for all CSDs/CSs in the 2.1 series of releases (preferred)
2. If we have to have different strings for different CSDs, use something obvious like "2.1-CSD01" or "2.1-draft1".

[jordan2175]

@MarkDavidson @johnwunder please see my description right about yours. Do you not think it would be more confusing for the industry to have to figure out if 2.1-CSD2 or 2.1-CS1 was the most current version? The reason why I am proposing divorcing the versions from the OASIS terminology is to make it easier for people. The version number would always increase, regardless of the OASIS stage.

So for the following internal versions you would have the corresponding TAXII versions. Lets use an example where we do 3 CSDs then a CS, then get substantive changes from the TAB or public and have to do one more CSD and then another CS..

CSD01 = 2.1.1 CSD02 = 2.1.2 CSD03 = 2.1.3 CS01 = 2.1.4 CSD04 = 2.1.5 CS02 = 2.1.6 OASIS Standard 01 = 2.1.7

This way the versions always increase. There is no confusion. Now, if we wanted to add a suffix like "draft" or something to indicate that it was not yet final, I am also okay with that.

[terrymacdonald]

After a long discussion with Bret Jordan on the slack channel I've come to a conclusion:

I think the important part of CSD is the 'Draft' bit. It is not a real specification until it is a "Committee Specification". People shouldn't expect reliable code UNTIL we have a full CS completed. My stance is that the CSD is a draft for what the final CS will look like. Therefore we each CSD should reflect what we intend the final version of what the CS would look like.

Additionally - this only affects the test code people are developing. Its only a small group of test users who will be in contact with each other for testing purposes, and are who all likely to know when the next CSD is being released, and can just ask each other which CSD they support. Plugfests can be specific in which CSD they are testing. That said, I do understand it is a problem for interoperability during testing, so I would like to propose a slight modification to the suggestions above.

After a discussion with Bret, I would like to propose the following versioning format: TAXII 2.1 CSD01 = 2.1-draft01 TAXII 2.1 CSD02 = 2.1-draft02 TAXII 2.1 CS FINAL = 2.1

I would like to see:

• The production TAXII version in the CS to be the same as the TAXII version specification we are using, so that when we have agreed the CS and it passes the public review feedback stages the standard TAXII version would be '2.1'
• The production TAXII version should be used in the standards text as we do now.
• For each CSD we have an additional block of highlighted text that specifically states something like "While this standard is being developed we use a temporary TAXII version per CSD to aid in testing. The temporary TAXII version for this CSD is '2.1-draft01' and any test software that implement this specific CSD MUST support the temporary TAXII version in addition to the standard TAXII version used above."

Cheers Terry MacDonald Cosive

[jordan2175]

I am okay with Terry's proposal. @allant0 @johnwunder @MarkDavidson can you support this? The idea is we would use a "-draft##" suffix for everything up until we do the final CSD for CS publication. At that point we would switch the version to be just "2.1". Any follow-on changes that are needed from multiple CS releases or even if the public review / TAB forces us to go back and do one more CSD, those changes should be small enough that we can track them out-of-band.

[MarkDavidson]

I'm personally in favor of using the plain version string, e.g., version=2.1 for all CSDs, for the following reasons:

1. I don't understand why the stated problem is important to solve - no supporting evidence has been given in this thread, just a problem statement and various proposed solutions.
2. Each new CSD and CS will require code changes to content negotiation, which increases the chances of interoperability breaking. If the change had supporting arguments, then I might view this tradeoff as worthwhile.
3. I don't think the community in general will support multiple CSDs at once, I see the community supporting the latest CSD/CS. For instance, I don't see testing multiple CSDs at a plugfest - I see us doing interop testing for just the most recent CSD or CS.

I guess my biggest concern is - why is this a problem worth solving? I can see drawbacks for the various solutions proposed, though I'm not able to reason whether or not there are benefits to them.

In terms of what I'd bring to a plugfest or use as a baseline for a vendor integration, I'd only bring something that implements the most recent CSD or CS, and I would not care one bit about compatibility with older CSDs.

I want TAXII 2.1 compatibility issues to arise when two vendors implement different CSDs/CSs, because that's how we'll move the fastest toward interoperable TAXII 2.1 implementations in the marketplace.

[johnwunder]

I tend to agree w/ Mark that we shouldn't do this. We shouldn't encourage code that implements old CSDs to hang around by dignifying it with its own content version.

That said, if we do decide to identify individual CSD versions, I think the naming structure outlined above (2.1-draft1, 2.1-draft2, 2.1) is good.

[jmgnc]

I also agree w/ Mark. CSD should be short lived enough that it's not an issue. If you have troubles between your products because you're implementing the draft, then you know it's a problem because of the draft, and we shouldn't be solving draft issues in the final production spec that will become CS.

Now if there was guidance outside the CSD/CS that recommended people use this, that'd be a different story.

[terrymacdonald]

I tend to agree with Mark too. I'd prefer we focus on the end game with our CSDs, but I also see there could be the need for this during testing.

Is there anywhere we could put this outside of the standard itself? Some informal guidance somewhere not in the CSD itself?

Cheers

Terry MacDonald | Chief Product Officer

M: +64 211 918 814 <+64+211+918+814> E: terry.macdonald@cosive.com W: www.cosive.com

On Fri, Mar 2, 2018 at 9:02 AM, John-Mark Gurney notifications@github.com wrote:

I also agree w/ Mark. CSD should be short lived enough that it's not an issue. If you have troubles between your products because you're implementing the draft, then you know it's a problem because of the draft, and we shouldn't be solving draft issues in the final production spec that will become CS.

Now if there was guidance outside the CSD/CS that recommended people use this, that'd be a different story.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/oasis-tcs/cti-taxii2/issues/49#issuecomment-369713257, or mute the thread https://github.com/notifications/unsubscribe-auth/AFdOrCAMv0Yk9_I8QNZhtfcxmzSGyh9Eks5taFO6gaJpZM4SOTEP .

[emmanvg]

I agree with Mark's reasons to not do this. Based on the recent email conversation and as mentioned by John-Mark and Terry, if we really need this for testing purposes. It might be better to define the version in a separate informal document for people that are building prototypes.

[jordan2175]

Closing based on results from ballot.