Course related proposals

[danbri]

Context: Passing this along from Google colleagues who have been working with web data that uses current Course schema. The suggestions are based on a desire to be able to do more with this kind of data.

Proposal

1. Course-related properties:

Property name in Schema.org	Description	Appears on Type	Expected Type
syllabusSections	Syllabus that lays out what each section of the course will cover.	Course	Syllabus [new]
courseLength	Represents the length and pace of the course.	CourseInstance	Schedule
skills	Skills the course can help users obtain.	Course,Occupation,JobPosting	Text,DefinedTerm
totalHistoricalEnrollment	The total number of students that have enrolled in the history of the course.	Course	Integer
financialAidEligible	Any scholarships, special payment plans, or other financial aid opportunities for users looking to take the course.	Course,EducationalOccupationalProgram	Text,DefinedTerm
availableLanguage	Subtitles, closed captions, or other languages the course is offered in.	Course	Text

2. A Syllabus type

Definition: “ A syllabus that describes the material covered in a course”

3. Syllabus properties

Typical properties (none new to Schema.org):

Property name in Schema.org	Description	Appears on Type
schema.org/name	Title of a specific syllabus section.	schema.org/Syllabus
schema.org/description	Description of a specific syllabus section.	schema.org/Syllabus
schema.org/timeRequired	Expected duration for a specific syllabus section.	schema.org/Syllabus

Example

{
"@context": "https://schema.org/",
"@id": "https://www.example.com/advancedCpp",
"@type": "Course",

"name": "Learn Advanced C++ Topics", 
"description": "Improve your C++ skills by learning advanced topics such as pointers,
                memory allocation, and function parameters.",

"publisher": {
    "@type": "Organization", 
    "name": "CourseWebsite",
    "url": "www.example.com"
},

"provider": {
    "@type": "Organization", 
    "name": "CourseProvider",
    "url": "www.exampleProvider.com"
},

"aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "9.8",
    "bestRating": "10",
    "ratingCount": 1234
},

"totalHistoricalEnrollment": 12345,

"image": [
    "https://example.com/photos/1x1/photo.jpg",
     "https://example.com/photos/4x3/photo.jpg",
     "https://example.com/photos/16x9/photo.jpg"
],

"educationalCredentialAwarded": {
    "name": "CourseProvider Certificate",
    "url": "www.exampleCertificate.com",
    "credentialCategory": "Certificate",
    "offers": {
       "@type": "Offer",
       "price": "5",
       "priceCurrency": "USD"
    } 
},

"financialAidEligible": "Scholarship Available",

"coursePrerequisites": [
    "Basic understanding of C++ up to arrays and functions.",
    {
       "@type": "Course",
       "@id": "https://www.coursewebsite.abc/beginnerCpp",
       "name": "Learn Beginner C++ Topics",
       "description": "Learn the basics of C++."
    }
],

"educationalLevel": "Advanced",
"inLanguage": "en",
"availableLanguage": ["fr", "es"],


"teaches": ["Practice and apply systems thinking to plan for change",  
            "Understand how memory allocation works."],
"skills": ["C++ Coding", "Backend Engineering"],

"offers": {
   "@type": "Offer",
   "description": "Paid",
   "price": "10",
   "priceCurrency": "USD"
},

"syllabusSections": [
  {
    "name": "Memory Allocation",
    "description": "Learn how memory is allocated when you create C++ variables.",     
    "timeRequired": "PT6H"
  },
  {
    "name": "C++ Pointers",
    "description": "Learn what a C++ pointer is and when they are used.",
    "timeRequired": "PT11H"
  },
]
"review": [
  {
    "@type": "Review",
    "author": {
        "@type": "Person",
        "name": "Bob Smith"
      },
    "datePublished": "2020-08-31",
    "reviewBody": "My C++ skills improved, but the pace was too fast.",
    "reviewRating": {
      "@type": "Rating",
      "bestRating": "5",
      "ratingValue": "3",
      "worstRating": "1"
    }
  }
]  

"hasCourseInstance": [{
   // Hybrid, instructor-led class meeting daily in Fall 2023
   "@type": "CourseInstance",
   "courseMode": "hybrid",
   "location": "Hogwarts Tech",
   "courseLength": {
      "@type": "Schedule",
      "duration": "PT1H",
      "startDate": "2023-07-01",
      "endDate": "2023-12-15",
      "repeatFrequency": "P1D"
   },
    "instructor": {
      "@type" "Person",
      "name": "John Doe",
      "description": "Professor at X-University",
      "image": http://examplePerson.jpg"
   }
},
{
   // Online, self-paced 10 hours / week for 15 weeks
   "@type": "CourseInstance",
   "courseMode": "online",
   "courseLength": {
      "@type": "Schedule",
      "duration": "PT10H",
      "repeatFrequency": "P1W",
      "repeatCount": 15
   },
}]

}

[danbri]

Discussion points:

• Why is syllabusSections not nested in hasCourseInstance?

  • Pages with the Course Schema markup typically only have one syllabus. It would be redundant to add the same syllabus to different courseInstances.

• What is the difference between teaches and skills?

  • teaches is open text and describes the very specific knowledge the user will learn.
  • skills is more generalized and will have a publicly published list of ~1000 skills that implementers of the Course markup can pick from. Jobs and Occupations can also reference this list.

• Course schema currently has timeRequired which only accepts a duration (i.e. "PT4H30M" represents 4 hours and 30 minutes). However, course providers represent course length in different formats (i.e. pace, material duration if self-paced, dates + frequency).

  • courseLength is a more comprehensive way of representing these different time formats.

[danbri]

Discussing with @philbarker briefly today, he suggests that we ought to be able to cover “skills” using the existing “teaches” property.

[stuartasutton]

Phil is correct. Teaches is inclusive of knowledge, skills, dispositions etc. Teaches can also point to concepts in a DefinedTermSet of identified as skills.

[philbarker]

Ideally we would want teaches to point to a DefinedTerm. For example in Credential Engine the entry for C182 - Introduction to IT from WGU shows under "connections" that it teaches 9 competencies drawn from this competency framework; these are also described by WGU using Rich Skill Descriptions like this one.

I don't see how you can say that skills and teaches are different because they point to different sources of the same information, i.e. reference different skills frameworks.

[ashyv]

Thanks all for your feedback. Addressing some of the points we've heard here:

1. Skills are a defined set of terms, whereas teaches explains what users will learn.
   Coursera, as well as other providers, represent these in 2 distinct ways [example course with both skills and teaches]

If absolutely necessary, we can try to make teaches repeatable, but we would be overloading the term and collecting two different pieces of data.

2. We will rename courseLength to courseSchedule given the type it links to is a Schedule object.

3. What's the difference between timeRequired in course vs in Syllabus. timeRequired in course is the length of the overall course (though we are pushing our providers to use courseSchedule instead to provide more detail). timeRequired in Syllabus is how long it should take to complete one Syllabus section.

Please let us know your thoughts, especially on point 1. Thanks!

[danbri]

Perhaps the notion of skill is something that we can consider part of the property value? It may be that certain websites currently use those words in this configuration but it far from standard usage. There are numerous articles that discuss ways to "teach", learn, or acquire a skill. Competency and learning outcome (from our current definition) are a bit jargon sounding to a non-educationalist but they're essentially the same idea. Whether the property values are formalised in code lists (by sites, tools, schools or governments or international treaty is orthogonal. As is repeatability (which is pretty much unavoidable here).

…

On Mon, 20 Mar 2023, 19:33 ashyv, ***@***.***> wrote: Thanks all for your feedback. Addressing some of the points we've heard here: 1. Skills are a defined set of terms, whereas teaches explains what users will learn. Coursera, as well as other providers, represent these in 2 distinct ways [example course <https://www.coursera.org/specializations/machine-learning-introduction> with both skills and teaches] If absolutely necessary, we can try to make teaches repeatable, but we would be overloading the term and collecting two different pieces of data. 1. We will rename courseLength to courseSchedule given the type it links to is a Schedule object. 2. What's the difference between timeRequired in course vs in Syllabus. timeRequired in course is the length of the overall course (though we are pushing our providers to use courseSchedule instead to provide more detail). timeRequired in Syllabus is how long it should take to complete one Syllabus section. Please let us know your thoughts, especially on point 1. Thanks! — Reply to this email directly, view it on GitHub <#3281 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABJSGJ4PNCXZS33RTTC74DW5CWKFANCNFSM6AAAAAAV2SZGP4> . You are receiving this because you were assigned.Message ID: ***@***.***>

[philbarker]

1. I am very concerned that the use of teaches here is at odds with use in LRMI, and other standards that have adopted / are adopting , e.g. CTDL, IEEE P2881, and K12-OCX (in the older property educationalAlignement). This isn't new territory, please don't muddy it. But in case I am being too precious, I'll send a message around LRMI to check what they think.

Looking at the Coursera example, the "skills" look like subjects or topics, I would use about for these -- topics can also be defined sets of terms. What is listed under "What you will learn" look like competency definitions, i.e. the definition part of competencies as defined terms, I would use teaches to point to these. This is closer to what employers are looking for to fill jobs/roles. Lots of work linking competence based education to skills based hiring relies on the competencies that a course teaches or a test assesses or a credential requires being the same as the skills required for the job.

@danbri yes, this is a bit education jargony, but not in any way that would be unfamiliar to Coursera or anyone else hoping to deal with education. And your instinct is right, competency and learning outcome are essentially the same thing; and "skills" in both education- and HR-speak are a subset of that thing.

2. OK, makes sense
3. I think that is the point I was making. Why not use the existing property?

BTW, you might want to look at how CTDL handles course schedules.

[HughP]

1. Skills are a defined set of terms, whereas teaches explains what users will learn.
   Coursera, as well as other providers, represent these in 2 distinct ways [example course with both skills and teaches]

If absolutely necessary, we can try to make teaches repeatable, but we would be overloading the term and collecting two different pieces of data.

It sees to me that what Coursera is doing here is providing a summary. That summary is like an abstract. Maybe abstract is a useful alternative here? Teaches like @philbarker and @stuartasutton suggest is supposed to point to defined terms in controlled taxonomies.

[HughP]

1. I am very concerned that the use of teaches here is at odds with use in LRMI, and other standards that have adopted / are adopting , e.g. CTDL, IEEE P2881, and K12-OCX (in the older property educationalAlignement). This isn't new territory, please don't muddy it. But in case I am being too precious, I'll send a message around LRMI to check what they think.

I echo Phill's comments. The canonical authority for the semantic interpretation of LRMI elements within schema.org needs to rest with LRMI. If the semantics of the metadata terms (properties) are "co-opted" by other parties then this serves as a point of risk assessment for other metadata communities when they consider aligning with schema.org. That is, why align? semantics of the terms might be changed.

[ashyv]

Thanks for the suggestions. Does the following example look okay?

"about": ["Build & train a neural network with TensorFlow to perform multi-class classification", "Apply best practices for ML development"]

"teaches": ["Tensorflow", "Supervised Learning"]

We'll use about for the free form description of what students will learn. And we'll use teaches for defined terms (we intend to provide ~1000 defined skills that our providers can pick from).

Phil, regarding timeRequired, I think we are on the same page but perhaps I'm not saying it correctly. We are using the existing timeRequired property. But syllabusSections is a repeated field (i.e. a class might have 5 modules / chapters), so we need to include timeRequired in each Syllabus section.

[philbarker]

Does the following example look okay?

"about": ["Build & train a neural network with TensorFlow to perform multi-class classification", "Apply best practices for ML development"]

"teaches": ["Tensorflow", "Supervised Learning"]

I was suggesting the other way round:

"teaches": [
   "Build & train a neural network with TensorFlow to perform multi-class classification", 
   "Apply best practices for ML development"
] 
"about": ["Tensorflow", "Supervised Learning"]

And yes, I know Coursera puts "Tensorflow", "Supervised Learning" under skills, but as learning objectives / competency statements they are not very helpful. I suspect they (or the organization that supplied the course) have a skills taxonomy/framework that looks something like:

Specialization: Computer Science / Machine Learning
Topic: 1. Supervised Learning
Objectives:

• 1.1. "Apply best practices for ML development"
• 1.2. etc.

Topic: 2. Tensorflow
Objectives:

• 2.1 "Build & train a neural network with TensorFlow to perform multi-class classification",
• 2.2. etc.

etc.

Phil, regarding timeRequired, I think we are on the same page but perhaps I'm not saying it correctly. We are using the existing timeRequired property. But syllabusSections is a repeated field (i.e. a class might have 5 modules / chapters), so we need to include timeRequired in each Syllabus section.

Yes, I think we are on the same page, that sounds good (renaming courseLength to courseSchedule helped a lot to clarify this).

[danbri]

Ok, we are getting somewhere positive I think! Thank you all for putting the time in to fond common ground and understand where others are coming from - that is what shared schemas are all about! I hope we also have rough consensus that for both these aspects of the description we will expect to see both strings/phrases/hashtags as well as URI/URL identifiers (ideally to shared definitions with both machine and human representations). The Schema can be essentially the same for both, i.e. providing a framework for using controlled IDs without assuming everyone is set up to do so yet. To support this better we could tweak /about to more explicitly support DefinedTerm and clarify that when something is “about” such a term, it is the content of the term that it the real value, not the term as a bibliographic artifact.

…

On Wed, 22 Mar 2023 at 09:55, Phil Barker ***@***.***> wrote: Does the following example look okay? "about": ["Build & train a neural network with TensorFlow to perform multi-class classification", "Apply best practices for ML development"] "teaches": ["Tensorflow", "Supervised Learning"] I was suggesting the other way round: "teaches": [ "Build & train a neural network with TensorFlow to perform multi-class classification", "Apply best practices for ML development" ] "about": ["Tensorflow", "Supervised Learning"] And yes, I know Coursera puts "Tensorflow", "Supervised Learning" under skills, but as learning objectives / competency statements they are not very helpful. I suspect they (or the organization that supplied the course) have a skills taxonomy/framework that looks something like: *Specialization:* Computer Science / Machine Learning *Topic:* 1. Supervised Learning *Objectives:* - 1.1. "Apply best practices for ML development" - 1.2. etc. *Topic:* 2. Tensorflow *Objectives:* - 2.1 "Build & train a neural network with TensorFlow to perform multi-class classification", - 2.2. etc. etc. Phil, regarding timeRequired, I think we are on the same page but perhaps I'm not saying it correctly. We are using the existing timeRequired property. But syllabusSections is a repeated field (i.e. a class might have 5 modules / chapters), so we need to include timeRequired in each Syllabus section. Yes, I think we are on the same page, that sounds good (renaming courseLength to courseSchedule helped a lot to clarify this). — Reply to this email directly, view it on GitHub <#3281 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABJSGN3TVS3ORPNJ55TIH3W5LEBZANCNFSM6AAAAAAV2SZGP4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[ashyv]

Phil, sounds good to go with what you proposed, but +1 to Dan's comment - we need to modify the about field to support DefinedTerm and Text (right now it just accepts a Thing type).

Will this change happen alongside our Course Schema change, or will it be it's own standalone change?

[ashyv]

Also, now that we seem to be aligned on the Course Schema changes, what are the next steps? Is there anything more I can provide to make things easier on your end?

[danbri]

I will queue this for inclusion in next release candidate. Examples in json-ld would be great!

[ashyv]

<script type="application/ld+json">
    {
       "@context": "https://schema.org/",
       "@id": "https://www.example.com/advancedCpp",
       "@type": "Course",

       "name": "Learn Advanced C++ Topics", 
       "description": "Improve your C++ skills by learning advanced topics such as 
                pointers, memory allocation, and function parameters.",

       "publisher": {
           "@type": "Organization", 
           "name": "CourseWebsite",
           "url": "www.exampleCourseWebsite.com"
       },
       "provider": {
           "@type": "Organization",
           "name": "Hogwarts Tech",
           "url": "www.exampleHogwartsTech.com"
       },

       "image": [
           "https://example.com/photos/1x1/photo.jpg",
           "https://example.com/photos/4x3/photo.jpg",
           "https://example.com/photos/16x9/photo.jpg"
       ],

       "aggregateRating": {
          "@type": "AggregateRating",
          "ratingValue": "9.8",
          "bestRating": "10",
          "ratingCount": "1234",
          "reviewCount": "450"
       },

       "offers": {
          "@type": "Offer",
          "category": "Paid",
          "price": "10.25",
          "priceCurrency": "USD"
       },

       "educationalLevel": "Advanced",
       "totalHistoricalEnrollment": "12345",

       "about": ["C++ Coding", "Backend Engineering"],
       "teaches": ["Practice and apply systems thinking to plan for change",  
            "Understand how memory allocation works."],

       "inLanguage": "en",
       "availableLanguage": ["fr", "es"],

       "review": [
       {
           "@type": "Review",
           "author": {
               "@type": "Person",
               "name": "Bob Smith"
           },
           "datePublished": "2020-08-31",
           "reviewBody": "My C++ skills improved, but the pace was too fast.",
           "reviewRating": {
              "@type": "Rating",
              "bestRating": "10",
              "ratingValue": "6"
           }
         }
       ],

       "syllabusSections": [
        {
           "@type": "Syllabus",
           "name": "Memory Allocation",
           "description": "Learn how memory is allocated when creating C++ variables.",     
           "timeRequired": "PT6H"
         },
         {
           "@type": "Syllabus",
           "name": "C++ Pointers",
           "description": "Learn what a C++ pointer is and when they are used.",
           "timeRequired": "PT11H"
         }
       ],

       "coursePrerequisites": [
           "Basic understanding of C++ up to arrays and functions.",
           "https://www.example.com/beginnerCpp"
       ],

       "educationalCredentialAwarded": {
           "@type": "EducationalOccupationalCredential",
           "name": "CourseProvider Certificate",
           "url": "www.exampleCertificate.com",
           "credentialCategory": "Certificate",
           "offers": {
              "@type": "Offer",
              "price": "5",
              "priceCurrency": "USD"
           } 
       },

       "financialAidEligible": "Scholarship Available",

       "video": {
               "@type": "VideoObject",
               "name": "Video name",
               "description": "A video previewing this course.",
               "uploadDate": "2022-03-28",
               "contentUrl": "www.videoUrl.mp4",
               "thumbnailUrl": "www.thumbnailUrl.jpg"
        },

       "hasCourseInstance": [
       {
          // Blended, instructor-led class meeting daily in Fall 2023
          "@type": "CourseInstance",
          "courseMode": "Blended",
          "location": "Hogwarts Tech",
          "courseWorkload": "PT28H",
          "courseSchedule": {
             "@type": "Schedule",
             "duration": "PT1H",
             "startDate": "2023-07-01",
             "endDate": "2023-12-15",
             "repeatFrequency": "Daily"
          },
           "instructor": {
             "@type": "Person",
             "name": "John Doe",
             "description": "Professor at X-University",
             "image": "http://examplePerson.jpg"
          }
       },
       {
          // Online, self-paced 10 hours / week for 15 weeks
          "@type": "CourseInstance",
          "courseMode": "Online",
          "courseWorkload": "PT150H",
          "courseSchedule": {
             "@type": "Schedule",
             "duration": "PT10H",
             "repeatFrequency": "Weekly",
             "repeatCount": 15
          }
       }]
     }
</script>

[danbri]

Ok, this is live. There was a small mistake in yesterday's release (16.0) corrected today; I had courseLength instead of the agreed courseSchedule.

[github-actions]

This issue is being nudged due to inactivity.