Přejít na hlavní obsah

Open Lesson Format

The Open Lesson Format is a standardized JSON schema that allows third-party content providers to publish curriculum for Lessons.church. Any organization that hosts a feed in this format can be added as an external provider, making their content browsable and playable alongside the built-in library.

How It Works​

A provider hosts two types of endpoints:

  1. Provider Tree -- A single URL that returns the full catalog of programs, studies, lessons, and venues. Each venue includes a feed URL pointing to the detailed lesson content.
  2. Venue Feed -- One URL per venue, returning the full lesson content (sections, actions, and media files).

When a church adds your provider URL in Lessons.church, the platform fetches your tree to discover available content, then fetches individual venue feeds on demand.

Provider Tree​

Your provider URL must return a JSON object with this structure:

{
  "programs": [
    {
      "id": "program-1",
      "name": "Gospel of Mark",
      "slug": "gospel-of-mark",
      "image": "https://example.com/images/mark.jpg",
      "about": "A 12-week study through the Gospel of Mark.",
      "studies": [
        {
          "id": "study-1",
          "name": "The Beginning",
          "slug": "the-beginning",
          "image": "https://example.com/images/study1.jpg",
          "lessons": [
            {
              "id": "lesson-1",
              "name": "The Baptism of Jesus",
              "slug": "baptism-of-jesus",
              "title": "The Baptism of Jesus",
              "image": "https://example.com/images/lesson1.jpg",
              "description": "An introduction to Jesus' ministry.",
              "bottomLine": "God keeps His promises.",
              "verse": "Genesis 9:13 — I have set my rainbow in the clouds…",
              "parentQuestion": "What is one promise God has kept in our family?",
              "parentNote": "Pray together thanking God for keeping His promises.",
              "venues": [
                {
                  "id": "venue-1",
                  "name": "Kids",
                  "apiUrl": "https://example.com/feed/venues/venue-1"
                },
                {
                  "id": "venue-2",
                  "name": "Adults",
                  "apiUrl": "https://example.com/feed/venues/venue-2"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Tree Fields​

FieldTypeDescription
programs[].idstringUnique program identifier
programs[].namestringDisplay name
programs[].slugstringURL-friendly name
programs[].imagestringProgram image URL (optional)
programs[].aboutstringDescription (optional)
studies[].idstringUnique study identifier
studies[].namestringDisplay name
studies[].slugstringURL-friendly name
studies[].imagestringStudy image URL (optional)
lessons[].idstringUnique lesson identifier
lessons[].namestringDisplay name
lessons[].slugstringURL-friendly name
lessons[].titlestringFull title
lessons[].imagestringLesson image URL (optional)
lessons[].descriptionstringLesson summary (optional). Catalog copy for teachers browsing the library — not parent take-home.
lessons[].bottomLinestringOne-sentence parent take-home (optional)
lessons[].versestringMemory verse reference and short text (optional)
lessons[].parentQuestionstringOne question for parents to ask at home (optional)
lessons[].parentNotestringOptional extra note for parents (markdown)
venues[].idstringUnique venue identifier
venues[].namestringVenue name (e.g. "Kids", "Adults", "Youth")
venues[].apiUrlstringURL returning the venue feed (see below)

The four parent take-home fields (bottomLine, verse, parentQuestion, parentNote) are optional on both the tree and the venue feed. If omitted they are treated as empty. Do not copy description into them.

Venues represent different versions of the same lesson tailored for different audiences (age groups, settings, etc.).

Venue Feed​

Each venue's apiUrl must return a JSON object matching this schema:

{
  "id": "venue-1",
  "name": "Kids",
  "lessonId": "lesson-1",
  "lessonName": "The Baptism of Jesus",
  "lessonImage": "https://example.com/images/lesson1.jpg",
  "lessonDescription": "An introduction to Jesus' ministry.",
  "bottomLine": "God keeps His promises.",
  "verse": "Genesis 9:13 — I have set my rainbow in the clouds…",
  "parentQuestion": "What is one promise God has kept in our family?",
  "parentNote": "Pray together thanking God for keeping His promises.",
  "studyName": "The Beginning",
  "studySlug": "the-beginning",
  "programName": "Gospel of Mark",
  "programSlug": "gospel-of-mark",
  "programAbout": "A 12-week study through the Gospel of Mark.",
  "downloads": [],
  "sections": [
    {
      "id": "section-1",
      "name": "Opening Discussion",
      "sort": 1,
      "materials": "Whiteboard and markers",
      "actions": [
        {
          "id": "action-1",
          "actionType": "text",
          "content": "**Key Verse:** Mark 1:9-11",
          "sort": 1
        },
        {
          "id": "action-2",
          "actionType": "question",
          "content": "What do you know about baptism?",
          "sort": 2,
          "role": "Leader"
        },
        {
          "id": "action-3",
          "actionType": "play",
          "content": "Intro Video",
          "sort": 3,
          "files": [
            {
              "id": "file-1",
              "name": "intro-video.mp4",
              "url": "https://example.com/media/intro.mp4",
              "streamUrl": "https://vimeo.com/123456789",
              "fileType": "video/mp4",
              "seconds": 180,
              "bytes": 52428800,
              "thumbnail": "https://example.com/media/intro-thumb.jpg",
              "loop": false
            }
          ]
        }
      ]
    }
  ]
}

Venue Feed Fields​

Root Object​

FieldTypeDescription
idstringVenue identifier
namestringVenue name
lessonIdstringLesson identifier
lessonNamestringLesson display name
lessonImagestringLesson image URL
lessonDescriptionstringLesson summary (catalog copy)
bottomLinestringOne-sentence parent take-home (optional)
versestringMemory verse reference and short text (optional)
parentQuestionstringOne question for parents to ask at home (optional)
parentNotestringOptional extra note for parents, markdown (optional)
studyNamestringParent study name
studySlugstringParent study slug
programNamestringParent program name
programSlugstringParent program slug
programAboutstringProgram description
downloadsarrayDownloadable file bundles
sectionsarrayOrdered lesson sections

Section​

FieldTypeDescription
idstringSection identifier
namestringSection title
sortnumberDisplay order
materialsstringMaterials or preparation notes (optional)
actionsarrayOrdered actions within this section

Action​

FieldTypeDescription
idstringAction identifier
actionTypestringOne of: play, text, question, quote, subhead
contentstringText content or media label
sortnumberDisplay order
rolestringRole name, e.g. "Leader", "Kids" (optional)
roleIdstringRole identifier (optional)
filesarrayMedia files for play actions (optional)

File​

FieldTypeDescription
idstringFile identifier
namestringFile name
urlstringDirect download URL
streamUrlstringStreaming URL, e.g. Vimeo link (optional)
fileTypestringMIME type (e.g. video/mp4, image/jpeg)
secondsnumberDuration in seconds for audio/video (optional)
bytesnumberFile size in bytes (optional)
thumbnailstringThumbnail image URL (optional)
loopbooleanWhether media should loop (optional, default false)

Download​

FieldTypeDescription
namestringDownload bundle name (e.g. "Printable Materials")
filesarrayFiles in this download bundle (same fields as File above)

Action Types​

TypePurpose
playMedia playback -- video, audio, or slideshow. Must include files.
textStatic text content. Supports markdown-style bold (**text**).
questionDiscussion or reflection question for the audience.
quoteA highlighted quote or Scripture passage.
subheadA heading or divider within a section.
tip

To see a working example of the feed in action, you can view the built-in Lessons.church content tree at https://api.lessons.church/lessons/public/tree and fetch any venue feed URL from it.