Data Model
語句 (Statement) 組成
VisCa 的每一筆學習紀錄稱之為一筆語句 (Statement),由 JSON 組成,包含數個必要或非必要的屬性,數位學習服務可視其需要自由組合,但最少須包含「人」、「動作」與「活動」三個屬性。
語句 (Statement) 屬性
一個 xAPI statement 正好對應、記錄一個學習活動事件,其中至少含有主詞 (Actor)、動詞 (Verb)、對象 (Object),將其語句 (Statement) 後建立好後會儲存至學習記錄資料庫 (LRS,Learning Record Store)。當使用者進行學習活動時,活動提供者 (Activity Provider, AP) 負責送出這些語句 (Statement),並遵照設定 (Design Profile) 與處方 (Recipe) 規定,而其設計也將影響學習分析的成果。statement 中的欄位無論是必要或選填都不允許空值。
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
actor | Object | 主詞。此語句 (Statement) 的擁有者。 | 必要 |
verb | Object | 動詞。學生或學習小組之動作。 | 必要 |
object | Object | 對象。可以為活動 (Activity)、動作者 (Agent) 或者為另一個語句 (Statement) 物件。預設為活動 (Activity) 物件。 | 必要 |
result | Object | 此語句 (Statement) 之結果。可依照對應的動詞 (Verb) 取得對應結果。 | 選擇性 |
context | Object | 描繪此語句 (Statement) 之情境。 | 選擇性 |
timestamp | Date/Time | 產生時間,請依照 ISO 8601 之格式。 | 選擇性 |
authority | Object | 語句 (Statement) 擁有者 (例如:平台、廠商)。 | 選擇性 |
attachments | Array of attachment Objects | 欲加之附件資訊。 | 選擇性 |
version | Version | xAPI 版本號。 | 選擇性 |
注意事項
- 上述每一屬性不可重複。
- 一筆語句 (Statement) 至少要含有主詞 (actor)、動詞 (verb) 和對象 (object)。
- 屬性順序可自由排列。
範例
{
"id": "12345678-1234-5678-1234-567812345678",
"actor":{
"mbox":"mailto:xapi@adlnet.gov"
},
"verb":{
"id":"http://adlnet.gov/expapi/verbs/created",
"display":{
"zh-TW":"created"
}
},
"object":{
"id":"http://example.adlnet.gov/xapi/example/activity"
}
}
主詞 (Actor)
主詞 (Actor) 指進行學習行為的人,可以是「個人 (Agent Object)」 或 「群體(Group Object)」,兩種都必須有獨特的識別代碼,稱為「Inverse Functional Identifier」。
Agent Object
Agent Object 可是是一個人或者一系統。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
objectType | string | 請設置為 Agent | 選擇性 |
name | String | 腳色之全名。 | 選擇性 |
Inverse Functional Identifier,請參與此。 | 必要 |
注意事項
- Agent Object 必須要包含 Inverse Functional Identifier 中的 mbox。
- Agent Object 最多只能含有一組 Inverse Functional Identifier。
Group Object
Group Object 可以視為 Agent Object 的集合,並分為 Anonymous Group 和 Identified Group 兩類
Anonymous Group
Anonymous Group 用於沒有被明確定義的群組,例如:專案小組。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
objectType | String | 請設置為 Group | 必要 |
name | String | 群組名稱。 | 選擇性 |
member | Array of Agent Objects | 必要 |
注意事項
- 組成時至少包括一個 member 物件。
- Anonymous Group Object 不可被包含於另一 Member 物件中。
- 不得包含 Inverse Functional Identifier 物件。
Identified Group
Identified Group 用於已被清楚(唯一)定義的群組。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
objectType | String | Group | 必要 |
name | String | 群組名稱。 | 選擇性 |
member | Array of Agent Objects | 選擇性 | |
Inverse Functional Identifier,請參與此。 | 必要 |
注意事項
- 組成時必須要有 Inverse Functional Identifier 物件。
- Identified Group Object 不可被包含於另一 Member 物件中。
- 當 Identified Group 已使用 Agent identifiers 時,則不應該使用 Inverse Functional Identifier 物件。
- Identified Group Object 可擁有 member 物件。
Inverse Functional Identifier
- Inverse Functional Identifier 只能是動作者 (Agent) 或 Identified Group的值。
- Inverse Functional Identifier 只能從下列四種擇一使用,不可使用任兩個以上。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
mbox | mailto IRI | 格式為 "mailto: 電子郵件" | 選擇性 |
mbox_sha1sum | String | 將 mailto IRI 進行 SHA1 hash | 選擇性 |
openid | URI | 一個唯一的 openid | 選擇性 |
account | Object | 現有的使用者帳號資訊。 | 選擇性 |
Account Object
現有系統或服務中的使用者帳號。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
homePage | IRL | 此帳戶之服務首頁 | 必要 |
name | String | 帳戶的 ID | 必要 |
範例
{
"objectType": "Agent",
"account": {
"homePage": "http://www.example.com",
"name": "1625378"
}
}
動詞 (Verb)
動詞 (Verb) 指學習行為的「動作」,例如:「小明回答了一個問題」,其中的「回答」即為一個動詞 (Verb)。動作必須選自 Verb vocabularies 註冊表 (registry),若需新增則應 CoP 提出申請。具體的動作定義有助於明確解讀發生的學習行為,而過度寬泛的動作定義會降低學習經歷的有效性。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
id | IRI | 與動詞 (Verb) 對應的定義。IRI需要是可以被一般人所讀取的,並包含其動詞 (Verb) 之含意 | 必要 |
display | Language Map | 提供多語言之表示。 | 推薦 |
注意事項
- display 屬性必須是已先被 Verb IRI 所定義。
- display 屬性不能用來改變動詞的意涵。
- id IRI 需要是可以被一般人所讀取,並且含有動詞 (Verb) 的含意。
範例
{
"id":"http://www.adlnet.gov/XAPIprofile/ran(travelled_a_distance)",
"display":{
"en-US":"ran",
"es" : "corrió"
}
}
對象 (Object)
主詞 (Actor) 與之發生的對象即是對象 (Object),對象 (Object) 可以是一個活動 (Activity)、一個操作者(Agent)、一群操作者 (Group)、子學習紀錄 (Sub-Statement)、參考紀錄 (Statement Reference)等。若沒有特別指明,預設的對象則是活動 (Activity),其識別碼 id 將由活動提供者 (Activity Provider) 決定與維護,並且必須是 IRI,設定 (Design Profile) 或處方 (Recipe)。
Activity ObjectType
活動 (Activity) 是最常發生的對象種類,它的含意相當廣泛,可以是一個學習資源、一個網頁、一堂課、一段影片、一次模擬飛行。另外,必須確保每個活動 (Activity) 必須有獨特識別碼 (id,符合 IRI 規格),該 id 僅對應一個活動 (Activity),連到說明資訊網頁,並必須宣告其活動型態 (ActivityType) ,ActivityType 也是一種 Controlled Vocabulary (限制詞),必須使用事先已註冊的語彙或由 VisCa 討論同意而新增。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
objectType | String | 請設置為 Activity | 必要 |
id | IRI | 一個唯一的 Activity Id | 必要 |
definition | Object | 元數據 (Metadata) | 選擇性 |
definition
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
name | Language Map | 該活動(影片)之名稱 | 推薦 |
description | Language Map | 此活動之敘述 | 推薦 |
type | IRI | 活動類型 | 推薦 |
moreInfo | IRL | 提供更多關於此活動之訊息 | 選擇性 |
Interaction properties,請參閱 Interaction Activities | |||
extensions | Object | 根據需要使用其他屬物件 | 選擇性 |
注意事項
- 每個活動 (Activity) 的 Id 必須要是唯一的。
- 同樣的 Activity Id 必須引用相同的活動 (Activity) 。
Interaction Activities
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
interactionType | String | 例如:"cmi.interactions.n.type" | 選擇性 |
correctResponsesPattern | An array of strings | 例如:"cmi.interactions.n.correct_responses.n.pattern" | 選擇性 |
choices | scale | source | target | steps | Array of interaction components | 選擇性 |
注意事項
- Interaction Activities 至少要有一個欄位。
Interaction Components
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
id | String | 必要 | |
description | Language Map | 選擇性 |
interactionType 支援種類如下:
interactionType | component |
---|---|
choice, sequencing | choices |
likert | scale |
matching | source, target |
performance | steps |
true-false, fill-in, long-fill-in, numeric, other | [No component lists defined] |
注意事項
- Interaction Components 中的 ID 不可為空。
- 在 Interaction Components 陣列中,所有的 ID 必須是不同的。
ObjectType - Agent or Group
規則內容與主詞 (Actor) 相同。
ObjectType - Statement
使用語句 (Statement) 作為對象 (Object) 有兩種情況,一種是參考紀錄(Statement References),其引用已存在之語句 (Statement),例如:評論;另一則是使用新的語句 (Statement),稱為 Sub-Statement。
Statement References
Statement References 是引用一已預先存在之語句 (Statement)。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
objectType | String | StatementRef | 必要 |
id | UUID | Statement 的 UUID | 必要 |
注意事項
- objectType 值必須為 StatementRef。
範例
{
"actor" : {
"objectType": "Agent",
"mbox":"mailto:test@example.com"
},
"verb" : {
"id":"http://example.com/commented",
"display": {
"en-US":"commented"
}
},
"object" : {
"objectType":"StatementRef",
"id":"8f87ccde-bb56-4c2e-ab83-44982ef22df0"
},
"result" : {
"response" : "Wow, nice work!"
}
}
Sub-Statements
存在於另一語句 (Statement) 之下的語句 (Statement) 為 Sub-Statement。
注意事項
- objectType 值必須為 SubStatement。
- Sub-Statement 中不可擁有 id、version、authority等屬性。
- Sub-Statement 中不能包含其他 Sub-Statement。
範例
{
"actor": {
"objectType": "Agent",
"mbox":"mailto:test@example.com"
},
"verb" : {
"id":"http://example.com/planned",
"display":{
"en-US":"planned"
}
},
"object": {
"objectType": "SubStatement",
"actor" : {
"objectType": "Agent",
"mbox":"mailto:test@example.com"
},
"verb" : {
"id":"http://example.com/visited",
"display":{
"en-US":"will visit"
}
},
"object": {
"id":"http://example.com/website",
"definition": {
"name" : {
"en-US":"Some Awesome Website"
}
}
}
}
}
Result (結果)
此語句 (Statement) 的量測結果,包括是否完成、是否通過、原始得分、題目得分範圍、所花費時間、學習者的選擇與送出內容 ... 等等,還可自定義新的資料項目 (向 VisCa 申請)。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
score | Object | 動作者的分數資訊 | 選擇性 |
success | Boolean | 動作者此次的活動成功與否 | 選擇性 |
completion | Boolean | 動作者此次的活動完成與否 | 選擇性 |
response | String | 對於此活動的回應,須採固定格式 | 選擇性 |
duration | Formatted according to ISO 8601 with a precision of 0.01 seconds | 表示此活動之持續時間 | 選擇性 |
extensions | Object | 對應其他欲表達之元素 | 選擇性 |
Score
表示學習者所取得的活動分級結果
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
scaled | Decimal numbe,-1 到 1之間 | Cf. 'cmi.score.scaled' 於 SCORM 2004 4th Edition | 推薦 |
raw | Decimal numbe,最大最小值之間 | 原始數。Cf. 'cmi.score.raw' | 選擇性 |
min | Decimal numbe | 表示該次對象的最低分。Cf. 'cmi.score.min' | 選擇性 |
max | Decimal numbe | 表示該次對象的最高分。Cf. 'cmi.score.max' | 選擇性 |
注意事項
- 若分數可以轉換成百分比(%)則應該包括 scaled。
- 若此 score 無法展示進度或者分數,建議改用 extensions 來展現。
情境 (Context)
可添加一個情境至學習紀錄,例如:使用的平台、小組成員、指導者、版本、語言、地點、...等。在情境 (Context) 的 Attribute 下有數個 Properties 可被用來記錄許多相關資料,獲得相當完整的情境資訊。外圍情境資訊,例如:學習者的位置、環境因子 (溫度、背景噪音),可以自定義新的項目 (向 VisCa 申請)。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
registration | UUID | 由學習紀錄所定義之 registration | 選擇性 |
instructor | Agent | 如果教學者不是動作者時,請填寫教學者 | 選擇性 |
team | Group | 如果團隊本身不是動作者時,請填寫團隊資訊 | 選擇性 |
contextActivities | contextActivities Object | 學習活動情境之各類型資訊。有效的類型:parent、grouping、category、other | 選擇性 |
revision | String | 此筆學習活動之修訂紀錄。沒有特定格式 | 選擇性 |
platform | String | 此筆活動紀錄之使用平台 | 選擇性 |
language | String (RFC 5646) | 此情境中使用之語言 | 選擇性 |
statement | Statement Reference | 學習活動情境之參考紀錄 | 選擇性 |
extensions | Object | 其他的特殊情境元素。舉例:飛行模擬器中有關的事物,高度、速度、風、飛行姿 & 態、GPS | 選擇性 |
注意事項
- 當此筆學習紀錄之對象 (Object) 為活動 (Activity) 時,才可使用 revision 屬性。
- 當此筆學習紀錄之對象 (Object) 為活動 (Activity) 時,才可使用 platform 屬性。
- 若此情境沒有指定特定語言則請勿使用 language 屬性。
- revision 屬性主要是用來修訂一些小錯誤(如:錯字)。
- 該活動若有重大改變,則請勿使用 revision 屬性修訂活動資訊。請使用新的 Activity id。
Registration Property
學習者進行特定學習活動時的一個實例。
ContextActivities Property
學習活動的類型。共有四種有效的情境類型:
- Parent:一個彼此之間有直接關的活動。如:進行小測驗,此情境屬於 Parent。
- Grouping:彼此間有間接關係的活動。如:某證照的一門課程,此 Grouping 情境為此門課程。
- Category:類別型活動。如:安娜試圖進行考試,並且使用 CMI-5 profile 進行追蹤。考試是活動,而 CMI-5 profile 則是 Category。
- Other:不屬於上述之活動類型時,請使用此情境。例如:安娜閱讀教科書為了生物學考試。此範例的活動是閱讀教科書,而活動類型屬於 Other。
注意事項
- 在 contextActivities 中,每個 Key 值必定是 parent、grouping、category、other。
- contextActivities 中的物件需以陣列形式存在,非單一物件。
範例
{
"parent" : [
{"id" : "http://example.adlnet.gov/xapi/example/test1"}
],
"grouping" : [
{"id" : "http://example.adlnet.gov/xapi/example/Algebra1"}
]
}
時間戳記 (Timestamp)
學習經歷發生的時間點。
注意事項
- 必須依照 ISO 8601 格式。
- 必須包含時區資訊。
- 當時間戳記 (Timestamp) 不是存在於 Sub-Statement 中時,範圍必須是當下或過去時間。
- 時間戳記 (Timestamp) 精度至毫秒 (保留毫秒)。
- 時間戳記 (Timestamp) 可以為未來的某個時間點,作為表示一個學習計畫的期限,並僅限存在於 Sub-Statement。
Authority
此筆紀錄的擁有者;敘述此筆學習紀錄是由誰 (人、系統、應用程式) 產生。
範例
"authority": {
"objectType" : "Group",
"member": [
{
"account": {
"homePage":"http://example.com/xAPI/OAuth/Token",
"name":"oauth_consumer_x75db"
}
},
{
"mbox":"mailto:bob@example.com"
}
]
}
附件 (Attachments)
若此語句 (Statement) 有額外檔案需要夾帶時,則使用附件 (Attachments)。
結構資訊
屬性 | 型態 | 簡述 | 必要性 |
---|---|---|---|
usageType | IRI | 定義此附件 | 必要 |
display | Language Map | 此附件的顯示名稱 | 必要 |
description | Language Map | 關於此附件的敘述 | 選擇性 |
contentType | Internet Media Type | 附件內容的類型 | 必要 |
length | Integer | 附件資料的長度資訊 | 必要 |
sha2 | String | 將附件進行 SHA-2 (SHA-256、SHA-384、SHA-512)。不得使用 SHA-224。建議最小的 Key 值長度為 256 bits | 必要 |
fileUrl | IRL | 一個可以被檢視的附件資料 IRL | 選擇性 |
範例
{
"actor": {
"mbox": "mailto:sample.agent@example.com",
"name": "Sample Agent",
"objectType": "Agent"
},
"verb": {
"id": "http://adlnet.gov/expapi/verbs/answered",
"display": {
"en-US": "answered"
}
},
"object": {
"id": "http://www.example.com/tincan/activities/multipart",
"objectType": "Activity",
"definition": {
"name": {
"en-US": "Multi Part Activity"
},
"description": {
"en-US": "Multi Part Activity Description"
}
}
},
"attachments": [
{
"usageType": "http://example.com/attachment-usage/test",
"display": {"en-US": "A test attachment"},
"description": {"en-US": "A test attachment (description)" },
"contentType": "text/plain; charset=ascii",
"length": 27,
"sha2": "495395e777cd98da653df9615d09c0fd6bb2f8d4788394cd53c56a3bfdcd848a"
}
]
}