Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to expand and clarify determining properties #258

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

andyjohnson
Copy link
Collaborator

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.

@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should get expanded to cover all IFIs

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So should be "Arrays"

Comment on lines +174 to +181
### 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if we want to add Category Context Activities as a concepts, activities are already concepts.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See comment above

Comment on lines +472 to +473
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

6/7/2022 - Getting at the notion that we are making it an array as opposed to just the singular value.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants