docs: Fill in missing doc descriptions and types

models/_docs/docs.md

@@ -0,0 +1,120 @@
+
+{% docs actor_id %}
+The "id" portion of the xAPI Actor for this event. See: https://xapi.com/statements-101/#actor
+
+The LMS can be configured to send different identifiers for an actor, but they are all stored as Strings in ClickHouse: https://docs.openedx.org/projects/openedx-aspects/en/latest/technical_documentation/how-tos/changing_actor_identifier.html
+
+{% enddocs %}
+
+# TODO: link to Opaque Keys docs
+{% docs block_id %}
+The unique XBlock usage key for this block
+{% enddocs %}
+
+# TODO: link to Opaque Keys docs
+{% docs course_key %}
+The CourseKey for this course run
+{% enddocs %}
+
+{% docs course_name %}
+The name of the course
+{% enddocs %}
+
+{% docs course_order %}
+The sort order of this block in the course across all course blocks
+{% enddocs %}
+
+{% docs course_run %}
+The course run for the course
+{% enddocs %}
+
+{% docs display_name %}
+The XBlock's display name
+{% enddocs %}
+
+{% docs dump_id %}
+The UUID of the event sink run that publishes to ClickHouse. When an event is published, all data is sent with the same dump_id.
+{% enddocs %}
+
+{% docs email %}
+The email address of the learner from the LMS user table. When Aspects PII syncing is off this will be empty.
+{% enddocs %}
+
+{% docs emission_time %}
+Timestamp, to the second, of when this event was emitted
+{% enddocs %}
+
+{% docs enrollment_mode %}
+The mode of enrollment such as "audit", "verified", or instance-specific values.
+{% enddocs %}
+
+{% docs enrollment_status %}
+Whether a learner is actively enrolled in a course
+{% enddocs %}
+
+{% docs event_id %}
+The unique identifier for the xAPI event, represented as a UUID v5 string, and based upon the actor id, verb, and event timestamp.
+{% enddocs %}
+
+{% docs graded %}
+Whether the block is graded
+{% enddocs %}
+
+{% docs id %}
+The primary key value for this row in the edx-platform MySQL database
+{% enddocs %}
+
+{% docs learner_name %}
+The full name of the learner based on their edx-platform UserProfile "name" field
+{% enddocs %}
+
+{% docs object_id %}
+The "id" portion of the xAPI Object resource identifier (IRI), stores as a String. See: https://xapi.com/statements-101/#object
+{% enddocs %}
+
+{% docs org %}
+The organization that the course belongs to, this value is extracted from the course key
+{% enddocs %}
+
+{% docs section_block_id %}
+The location of this subsection in the course, represented as <section location>:<subsection location>:0
+{% enddocs %}
+
+{% docs section_number %}
+The location of this section in the course, represented as <section location>:0:0
+{% enddocs %}
+
+{% docs section_with_name %}
+The name of the section this block belongs to, with section_number prepended
+{% enddocs %}
+
+{% docs subsection_block_id %}
+The unique identifier for the subsection block
+{% enddocs %}
+
+{% docs subsection_number %}
+The location of this subsection in the course, represented as <section location>:<subsection location>:0
+{% enddocs %}
+
+{% docs subsection_with_name %}
+The name of the subsection, with section_number prepended
+{% enddocs %}
+
+{% docs time_last_dumped %}
+The datetime of the event sink run that publishes to ClickHouse. When an event is published, all data is sent with the same time_last_dumped.
+{% enddocs %}
+
+{% docs username %}
+The username of the learner from the LMS user table. When Aspects PII syncing is off this will be empty.
+{% enddocs %}
+
+{% docs verb_id %}
+The "id" portion of the xAPI Verb for this event. See: https://xapi.com/statements-101/#verb
+{% enddocs %}
+
+
+{% docs object_tag_source %}
+Course objects and their associated tags from CMS events:  
+`COURSE_CREATED, XBLOCK_CREATED, LIBRARY_BLOCK_CREATED, CONTENT_OBJECT_ASSOCIATIONS_CHANGED`  
+and `post_save` Django signal on the Object Tag model
+{% enddocs %}

models/base/schema.yml

@@ -6,28 +6,28 @@ models:
     columns:
       - name: event_id
         data_type: UUID
-        description: "The unique identifier for the event"
+        description: '{{ doc("event_id") }}'
       - name: verb_id
         data_type: String
-        description: "The xAPI verb identifier"
+        description: '{{ doc("verb_id") }}'
       - name: actor_id
         data_type: String
-        description: "The xAPI actor identifier"
+        description: '{{ doc("actor_id") }}'
       - name: object_id
         data_type: String
-        description: "The xAPI object identifier"
+        description: '{{ doc("object_id") }}'
       - name: course_id
         data_type: String
         description: "The fully-qualified course identifier URL"
       - name: course_key
         data_type: String
-        description: "The course key for the course"
+        description: '{{ doc("course_key") }}'
       - name: org
         data_type: String
-        description: "The organization that the course belongs to"
+        description: '{{ doc("org") }}'
       - name: emission_time
         data_type: DateTime64(6)
-        description: "The time the event was emitted"
+        description: '{{ doc("emission_time") }}'
       - name: event
         data_type: String
         description: "The xAPI event as a String"

models/base/sources.yml

@@ -3,12 +3,18 @@ version: 2
 sources:
   - name: xapi
     database: "{{ env_var('ASPECTS_XAPI_DATABASE', 'xapi') }}"
-    description: "the xapi database in clickhouse"
+    description: "Clickhouse database for xapi events"
     tables:
       - name: xapi_events_all
         identifier: "{{ env_var('ASPECTS_VECTOR_RAW_XAPI_TABLE', 'xapi_events_all') }}"
         description: "Base table for raw xAPI events"
         columns:
           - name: event_id
+            type: UUID
+            description: '{{ doc("event_id") }}'
           - name: emission_time
+            type: DateTime64(6)
+            description: '{{ doc("emission_time") }}'
           - name: event
+            type: String
+            description: "The JSON representation of this xAPI event, stored as a String"

models/courses/schema.yml

@@ -6,28 +6,28 @@ models:
     columns:
       - name: org
         data_type: String
-        description: "The organization that the course belongs to"
+        description: '{{ doc("org") }}'
       - name: course_key
         data_type: String
-        description: "The course key for the course"
+        description: '{{ doc("course_key") }}'
       - name: course_name
         data_type: String
-        description: "The name of the course"
+        description: '{{ doc("course_name") }}'
       - name: course_run
         data_type: String
-        description: "The course run for the course"
+        description: '{{ doc("course_run") }}'
       - name: block_id
         data_type: String
-        description: "The block's unique identifier"
+        description: '{{ doc("block_id") }}'
       - name: block_name
         data_type: String
         description: "The block's name"
       - name: section_number
         data_type: String
-        description: "The section this block belongs to, formatted as <section location>:0:0"
+        description: '{{ doc("section_number") }}'
       - name: subsection_number
         data_type: String
-        description: "The subsection this block belongs to, formatted as <section location>:<subsection location>:0"
+        description: '{{ doc("subsection_number") }}'  
       - name: hierarchy_location
         data_type: String
         description: "The full section:subsection:unit hierarchy in which this block belongs"
@@ -36,10 +36,10 @@ models:
         description: "The block's display name with section, subsection, and unit prepended to the name. This provides additional context when looking at block names and can help data consumers understand which block they are analyzing"
       - name: course_order
         data_type: Int32
-        description: "The sort order of this block in the course across all course blocks"
+        description: '{{ doc("course_order") }}'
       - name: graded
         data_type: Boolean
-        description: "Whether the block is graded"
+        description: '{{ doc("graded") }}'
       - name: block_type
         data_type: String
         description: "The type of block. This can be a section, subsection, unit, or the block type"
@@ -55,16 +55,16 @@ models:
         description: "The name of the block"
       - name: course_key
         data_type: String
-        description: "The course which the block belongs to"
+        description: '{{ doc("course_key") }}'
       - name: graded
         data_type: Boolean
-        description: "Whether the block is graded"
+        description: '{{ doc("graded") }}'
       - name: display_name_with_location
         data_type: String
         description: "The block's display name with section, subsection, and unit prepended to the name. This provides additional context when looking at block names and can help data consumers understand which block they are analyzing"
       - name: course_order
         data_type: Int32
-        description: "The sort order of this block in the course across all course blocks"
+        description: '{{ doc("course_order") }}'
       - name: section
         data_type: Int32
         description: "The section number that this block falls under in the course. Starts at 1."
@@ -76,10 +76,10 @@ models:
         description: "The unit number that this block falls under in the subsection. Starts at 1."
       - name: dump_id
         data_type: UUID
-        description: "The UUID of the event sink run that published this block to ClickHouse. When a course is published all blocks inside it are sent with the same dump_id."
+        description: '{{ doc("dump_id") }}'
       - name: time_last_dumped
         data_type: String
-        description: "The Datetime of the event sink run that published this block to ClickHouse. When a course is published all blocks inside it are sent with the same time_last_dumped."
+        description: '{{ doc("time_last_dumped") }}'
 
   - name: most_recent_course_blocks
     description: "A materialized view of course blocks with their display names and additional metadata. Only stores the most recent row per block location."
@@ -92,16 +92,16 @@ models:
         description: "The name of the block"
       - name: course_key
         data_type: String
-        description: "The course which the block belongs to"
+        description: '{{ doc("course_key") }}'
       - name: graded
         data_type: Boolean
-        description: "Whether the block is graded"
+        description: '{{ doc("graded") }}'
       - name: display_name_with_location
         data_type: String
         description: "The block's display name with section, subsection, and unit prepended to the name. This provides additional context when looking at block names and can help data consumers understand which block they are analyzing"
       - name: course_order
         data_type: Int32
-        description: "The sort order of this block in the course across all course blocks"
+        description: '{{ doc("course_order") }}'
       - name: section
         data_type: Int32
         description: "The section number that this block falls under in the course. Starts at 1."
@@ -113,54 +113,54 @@ models:
         description: "The unit number that this block falls under in the subsection. Starts at 1."
       - name: dump_id
         data_type: UUID
-        description: "The UUID of the event sink run that published this block to ClickHouse. When a course is published all blocks inside it are sent with the same dump_id."
+        description: '{{ doc("dump_id") }}'
       - name: time_last_dumped
         data_type: String
-        description: "The datetime of the event sink run that published this block to ClickHouse. When a course is published all blocks inside it are sent with the same time_last_dumped."
+        description: '{{ doc("time_last_dumped") }}'
 
   - name: course_names
-    description: "A table of courses with their names"
+    description: "A dictionary of courses with their names"
     columns:
       - name: course_key
         data_type: String
-        description: "The course key for the course"
+        description: '{{ doc("course_key") }}'
       - name: course_name
         data_type: String
-        description: "The name of the course"
+        description: '{{ doc("course_name") }}'
       - name: course_run
         data_type: String
-        description: "The course run for the course"
+        description: '{{ doc("course_run") }}'
       - name: org
         data_type: String
-        description: "The organization that the course belongs to"
+        description: '{{ doc("org") }}'
 
   - name: dim_course_blocks_extended
     description: "dim_course_blocks with section and subsection names joined into the data."
     columns:
       - name: org
         data_type: String
-        description: "The organization that the course belongs to"
+        description: '{{ doc("org") }}'
       - name: course_key
         data_type: String
-        description: "The course key for the course"
+        description: '{{ doc("course_key") }}'
       - name: course_name
         data_type: String
-        description: "The name of the course"
+        description: '{{ doc("course_name") }}'
       - name: course_run
         data_type: String
-        description: "The course run for the course"
+        description: '{{ doc("course_run") }}'
       - name: block_id
         data_type: String
-        description: "The block's unique identifier"
+        description: '{{ doc("block_id") }}'
       - name: block_name
         data_type: String
         description: "The block's name"
       - name: section_number
         data_type: String
-        description: "The section this block belongs to, formatted as <section location>:0:0"
+        description: '{{ doc("section_number") }}'
       - name: subsection_number
         data_type: String
-        description: "The subsection this block belongs to, formatted as <section location>:<subsection location>:0"
+        description: '{{ doc("subsection_number") }}'
       - name: hierarchy_location
         data_type: String
         description: "The full section:subsection:unit hierarchy in which this block belongs"
@@ -169,16 +169,16 @@ models:
         description: "The block's display name with section, subsection, and unit prepended to the name. This provides additional context when looking at block names and can help data consumers understand which block they are analyzing"
       - name: graded
         data_type: Boolean
-        description: "Whether the block is graded"
+        description: '{{ doc("graded") }}'
       - name: block_type
         data_type: String
         description: "The type of block. This can be a section, subsection, unit, or the block type"
       - name: section_with_name
         data_type: String
-        description: "The name of the section this block belongs to, with section_number prepended"
+        description: '{{ doc("section_with_name") }}'
       - name: subsection_with_name
         data_type: String
-        description: "The name of the section this subsection belongs to, with subsection_number prepended"
+        description: '{{ doc("subsection_with_name") }}'
       - name: course_order
         data_type: Int32
-        description: "The sort order of this block in the course across all course blocks"
+        description: '{{ doc("course_order") }}'