Statement versioning inconsistency

[stevenvergenz]

When describing the "version" field of statements, Data 2.4.10 reads:

• Statements returned by an LRS MUST retain the version they are accepted with. If they lack a version, the version MUST be set to 1.0.0.
• If Learning Record Providers set the Statement version, they MUST set it to 1.0.0.
• Learning Record Providers SHOULD NOT set the Statement version.

Whereas with regards to the X-Experience-API-Version header, Communication 3.3 reads:

• The LRS MUST set this header to the latest patch version.
• The Client MUST set this header to the latest patch version.

This means that every statement must simultaneously be described by clients and the LRS as two different patch versions, which could be confusing for LRPs.

I see three possible remedies here:

1. Both version numbers drop the patch number altogether, and only use 1.0. The data format is required to be the same across all patch versions, so you could safely do this.
2. Both numbers track the latest patch, so that the distinction between the LRS version and the statement version could be made clear.
3. The numbering stands as it is, but additional text is added to one or both sections to make it clear that statements only track minor spec versions, but the version header tracks patches.

[fugu13]

The differences are because they serve different purposes -- the version in the statement is a data compatibility version (and also can't change with patch versions because it would break spec compatibility), while the second is a version for communication compatibility (which is slightly more nuanced).

They can't both become just 1.0 because 1.0 isn't a legal value for the version element in statements (it was a little weird it got included as an option with the headers, but it did, so it isn't getting removed). Also, that would remove the reason for including it (nuanced communication versioning).

They can't both track the latest patch because they don't have the same purpose.

I'm definitely fine with additional clarifying text. Maybe a note in each of them that references the other, with appropriate comparative text. "Unlike x-experience-api-version (see ...), this value is always 1.0.0, as it is represents the version of the data model, and all 1.0.x statements share the same data model, 1.0.0." "Unlike the version attribute, which is always 1.0.0, this value is always the version of the standard implemented, because while no communication incompatibility should arise among 1.0.x versions, there are sometimes clarifications of previously intended behavior." (just really rough takes on what they could say).

[garemoko]

PR merged, can this be closed?

[stevenvergenz]

I'd say so. :+1:

[garemoko]

@stevenvergenz you have the power. Click that close button! :-)