Updates to expand and clarify determining properties #258
Conversation
| @@ -80,7 +80,7 @@ To assist in accomplishing these two primary goals, Profiles also contain metada | |||
| <a name="using-prof-statements"></a> | |||
| ## 5.0 Using Profiles in Statements | |||
|
|
|||
| Using an introduced Concept, such as an activity type, verb, attachment usage type, extension, activity, or document resource, can be done freely, provided the defined usage and meaning are adhered to. But a Learning Record Provider can go further, and make sure to adhere to Profile-described Statement Templates and Patterns. Learning Record Providers authoring Statements that conform to matching Profile-described Statement Templates and Patterns SHOULD include the most up-to-date conformant Profile version as a category context activity with id equal to the version's `id` in those Statements, and Statements containing a Profile version as a category context activity MUST conform to any matching Statement Templates and Patterns that Profile version describes. | |||
| Using an introduced Concept, such as an activity type, verb, attachment usage type, extension, activity, or document resource, can be done freely, provided the defined usage and meaning are adhered to. But a Learning Record Provider can go further, and make sure to adhere to Profile-described Statement Templates and Patterns. Learning Record Providers authoring Statements that conform to matching Profile-described Statement Templates and Patterns SHOULD include the most up-to-date conformant Profile version as a category context activity with id equal to the version's `id` in those Statements, and Statements containing a Profile version as a category context activity MUST conform to any matching Statement Templates and Patterns that Profile version describes. An LRP is effectively declaring conformance to a specific Profile version BY including the category context activity with that Profile version's `id`. There is no other mechanism defined in this document that links a Statement to a particular xAPI Profile. However, not every category context activity has a specific xAPI Profile, it might simply be an activity id. | |||
There was a problem hiding this comment.
There is no other mechanism defined in this document that links a Statement to a particular xAPI Profile
I think this is something we can expand on in the WG. It may be valuable to support Statement Template(s) (and possibly Pattern(s)) category activities along side profile version.
- Including a Statement Template category activity is an explicit reference to the intended Statement Template
- Including a Pattern category activity indicates the statement was generated as part of a Pattern
- Including a Profile Version category activity would still have the same meaning
If the group chooses to go this route, we'll probably want to define Activity Types for Profile Version, Statement Template and Pattern. The Activity Type would then become a requirement for these category activities.
There was a problem hiding this comment.
Per the July 19, 2022 - agree that establishing the author's intent for a Statement to conform to a profile, pattern, or Statement template within that Statement is appropriate and this is the correct/optimal mechanism to do so. Patterns and Statement Templates would not be mandatory, nor would the xAPI Spec reserve those activity types at this time (future versions very likely may). The author assertions do not alleviate the need for a Statement tagged with a profile to be matched against all applicable patterns and Statement templates.
| @@ -441,6 +446,12 @@ Property | Type | Description | Required | |||
| `deprecated` | Boolean | A boolean, default false. If true, this Statement Template is deprecated. | Optional | |||
| `verb` | IRI | Verb IRI | Optional | |||
| `objectActivityType` | IRI | Object activity type IRI | Optional | |||
| `homepage` | IRL | Part of the Account object | Optional | |||
There was a problem hiding this comment.
I think this should get expanded to cover all IFIs
There was a problem hiding this comment.
Comment from the group on 6/7/2022 - should be all of the IFIs or none.
| @@ -441,6 +446,12 @@ Property | Type | Description | Required | |||
| `deprecated` | Boolean | A boolean, default false. If true, this Statement Template is deprecated. | Optional | |||
| `verb` | IRI | Verb IRI | Optional | |||
| `objectActivityType` | IRI | Object activity type IRI | Optional | |||
| `homepage` | IRL | Part of the Account object | Optional | |||
| `activityDefinitionExtension` key | IRI | The key of the extension of the Activity Definition Object | Optional | |||
There was a problem hiding this comment.
I think this description needs to be a little more specific or reworded. Its not clear to me if this is specifically the Statement Object Activity or any Activity in the statement.
There was a problem hiding this comment.
6/7/2022 - this can be for any Object (type of Activity), not just the Object of the Statement.
| `activityDefinitionExtension` key | IRI | The key of the extension of the Activity Definition Object | Optional | ||
| `resultExtension` key | IRI | The key of the extension of the Result Object | Optional | ||
| `contextExtension` key | IRI | The key of the extension of the Context Object | Optional | ||
| `contextCategoryContextActivity` key | IRI | The identifier of the Category Context Activity | Optional |
There was a problem hiding this comment.
I think this should be renamed (e.g. "profileVersion", "profileReference", etc.) to indicate its a profile version id/iri instead of an arbitrary category activity id. I also think this should be an array so that multiple references can be specified.
There was a problem hiding this comment.
Per 6/7/2022 , the first part of the comment is for line 453 and the second part is for 451-453. Multiple references should be allowed.
There was a problem hiding this comment.
So should be "Arrays"
| ### 7.1 Verbs, Activity Types, Category Context Activities and Attachment Usage Types | ||
|
|
||
| Verb, Activity Type, and Attachment Usage Type Concepts share the same properties. They're all Concepts that make sense to relate semantically to others of the same type, such as indicating one is a narrower form of another. | ||
| Verb, Activity Type, Category Context Activities, and Attachment Usage Type Concepts share the same properties. They're all Concepts that make sense to relate | ||
| semantically to others of the same type, such as indicating one is a narrower form of another. Category Context Activities were not included in the previous version, | ||
| but is expected that the Category Context Activity corresponding to the xAPI Profile would be a reserved term for that xAPI Profile, but would still be considered a | ||
| concept. Use of Category Context Activities also allows the "reserving" or "sub-profiling" where a full xAPI Profile may not be created, but the use of a "tag" is | ||
| needed within a profile. A Profile Creator SHOULD include the Category Context Activity corresponding to the xAPI Profile, versioning as appropriate, in its list of | ||
| Concepts. |
There was a problem hiding this comment.
I'm not sure if we want to add Category Context Activities as a concepts, activities are already concepts.
There was a problem hiding this comment.
Comment from the group on 6/7/2022 - believe this text was misplaced as no table in Section 7 was modified with an additional concept. We don't need a sub-type. We can try to work around making this addition and instead focus on Statement Templates and Patterns.
| A Profile Author MUST change a Statement Template's `id` between versions if any of the Determining Properties, StatementRef properties, or rules change. Changes of `scopeNote` are not considered changes in rules. | ||
| A Profile Author MUST change a Statement Template's `id` between versions if any of the Determining Properties, StatementRef properties, or rules change. | ||
| Changes of `scopeNote` are not considered changes in rules. | ||
| A Profile Author SHOULD create a Statement Template with a single Determining Property of the Category Context Activity |
There was a problem hiding this comment.
I think this is limiting / should be reworded to something like,
"A Profile Author SHOULD create Statement Templates with the profileReference Determining Property containing at least the Statement Templates' inScheme"
There was a problem hiding this comment.
Per 6/7/2022, Change the notion of lines 470-471 to say that the Profile should include at least a Statement Template that does those things. Capture that there are valid profiles without Statement Templates (however, this must be justified to the inherent inclusion of the context category context activity id in each Statement Template), Also do like the addition proposed by @FeLungs
| A Profile Author MUST change a Statement Template's `id` between versions if any of the Determining Properties, StatementRef properties, or rules change. | ||
| Changes of `scopeNote` are not considered changes in rules. | ||
| A Profile Author SHOULD create a Statement Template with a single Determining Property of the Category Context Activity | ||
| Other Statement Templates MAY use the Category Context Activity of the intended xAPI Profile in combination with another Determining Property. |
There was a problem hiding this comment.
I don't understand A Statement Template vs Other Statement Templates. Is this saying that at least one Statement Template in the profile must have the profile version reference determining property and then the rest do not have to?
There was a problem hiding this comment.
See comment above
| In previous versions of this document, and if a Statement Template with a single Determining Property of the Category Context Activity is not included, All Statement | ||
| Templates associated with this profile MUST consider that Category Context Activity as a Determining Property as it was an implicit requirement in previous versions. |
There was a problem hiding this comment.
I think it may be easier to make the profile version reference field required. Each Statement Template must include an array that includes at least the current profile version iri. Other Profile Version iris can be included but are not necessary
There was a problem hiding this comment.
6/7/2022 - Getting at the notion that we are making it an array as opposed to just the singular value.
Per the recommendation of the IEEE Profile Specification Working Group in May 2022, this pull request was created to expand the determining properties in the xAPI Profile Specification. This expansion includes only IRIs. Other changes were made for clarification.