XAPI-00254 > Test not clearly justified by the specification
integralla opened this issue · comments
The conformance test suite for Activities Resource Requirements (Communication 2.5) includes the following requirement:
XAPI-00254
The Activity Object must contain all available information about an activity from any statements who target the same “activityId”. For example, LRS accepts two statements each with a different language description of an activity using the exact same “activityId”. The LRS must return both language descriptions when a GET request is made to the Activities endpoint for that “activityId”.
In the actual specification, however, I can find no justification for this test.
Communication > 2.5 Activities Resource itself makes no mention that an LRS must merge any part of the activity definitions received for the same activityId across all activities.
The most relevant reference to this that I have found is in Data > 2.4.4.1 When the ObjectType is Activity, specifically the following two bullet points under the LRS requirements:
- Upon receiving a Statement with an Activity Definition that differs from the one stored, an LRS SHOULD decide whether it considers the Learning Record Provider to have the authority to change the definition and SHOULD update the stored Activity Definition accordingly if that decision is positive.
- An LRS MAY make small corrections to its canonical definition for the Activity when receiving a new definition e.g. to fix a spelling.
There is nothing there that clearly suggests that activity definitions should be merged, rather than overwritten.
The only other possibly applicable reference seems to be in Data > 3.2 Hosted Metadata, specifically under the LRS requirements.
- The LRS MAY act as a Metadata Consumer and attempt to resolve identifier IRIs.
- If an Activity IRI is a URL, an LRS SHOULD attempt to GET that URL, and include in HTTP headers: Accept: application/json, /. This SHOULD be done as soon as practical after the LRS first encounters the Activity id.
- Upon loading JSON which is a valid Activity Definition from a URL used as an Activity id, an LRS SHOULD incorporate the loaded definition into its canonical definition for that Activity, while preserving names or definitions not included in the loaded definition.
- Upon loading any document from which the LRS can parse an Activity Definition from a URL used as an Activity id, an LRS MAY consider this definition when determining its canonical representation of that Activity's definition.
It's not clear to me whether the two SHOULDs there are only if the LRS chooses to act as a metadata consumer but, in any case, this is not what the test is covering since it's using IRIs that are not resolvable.
Is the test invalid, or does the specification need to be updated?
The merge behavior for JSON documents and activities has been a convention for as long as I can remember, but I'm also not finding it in either spec document anywhere.
Will ping Andy and see if he's more familiar with how this became a requirement.
Hello! Thanks for the inquiry. We really don't have to go too much further than the definition itself:
4.1.6.4 Activities Resource (/activities)
The Activities Resource provides a method to retrieve a full description of an Activity from the LRS.
We separate the concept of "full description" from "canonical" often in the standard, so much so that we probably gloss over full description a bit, but it is saying that all properties, if populated, are to be returned. By its nature, any property with a language map is really splitting itself into Y possible name/value pairs, where Y is the total number of possible languages. Usually the number of used languages, X, will be really low, but each of those X are distinct, just as if "type" were used in one description and "moreInfo" in another.
Hi Andy, thank you for the explanation. My objection here is really that the conformance tests are enforcing an behavior that is not clearly defined by the specification.
If we go back to the section you've taken "full description" from, one possible reading of it is that "full description" and "canonical" are actually inter-changable terms because the "Requirements" section actually uses the later:
If an LRS does not have a canonical definition of the Activity to return, the LRS SHOULD* still return an Activity Object when queried.
I'm fine with closing this issue out but, in that case, the specification should really be updated to be at least as clear as the test description.
Hey @integralla , thanks for the reply. I agree it could have been clearer, and that the requirement below can be confusing:
"If an LRS does not have a canonical definition of the Activity to return, the LRS shall still return an Activity Object when queried."
Actually could be translated into "human" as follows:
- The LRS cannot use the notion of "canonical" as an excuse to return nothing if the LRS does indeed have an activity with that activityId.
Because the LRS is given leeway in determining what canonical is, a simple solution would be that their definition of canonical is an empty set. This requirement attempts to move them off of this position and at least return an object. It also impacts the Statement Resource in returning valid activity definitions. I agree that its placement could cause the notions of full description and canonical to get intertwined.