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.

Sign up for GitHub

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

Jump to bottom

Updates to expand and clarify determining properties #258

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

Updates to expand and clarify determining properties #258

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a62b9f4
Made Changes to Expand Determining Properties
andyjohnson Jun 1, 2022
f13bfb3
Added Statement Template Properties/References
andyjohnson Jun 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
30 changes: 23 additions & 7 deletions xapi-profiles-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.


<a name="prof-props"></a>
## 6.0 Profile Properties
Expand Down Expand Up @@ -171,9 +171,14 @@ All Concepts in a Profile MUST follow the rules of one of the subsections within


<a name="verb-activity-attach"></a>
### 7.1 Verbs, Activity Types, and Attachment Usage Types
### 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.
Comment on lines +174 to +181
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.


Property | Type | Description | Required
-------- | ---- | ----------- | --------
Expand Down Expand Up @@ -428,7 +433,7 @@ The `description` includes guidance on how to interpret this Activity's use in S
<a name="statment-templates"></a>
## 8.0 Statement Templates

A Statement Template describes one way Statements following the Profile may be structured.
A Statement Template describes how Statements following the Profile MUST be structured.


Property | Type | Description | Required
Expand All @@ -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.

`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.

`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"

`objectActivityType` | IRI | Object activity type IRI | Optional
`contextGroupingActivityType` | Array | Array of contextActivities grouping activity type IRIs | Optional
`contextParentActivityType` | Array | Array of contextActivities parent activity type IRIs | Optional
`contextOtherActivityType` | Array | Array of contextActivities other activity type IRIs | Optional
Expand All @@ -452,12 +463,17 @@ Property | Type | Description | Required

A Statement Template MUST NOT have both `objectStatementRefTemplate` and `objectActivityType`.

The verb, object activity type, attachment usage types, and context activity types listed are called Determining Properties.
The verb, object activity type, homepage, extensions, category context activity, attachment usage types, and context activity types listed are called Determining Properties.

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

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

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


A Learning Record Provider authoring a Statement following a Statement Template:
* MUST include all the Determining Properties in the Statement Template.
* MUST include all the Determining Properties in the Statement Template. A Statement Template using multiple Determining Properties is considered an "AND" operation.
* MUST follow all rules in the Statement Template.
* MUST, if `objectStatementRefTemplate` is specified, set the Statement object to a StatementRef with the `id` of a Statement matching at least one of the specified Statement Templates.
* MUST, if `contextStatementRefTemplate` is specified, set the Statement context Statement property to a StatementRef with the `id` of a Statement matching at least one of the specified Statement Templates.
Expand Down