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 中的欄位無論是必要或選填都不允許空值。

注意事項

• 上述每一屬性不可重複。
• 一筆語句 (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 可是是一個人或者一系統。

結構資訊

注意事項

• 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 用於沒有被明確定義的群組，例如：專案小組。

結構資訊

注意事項

• 組成時至少包括一個 member 物件。
• Anonymous Group Object 不可被包含於另一 Member 物件中。
• 不得包含 Inverse Functional Identifier 物件。

Identified Group

Identified Group 用於已被清楚(唯一)定義的群組。

結構資訊

注意事項

• 組成時必須要有 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 只能從下列四種擇一使用，不可使用任兩個以上。

結構資訊

Account Object

現有系統或服務中的使用者帳號。

結構資訊

範例

{
  "objectType": "Agent",
  "account": {
      "homePage": "http://www.example.com",
      "name": "1625378"
  }
}

動詞 (Verb)

　　動詞 (Verb) 指學習行為的「動作」，例如：「小明回答了一個問題」，其中的「回答」即為一個動詞 (Verb)。動作必須選自 Verb vocabularies 註冊表 (registry)，若需新增則應 CoP 提出申請。具體的動作定義有助於明確解讀發生的學習行為，而過度寬泛的動作定義會降低學習經歷的有效性。

結構資訊

注意事項

• 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 討論同意而新增。

結構資訊

definition

結構資訊

注意事項

• 每個活動 (Activity) 的 Id 必須要是唯一的。
• 同樣的 Activity Id 必須引用相同的活動 (Activity) 。

Interaction Activities

結構資訊

注意事項

• Interaction Activities 至少要有一個欄位。

Interaction Components

結構資訊

interactionType 支援種類如下：

注意事項

• 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 值必須為 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

　　表示學習者所取得的活動分級結果

結構資訊

注意事項

• 若分數可以轉換成百分比(%)則應該包括 scaled。
• 若此 score 無法展示進度或者分數，建議改用 extensions 來展現。

情境 (Context)

　　可添加一個情境至學習紀錄，例如：使用的平台、小組成員、指導者、版本、語言、地點、...等。在情境 (Context) 的 Attribute 下有數個 Properties 可被用來記錄許多相關資料，獲得相當完整的情境資訊。外圍情境資訊，例如：學習者的位置、環境因子 (溫度、背景噪音)，可以自定義新的項目 (向 VisCa 申請)。

結構資訊

注意事項

• 當此筆學習紀錄之對象 (Object) 為活動 (Activity) 時，才可使用 revision 屬性。
• 當此筆學習紀錄之對象 (Object) 為活動 (Activity) 時，才可使用 platform 屬性。
• 若此情境沒有指定特定語言則請勿使用 language 屬性。
• revision 屬性主要是用來修訂一些小錯誤（如：錯字）。
• 該活動若有重大改變，則請勿使用 revision 屬性修訂活動資訊。請使用新的 Activity id。

Registration Property

　　學習者進行特定學習活動時的一個實例。

ContextActivities Property

　　學習活動的類型。共有四種有效的情境類型：

1. Parent：一個彼此之間有直接關的活動。如：進行小測驗，此情境屬於 Parent。
2. Grouping：彼此間有間接關係的活動。如：某證照的一門課程，此 Grouping 情境為此門課程。
3. Category：類別型活動。如：安娜試圖進行考試，並且使用 CMI-5 profile 進行追蹤。考試是活動，而 CMI-5 profile 則是 Category。
4. 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)。

結構資訊

範例

{
    "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"
        }
    ]
}