Skip to content

E
edx-platform
Commit 4f917a89 by Alison Hodges
Options

Added pretty-printed JSON examples for DOC-168, fixed rst subheadings

parent 2d6bfbad
Showing with 179 additions and 43 deletions
docs/en_us/data/source/internal_data_formats/change_log.rst
...@@ -10,6 +10,8 @@ Change Log ...@@ -10,6 +10,8 @@ Change Log
* - Date * - Date
- Change - Change
* - 19 Mar 2014
- Provided alternative formatting for the examples in the :ref:`Discussion Forums Data` chapter.
* - 13 Mar 2014 * - 13 Mar 2014
- Updated the :ref:`Student_Info` chapter. - Updated the :ref:`Student_Info` chapter.
* - 24 Feb 14 * - 24 Feb 14
......
docs/en_us/data/source/internal_data_formats/discussion_data.rst
...@@ -22,39 +22,147 @@ A sample of the field/value pairs that are in the mongo file, and descriptions o ...@@ -22,39 +22,147 @@ A sample of the field/value pairs that are in the mongo file, and descriptions o
Samples Samples
********* *********
Two sample rows, or documents, from a mongo file of discussion data follow. Two sample rows, or JSON documents, from a .mongo file of discussion data follow. The JSON documents are minified before they are added to the log file, so they appear in compact format.
----------------------------------------
CommentThread Document Example CommentThread Document Example
---------------------------------------- ----------------------------------------
.. code-block:: json .. code-block:: json
{ "_id" : { "$oid" : "50f1dd4ae05f6d2600000001" }, "_type" : "CommentThread", "anonymous" : false, { "_id" : { "$oid" : "50f1dd4ae05f6d2600000001" }, "_type" : "CommentThread", "anonymous" :
"anonymous_to_peers" : false, "at_position_list" : [], "author_id" : "NNNNNNN", "author_username" : false, "anonymous_to_peers" : false, "at_position_list" : [], "author_id" : "NNNNNNN",
"AAAAAAAAAA", "body" : "Welcome to the edX101 forum!\n\nThis forum will be regularly monitored by "author_username" : "AAAAAAAAAA", "body" : "Welcome to the edX101 forum!\n\nThis forum will
edX. Please post your questions and comments here. When asking a question, don't forget to search be regularly monitored by edX. Please post your questions and comments here. When asking a
the forum to check whether your question has already been answered.\n\n", "closed" : false, question, don't forget to search the forum to check whether your question has already been
"comment_count" : 0, "commentable_id" : "i4x-edX-edX101-course-How_to_Create_an_edX_Course", answered.\n\n", "closed" : false, "comment_count" : 0, "commentable_id" : "i4x-edX-edX101-
"course_id" : "edX/edX101/How_to_Create_an_edX_Course", "created_at" : { "$date" : 1358028106904 }, course-How_to_Create_an_edX_Course", "course_id" : "edX/edX101/How_to_Create_an_edX_Course",
"last_activity_at" : { "$date" : 1358134464424 }, "tags_array" : [], "title" : "Welcome to the "created_at" : { "$date" : 1358028106904 }, "last_activity_at" : { "$date" : 1358134464424 },
edX101 forum!", "updated_at" : { "$date" : 1358134453862 }, "votes" : { "count" : 1, "down" : [], "tags_array" : [], "title" : "Welcome to the edX101 forum!", "updated_at" : { "$date" :
"down_count" : 0, "point" : 1, "up" : [ "48" ], "up_count" : 1 } } 1358134453862 }, "votes" : { "count" : 1, "down" : [], "down_count" : 0, "point" : 1, "up" :
[ "48" ], "up_count" : 1 } }
If you use a JSON formatter to "pretty print" this document, a version that is more readable is produced.
.. code-block:: json
{
"_id": {
"$oid": "50f1dd4ae05f6d2600000001"
},
"_type": "CommentThread",
"anonymous": false,
"anonymous_to_peers": false,
"at_position_list": [
],
"author_id": "NNNNNNN",
"author_username": "AAAAAAAAAA",
"body": "Welcome to the edX101 forum!\n\nThis forum will be regularly monitored by edX. Please
post your questions and comments here. When asking a question, don't forget to search the
forum to check whether your question has already been answered.\n\n",
"closed": false,
"comment_count": 0,
"commentable_id": "i4x-edX-edX101-course-How_to_Create_an_edX_Course",
"course_id": "edX\/edX101\/How_to_Create_an_edX_Course",
"created_at": {
"$date": 1358028106904
},
"last_activity_at": {
"$date": 1358134464424
},
"tags_array": [
],
"title": "Welcome to the edX101 forum!",
"updated_at": {
"$date": 1358134453862
},
"votes": {
"count": 1,
"down": [
],
"down_count": 0,
"point": 1,
"up": [
"48"
],
"up_count": 1
}
}
----------------------------------------
Comment Document Example Comment Document Example
---------------------------------------- ----------------------------------------
.. code-block:: json .. code-block:: json
{ "_id" : { "$oid" : "52e54fdd801eb74c33000070" }, "votes" : { "up" : [], "down" : [], "up_count" : { "_id" : { "$oid" : "52e54fdd801eb74c33000070" }, "votes" : { "up" : [], "down" : [],
0, "down_count" : 0, "count" : 0, "point" : 0 }, "visible" : true, "abuse_flaggers" : [], "up_count" : 0, "down_count" : 0, "count" : 0, "point" : 0 }, "visible" : true,
"historical_abuse_flaggers" : [], "parent_ids" : [], "at_position_list" : [], "body" : "I'm hoping "abuse_flaggers" : [], "historical_abuse_flaggers" : [], "parent_ids" : [], "at_position_list" :
this Demonstration course will help me figure out how to take the course I registered for. I am just [], "body" : "I'm hoping this Demonstration course will help me figure out how to take the
auditing the course, but I want to benefit from it as much as possible, as I am extremely interested course I registered for. I am just auditing the course, but I want to benefit from it as much
in it.\n", "course_id" : "edX/DemoX/Demo_Course", "_type" : "Comment", "endorsed" : false, "anonymous" as possible, as I am extremely interested in it.\n", "course_id" : "edX/DemoX/Demo_Course",
: false, "anonymous_to_peers" : false, "author_id" : "NNNNNNN", "comment_thread_id" : { "$oid" : "_type" : "Comment", "endorsed" : false, "anonymous" : false, "anonymous_to_peers" : false,
"52e4e880c0df1fa59600004d" }, "author_username" : "AAAAAAAAAA", "sk" : "52e54fdd801eb74c33000070", "author_id" : "NNNNNNN", "comment_thread_id" : { "$oid" : "52e4e880c0df1fa59600004d" },
"updated_at" : { "$date" : 1390759901966 }, "created_at" : { "$date" : 1390759901966 } } "author_username" : "AAAAAAAAAA", "sk" : "52e54fdd801eb74c33000070", "updated_at" :
{ "$date" : 1390759901966 }, "created_at" : { "$date" : 1390759901966 } }
When pretty printed, this comment looks like this:
.. code-block:: json
{
"_id": {
"$oid": "52e54fdd801eb74c33000070"
},
"votes": {
"up": [
],
"down": [
],
"up_count": 0,
"down_count": 0,
"count": 0,
"point": 0
},
"visible": true,
"abuse_flaggers": [
],
"historical_abuse_flaggers": [
],
"parent_ids": [
],
"at_position_list": [
],
"body": "I'm hoping this Demonstration course will help me figure out how to take the
course I registered for. I am just auditing the course, but I want to benefit from it
as much as possible, as I am extremely interested in it.\n",
"course_id": "edX\/DemoX\/Demo_Course",
"_type": "Comment",
"endorsed": false,
"anonymous": false,
"anonymous_to_peers": false,
"author_id": "NNNNNNN",
"comment_thread_id": {
"$oid": "52e4e880c0df1fa59600004d"
},
"author_username": "AAAAAAAAAA",
"sk": "52e54fdd801eb74c33000070",
"updated_at": {
"$date": 1390759901966
},
"created_at": {
"$date": 1390759901966
}
}
***************** *****************
Shared Fields Shared Fields
...@@ -62,58 +170,70 @@ Shared Fields ...@@ -62,58 +170,70 @@ Shared Fields
Descriptions of the fields that are present for both ``CommentThread`` and ``Comment`` objects follow. Descriptions of the fields that are present for both ``CommentThread`` and ``Comment`` objects follow.
--------------------
_id _id
----- --------------------
The 12-byte MongoDB unique ID for this collection. Like all MongoDB IDs, the IDs are monotonically increasing and the first four bytes are a timestamp. The 12-byte MongoDB unique ID for this collection. Like all MongoDB IDs, the IDs are monotonically increasing and the first four bytes are a timestamp.
--------------------
_type _type
------- --------------------
``CommentThread`` or ``Comment`` depending on the type of object. ``CommentThread`` or ``Comment`` depending on the type of object.
--------------------
anonymous anonymous
----------- --------------------
If true, this ``CommentThread`` or ``Comment`` displays in the user interface as written by "anonymous", even to those who have course staff or discussion administration roles in the course. If true, this ``CommentThread`` or ``Comment`` displays in the user interface as written by "anonymous", even to those who have course staff or discussion administration roles in the course.
--------------------
anonymous_to_peers anonymous_to_peers
-------------------- --------------------
If true, this ``CommentThread`` or ``Comment`` displays in the user interface as written by "anonymous" to students, but course staff and discussion administrators see the author's username. If true, this ``CommentThread`` or ``Comment`` displays in the user interface as written by "anonymous" to students, but course staff and discussion administrators see the author's username.
--------------------
at_position_list at_position_list
------------------ --------------------
No longer used. Child comments (replies) are sorted by their ``created_at`` timestamp only. No longer used. Child comments (replies) are sorted by their ``created_at`` timestamp only.
--------------------
author_id author_id
----------- --------------------
Identifies the user who wrote this. Corresponds to the user IDs stored in the MySQL database as ``auth_user.id``. Identifies the user who wrote this. Corresponds to the user IDs stored in the MySQL database as ``auth_user.id``.
--------------------
author_username author_username
------------------ --------------------
The username of the person who wrote the discussion post or comment. The username of the person who wrote the discussion post or comment.
--------------------
body body
------ --------------------
Text of the comment in Markdown. UTF-8 encoded. Text of the comment in Markdown. UTF-8 encoded.
--------------------
course_id course_id
----------- --------------------
The full course_id of the course that this comment was made in, including org and run. This value can be seen in the URL when browsing the courseware section. Example: ``BerkeleyX/Stat2.1x/2013_Spring``. The full course_id of the course that this comment was made in, including org and run. This value can be seen in the URL when browsing the courseware section. Example: ``BerkeleyX/Stat2.1x/2013_Spring``.
.. 12 Feb 14, Sarina: not yet relevant but with splitmongo changes course_id conventions will change. may be worth discussing with Don et al as to when we expect these changes to land and how to document. .. 12 Feb 14, Sarina: not yet relevant but with splitmongo changes course_id conventions will change. may be worth discussing with Don et al as to when we expect these changes to land and how to document.
--------------------
created_at created_at
------------ --------------------
Timestamp in UTC. Example: ``ISODate("2013-02-21T03:03:04.587Z")``. Timestamp in UTC. Example: ``ISODate("2013-02-21T03:03:04.587Z")``.
.. FOR-482 open to research inconsistency between the data actually in the data package and this example and description. .. FOR-482 open to research inconsistency between the data actually in the data package and this example and description.
--------------------
updated_at updated_at
------------ --------------------
Timestamp in UTC. Example: ``ISODate("2013-02-21T03:03:04.587Z")``. Timestamp in UTC. Example: ``ISODate("2013-02-21T03:03:04.587Z")``.
.. FOR-482 open to research inconsistency between the data actually in the data package and this example and description. .. FOR-482 open to research inconsistency between the data actually in the data package and this example and description.
--------------------
votes votes
------- --------------------
Both ``CommentThread`` and ``Comment`` objects support voting. In the user interface, students can vote for posts (``CommentThread``s) and for responses, but not for the third-level comments made on responses. All ``Comment`` objects still have this attribute, even though there is no way to actually vote on the comment-level items in the UI. This attribute is a dictionary that has the following items inside: Both ``CommentThread`` and ``Comment`` objects support voting. In the user interface, students can vote for posts (``CommentThread``s) and for responses, but not for the third-level comments made on responses. All ``Comment`` objects still have this attribute, even though there is no way to actually vote on the comment-level items in the UI. This attribute is a dictionary that has the following items inside:
* up = list of User IDs that up-voted this comment or thread. * up = list of User IDs that up-voted this comment or thread.
...@@ -131,12 +251,14 @@ CommentThread Fields ...@@ -131,12 +251,14 @@ CommentThread Fields
The following fields are specific to ``CommentThread`` objects. Each thread in the discussion forums is represented by one ``CommentThread``. The following fields are specific to ``CommentThread`` objects. Each thread in the discussion forums is represented by one ``CommentThread``.
--------------------
closed closed
-------- --------------------
If true, this thread was closed by a discussion forum moderator or admin. If true, this thread was closed by a discussion forum moderator or admin.
--------------------
comment_count comment_count
--------------- --------------------
The number of comment replies in this thread. This includes all responses and replies, but does not include the original post that started the thread. So for this exchange:: The number of comment replies in this thread. This includes all responses and replies, but does not include the original post that started the thread. So for this exchange::
CommentThread: "What's a good breakfast?" CommentThread: "What's a good breakfast?"
...@@ -147,24 +269,28 @@ comment_count ...@@ -147,24 +269,28 @@ comment_count
The ``comment_count`` for this ``CommentThread`` is **4**. The ``comment_count`` for this ``CommentThread`` is **4**.
--------------------
commentable_id commentable_id
---------------- --------------------
A course team can attach a discussion to any piece of content in the course, or to top level categories like "General" and "Troubleshooting". When the discussion is a top level category it is specified in the course's policy file, and the ``commentable_id`` is formatted like this: "i4x-edX-edX101-course-How_to_Create_an_edX_Course". When the discussion is a specific component in the course, the ``commentable_id`` identifies that component: "d9f970a42067413cbb633f81cfb12604". A course team can attach a discussion to any piece of content in the course, or to top level categories like "General" and "Troubleshooting". When the discussion is a top level category it is specified in the course's policy file, and the ``commentable_id`` is formatted like this: "i4x-edX-edX101-course-How_to_Create_an_edX_Course". When the discussion is a specific component in the course, the ``commentable_id`` identifies that component: "d9f970a42067413cbb633f81cfb12604".
--------------------
last_activity_at last_activity_at
------------------ --------------------
Timestamp in UTC indicating the last time there was activity in the thread (new posts, edits, etc). Closing the thread does not affect the value in this field. Timestamp in UTC indicating the last time there was activity in the thread (new posts, edits, etc). Closing the thread does not affect the value in this field.
.. FOR-482 open to research inconsistency between the data actually in the data package and this example and description. .. FOR-482 open to research inconsistency between the data actually in the data package and this example and description.
--------------------
tags_array tags_array
------------ --------------------
No longer used. No longer used.
**History**: Intended to be a list of user definable tags. **History**: Intended to be a list of user definable tags.
--------------------
title title
------- --------------------
Title of the thread. UTF-8 string. Title of the thread. UTF-8 string.
******************** ********************
...@@ -175,36 +301,44 @@ The following fields are specific to ``Comment`` objects. A ``Comment`` is eithe ...@@ -175,36 +301,44 @@ The following fields are specific to ``Comment`` objects. A ``Comment`` is eithe
**History**: It used to be the case that ``Comment`` replies could nest much more deeply, but this was later capped at just these three levels (post, response, comment) much in the way that StackOverflow does. **History**: It used to be the case that ``Comment`` replies could nest much more deeply, but this was later capped at just these three levels (post, response, comment) much in the way that StackOverflow does.
--------------------
visible visible
---------- --------------------
Not used. Not used.
--------------------
abuse_flaggers abuse_flaggers
-------------------- --------------------
Records the user id of each user who selects the **Report Misuse** flag for a ``Comment`` in the user interface. Stores an array of user ids if more than one user flags the ``Comment``. This is empty if no users flag the ``Comment``. Records the user id of each user who selects the **Report Misuse** flag for a ``Comment`` in the user interface. Stores an array of user ids if more than one user flags the ``Comment``. This is empty if no users flag the ``Comment``.
----------------------------------------
historical_abuse_flaggers historical_abuse_flaggers
------------------------------ ----------------------------------------
If a discussion moderator removes the **Report Misuse** flag from a ``Comment``, all user IDs are removed from the ``abuse_flaggers`` field and then written to this field. If a discussion moderator removes the **Report Misuse** flag from a ``Comment``, all user IDs are removed from the ``abuse_flaggers`` field and then written to this field.
--------------------
endorsed endorsed
---------- --------------------
Boolean value, true if a forum moderator or instructor has marked that this ``Comment`` is a correct answer for whatever question the thread was asking. Exists for Comments that are replies to other Comments, but in that case ``endorsed`` is always false because there's no way to endorse such comments through the UI. Boolean value, true if a forum moderator or instructor has marked that this ``Comment`` is a correct answer for whatever question the thread was asking. Exists for Comments that are replies to other Comments, but in that case ``endorsed`` is always false because there's no way to endorse such comments through the UI.
--------------------
comment_thread_id comment_thread_id
------------------- --------------------
Identifies the ``CommentThread`` that the ``Comment`` is a part of. Identifies the ``CommentThread`` that the ``Comment`` is a part of.
--------------------
parent_id parent_id
-------------- --------------------
Applies only to comments made to a response. In the example given for ``comment_count`` above, "A Loco Moco? Only if you want a heart attack!" is a comment that was made to the response, "Try a Loco Moco, it's amazing!" Applies only to comments made to a response. In the example given for ``comment_count`` above, "A Loco Moco? Only if you want a heart attack!" is a comment that was made to the response, "Try a Loco Moco, it's amazing!"
The ``parent_id`` is the ``_id`` of the response-level ``Comment`` that this ``Comment`` is a reply to. Note that this field is only present in a ``Comment`` that is a reply to another ``Comment``; it does not appear in a ``Comment`` that is a reply to a ``CommentThread``. The ``parent_id`` is the ``_id`` of the response-level ``Comment`` that this ``Comment`` is a reply to. Note that this field is only present in a ``Comment`` that is a reply to another ``Comment``; it does not appear in a ``Comment`` that is a reply to a ``CommentThread``.
--------------------
parent_ids parent_ids
------------ --------------------
The ``parent_ids`` field appears in all ``Comment`` objects, and contains the ``_id`` of all ancestor comments. Since the UI now prevents comments from being nested more than one layer deep, it will only ever have at most one element in it. If a ``Comment`` has no parent, it is an empty list. The ``parent_ids`` field appears in all ``Comment`` objects, and contains the ``_id`` of all ancestor comments. Since the UI now prevents comments from being nested more than one layer deep, it will only ever have at most one element in it. If a ``Comment`` has no parent, it is an empty list.
--------------------
sk sk
-------------------- --------------------
A randomly generated number that drives a sorted index to improve online performance. A randomly generated number that drives a sorted index to improve online performance.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment