entitlementKey data type

[cars10]

The spec specifies the data type of entitlementKey as JSON Object with the following example value:

{courseStructure: "xyz-123-9999", alternate: "abc-456-1111"}

But in every example i have seen so far (including the complex-cmi5.xml in this spec) the value for entitlementKey is just a plain string, like

<entitlementKey>833d0c7c-a3f8-4f9b-a51f-cbd8a9dac9fb</entitlementKey>

Is this an error in the spec? I am not sure what data type to expect here.

Edit: Also, the data type of launchParameters is String, but the example includes a json object:

<launchParameters>{'initialSpeed':3.0,'mode':1}</launchParameters>

[cars10]

Might also be interesting for @brianjmiller for the testsuite? Maybe we can discuss in todays meeting.

[brianjmiller]

I don't believe there is a spec issue here because it is important to look at those items in the context. So the example that is a JSON object:

{courseStructure: "xyz-123-9999", alternate: "abc-456-1111"}

Is specifically referring to the value as it is placed in the LMS.LaunchData state API document. This document is a JSON structure that the AU retrieves during initialization of the launch session. The key is that this object has 2 properties, the first or courseStructure being derived from the cmi5.xml file, the second or alternate is derived in some other manner to be agreed upon by the LMS and AU.

So then the XML variant example:

<entitlementKey>833d0c7c-a3f8-4f9b-a51f-cbd8a9dac9fb</entitlementKey>

Shows how one records the course structure specific entitlement key in the cmi5.xml document. If you were to pair the two for the above <entitlementKey> example you'd expect the LMS.LaunchData to include:

{
    ...
    "entitlementKey": {
        "courseStructure": "833d0c7c-a3f8-4f9b-a51f-cbd8a9dac9fb"
    }
}

That being said, I agree that the examples could be made more clear to represent this connection. And there is an issue in that the JSON representation is incorrectly quoted to be JSON (for which I'll submit a PR).

As for the launchParameters the data type is just a string, so JSON is a valid string so is acceptable. I've mentioned in the past that showing a JSON example in a non-specifically JSON context is confusing, but no one has really decided that is important enough to change. I think it will be common for the launch parameters to be represented as JSON by content, and then it is just up to the AU to know that it expects JSON in that value and for it to parse it itself, but I don't necessarily think that warrants us using it as such as an example. Given the amount I have going on and the fact that it isn't in violation of the spec I won't be submitting a PR to change that example, but I wouldn't be against someone else proposing changes related to the examples.

[cars10]

Thank you for the clarification. It was really not clear to us that the LMS should read the <entitlementKey> and return this in the LMS.LaunchData under the courseStructure key, we currently simply return the value of the entitlementKey itself.

I guess the spec could be improved here, but is was obviously also our fault to assume that the datatype of a property in the LMS.LaunchData means that it should be the same datatype in the manifest file.

[MrBillMcDonald]

Reviewed per the June 24th Meeting.

Recommend a providing a JSON example of LMS.LaunchData and best practice that includes entitlement key

[MrBillMcDonald]

Per Feb 16th Meeting - update best practice document for inclusion in IEEE GitLab once its established