Changelog
Guides
Start typing to search…

2.7 schema:Event and schema:Schedule

A comprehensive description of how and when to use schema:Event and schema:Schedule.

Annotating events often leads to misunderstandings due to the broad and flexible nature of the schema:Event vocabulary. This openness leaves significant room for interpretation. A common source of confusion is the use of schema:Schedule as the range of schema:eventSchedule.

1. Definitions

As defined by schema.org/Event

An event happening at a certain time and location, such as a concert, lecture, or festival. Ticketing information may be added via the offers property. Repeated events may be structured as separate Event objects.

As defined by schema.org/Schedule

A schedule defines a repeating time period used to describe a regularly occurring Event. At a minimum a schedule will specify repeatFrequency which describes the interval between occurrences of the event. Additional information can be provided to specify the schedule more precisely. This includes identifying the day(s) of the week or month when the recurring event will take place, in addition to its start and end time. Schedules may also have start and end dates to indicate when they are active, e.g. to define a limited calendar of events.

1.1 Event types

In real life, that means the schema:Event class is used for different kinds of events:

  1. single events, like "340th birthday party of Johann Sebastian Bach". This event occurs exactly once.
  2. event series, like "Poolbar Festival 2025, 2.7.-10.8.2025". This is a series of various events, including concerts, lectures, and plays.
  3. recurring events, like "Wochenmarkt der Biobauern, 1.3.-28.9. 20205". This is one event that recurs, in a
    1. defined repetition frequency, mostly weekday-based
    2. at a given location
    3. at a given, potentially changing time

1.2 Modelling

All three above-defined event types use a different modelling structure. While it is syntactically correct to annotate all of them as single events, this might lead to confusion for data consumers. Therefore, a joint understanding of the semantics is crucial.

1.2.1 Single Events

A single event is annotated with a scheme:Event that has, at a minimum, a name and a start date. If not explicitly clear, it may also be helpful to include an end date, as well as start and end times.

Example

{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Klassikabend im Schlosspark",
  "startDate": "2025-08-10T19:30",
  "location": {
    "@type": "Place",
    "name": "Schloss Esterházy",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "Esterházyplatz 1",
      "addressLocality": "Eisenstadt",
      "postalCode": "7000",
      "addressCountry": "AT"
    }
  }
}

1.2.2 Event Series

An event series is annotated with a schema:EventSeries (a sub-class of schema:Event), and the events of the series as schema:Event.

The event series needs a start and end date (time is optional), the (sub-)events need a starting time (schema:startDate with time specifications), here, however, the end time is optional.

Example

{
  "@context": "https://schema.org",
  "@type": "EventSeries",
  "name": "Kulturreihe Sommerklänge 2025",
  "startDate": "2025-08-01",
  "endDate": "2025-08-15",
  "event": [
    {
      "@type": "Event",
      "name": "Sommerklänge: Konzert in Wien",
      "startDate": "2025-08-01T19:00",
      "location": {
        "@type": "Place",
        "name": "Wiener Konzerthaus",
        "address": {
          "@type": "PostalAddress",
          "streetAddress": "Lothringerstraße 20",
          "addressLocality": "Wien",
          "postalCode": "1030",
          "addressCountry": "AT"
        }
      }
    },
    {
      "@type": "Event",
      "name": "Sommerklänge: Konzert in Salzburg",
      "startDate": "2025-08-08T19:00",
      "location": {
        "@type": "Place",
        "name": "Großes Festspielhaus",
        "address": {
          "@type": "PostalAddress",
          "streetAddress": "Hofstallgasse 1",
          "addressLocality": "Salzburg",
          "postalCode": "5020",
          "addressCountry": "AT"
        }
      }
    },
    {
      "@type": "Event",
      "name": "Sommerklänge: Konzert in Graz",
      "startDate": "2025-08-15T19:00",
      "location": {
        "@type": "Place",
        "name": "Helmut List Halle",
        "address": {
          "@type": "PostalAddress",
          "streetAddress": "Waagner-Biro-Straße 98a",
          "addressLocality": "Graz",
          "postalCode": "8020",
          "addressCountry": "AT"
        }
      }
    }
  ]
}

1.2.3 Recurring Event

A recurring event is an event where the single event instances hafe little to no difference to the main event, except maybe the exact timing. Therefore it is annotated as schema:Event and its instances are implicitly defined as schema:Schedule entries.

The event itself needs a start and end date which describes when the first event takes place and when the last event takes places. The schedule defines the exact day and time, and things like the repeat count, the repeat frequency and potential exceptions.

Note: for a recurring event it is also valid to use schema:EventSeries instead of schema:Event.

Simple schedule example

{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Sommerklänge 2025 - Konzertreihe",
  "startDate": "2025-08-01",
  "endDate": "2025-08-22",
  "location": {
    "@type": "Place",
    "name": "Wiener Konzerthaus",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "Lothringerstraße 20",
      "addressLocality": "Wien",
      "postalCode": "1030",
      "addressCountry": "AT"
    }
  },
  "eventSchedule": {
    "@type": "Schedule",
    "startDate": "2025-08-01",
    "endDate": "2025-08-22",
    "repeatFrequency": "P1W",
    "byDay": ["FR"],
    "startTime": "19:00",
    "endTime": "21:00"
  }
}

2. Use Cases

Single events and event series' are trivial to annotate. Recurring events with schedules can become complex and often lead to misunderstandings. In this section we will list some examples for good patterns and also some anti patterns with corrections.

2.1 Good Examples

✅ Good Example 1

Correct use of Schedule for a recurring event:

{
  "@id": "http://example.com/event/001",
  "@type": "schema:Event",
  "schema:name": "Weekly Yoga Class",
  "schema:schedule": [
    {
      "@type": "schema:Schedule",
      "schema:repeatFrequency": "P1W",
      "schema:byDay": "https://schema.org/Tuesday",
      "schema:startTime": "18:00",
      "schema:endTime": "19:30"
    },
    {
      "@type": "schema:Schedule",
      "schema:repeatFrequency": "P1W",
      "schema:byDay": "https://schema.org/Monday",
      "schema:startTime": "19:00",
      "schema:endTime": "20:30"
    }
  ]
}

The event recurs weekly (repeatFrequency: P1W), which is exactly what Schedule is meant for.

This event describes a recurring yoga class (recurring weekly repeatFrequency: P1W) that takes place every Monday from 19:00–20:30 and Tuesday from 18:00–19:30, using two separate Schedule objects within the schema:schedule array.

✅ Good Example 2

Correct use of Schedule with a defined date range:

{
  "@id": "http://example.com/event/002",
  "@type": "schema:Event",
  "schema:name": "Seasonal Art Exhibition",
  "schema:schedule": {
    "@type": "schema:Schedule",
    "schema:repeatFrequency": "P1D",
    "schema:startDate": "2025-06-01",
    "schema:endDate": "2025-09-30",
    "schema:startTime": "10:00",
    "schema:endTime": "18:00"
  }
}

The event repeats daily within a specific date range (startDate and endDate), making Schedule a valid choice.

✅ Comprehensive good Example

This example describes a recurring event — specifically, a weekly market (Wochenmarkt) that takes place at different times of the year on different days.

{
  "@context": "https://schema.org",
  "@type": "schema:Event",
  "@id": "http://example.com/market/weekly",
  "schema:name": "Wochenmarkt",
  "schema:location": {
    "@type": "schema:Place",
    "schema:name": "Marktplatz",
    "schema:address": {
      "@type": "schema:PostalAddress",
      "schema:streetAddress": "Hauptstraße 1",
      "schema:addressLocality": "Beispielstadt",
      "schema:postalCode": "12345",
      "schema:addressCountry": "DE"
    }
  },
  "schema:eventSchedule": [
    {
      "@type": "schema:Schedule",
      "schema:name": "Öffnungszeiten Oktober - März",
      "schema:startDate": "2025-10-01",
      "schema:endDate": "2026-03-31",
      "schema:repeatFrequency": "P1W",
      "schema:byDay": [
        "https://schema.org/Monday",
        "https://schema.org/Wednesday"
      ],
      "schema:startTime": "08:00",
      "schema:endTime": "12:00"
    },
    {
      "@type": "schema:Schedule",
      "schema:name": "Öffnungszeiten April - September",
      "schema:startDate": "2025-04-01",
      "schema:endDate": "2025-09-30",
      "schema:repeatFrequency": "P1W",
      "schema:byDay": [
        "https://schema.org/Tuesday",
        "https://schema.org/Friday"
      ],
      "schema:startTime": "07:00",
      "schema:endTime": "12:00"
    }
  ]
}

Let’s walk through it in detail and explain the use of schema:eventSchedule, which is key to modeling such recurring patterns correctly.

As described above, schema:eventSchedule allows you to define a recurring event pattern (e.g. "every Tuesday and Friday from April to September") without listing each occurrence manually. Two separate schema:Schedule objects are used to describe different time periods with different rules (seasonal variation).

📆 First Schedule: Winter Hours (Oct–Mar)

{
  "@type": "schema:Schedule",
  "schema:name": "Öffnungszeiten Oktober - März",
  "schema:startDate": "2025-10-01",
  "schema:endDate": "2026-03-31",
  "schema:repeatFrequency": "P1W",
  "schema:byDay": [
    "https://schema.org/Monday",
    "https://schema.org/Wednesday"
  ],
  "schema:startTime": "08:00",
  "schema:endTime": "12:00"
}
Meaning:
  • This schedule is valid from Oct 1, 2025, to Mar 31, 2026.
  • The event repeats weekly (repeatFrequency: P1W).
  • It occurs every Monday and Wednesday.
  • The market opens at 08:00 and ends at 12:00.

🌼 Second Schedule: Summer Hours (Apr–Sep)

{
  "@type": "schema:Schedule",
  "schema:name": "Öffnungszeiten April - September",
  "schema:startDate": "2025-04-01",
  "schema:endDate": "2025-09-30",
  "schema:repeatFrequency": "P1W",
  "schema:byDay": [
    "https://schema.org/Tuesday",
    "https://schema.org/Friday"
  ],
  "schema:startTime": "07:00",
  "schema:endTime": "12:00"
}
Meaning:
  • This schedule is valid from Apr 1 to Sep 30, 2025.
  • It repeats weekly, but on Tuesdays and Fridays.
  • Start time is earlier in summer: 07:00–12:00.

✅ Complex good example

Christmas Market:

{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Weihnachtsmarkt am Hauptplatz",
  "description": "Der festlich geschmückte Weihnachtsmarkt am Hauptplatz mit Kunsthandwerk, Glühwein und kulinarischen Spezialitäten.",
  "location": {
    "@type": "Place",
    "name": "Hauptplatz",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "Hauptplatz 1",
      "addressLocality": "Musterstadt",
      "postalCode": "12345",
      "addressCountry": "DE"
    }
  },
  "startDate": "2025-12-01",
  "endDate": "2025-12-24",
  "eventSchedule": [
    {
      "@type": "Schedule",
      "startDate": "2025-12-01",
      "endDate": "2025-12-15",
      "repeatFrequency": "P1D",
      "byDay": [
        "https://schema.org/Monday",
        "https://schema.org/Tuesday",
        "https://schema.org/Wednesday",
        "https://schema.org/Thursday",
        "https://schema.org/Friday"
      ],
      "startTime": "10:00",
      "endTime": "20:00"
    },
    {
      "@type": "Schedule",
      "startDate": "2025-12-01",
      "endDate": "2025-12-15",
      "repeatFrequency": "P1D",
      "byDay": [
        "https://schema.org/Saturday",
        "https://schema.org/Sunday"
      ],
      "startTime": "11:00",
      "endTime": "21:00"
    },
    {
      "@type": "Schedule",
      "startDate": "2025-12-16",
      "endDate": "2025-12-24",
      "repeatFrequency": "P1D",
      "byDay": [
        "https://schema.org/Monday",
        "https://schema.org/Tuesday",
        "https://schema.org/Wednesday",
        "https://schema.org/Thursday",
        "https://schema.org/Friday"
      ],
      "startTime": "10:00",
      "endTime": "21:00"
    },
    {
      "@type": "Schedule",
      "startDate": "2025-12-16",
      "endDate": "2025-12-24",
      "repeatFrequency": "P1D",
      "byDay": [
        "https://schema.org/Saturday",
        "https://schema.org/Sunday"
      ],
      "startTime": "11:00",
      "endTime": "22:00"
    }
  ],
  "eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode",
  "eventStatus": "https://schema.org/EventScheduled",
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock"
  }
}

This example describes a Christmas market held from December 1 to 24, 2025. The market features free admission and includes festive offerings like handicrafts and seasonal foods. The schema:eventSchedule property is used here to describe recurring opening hours that vary between weekdays and weekends, and that change mid-way through December. By defining multiple Schedule objects, this approach allows precise modeling of temporal patterns (e.g. longer hours on weekends and during the final week before Christmas), which is especially useful for search engines and digital assistants to accurately display availability.

2.2 Anti patters

When not to use eventSchedule: If your events do not repeat or are not regular, you should instead:

  • Use individual Event objects inside an EventSeries, or
  • List Event items individually without recurrence logic.

❌ Bad Example 1

Incorrect use of Schedule for a one-time event:

{
  "@id": "http://example.com/event/003",
  "@type": "schema:Event",
  "schema:name": "Grand Opening Concert",
  "schema:schedule": {
    "@type": "schema:Schedule",
    "schema:repeatFrequency": "P0D",
    "schema:startDate": "2025-04-15",
    "schema:endDate": "2025-04-15"
  }
}

This is a one-time event, so Schedule is unnecessary. Instead, schema:startDate and schema:endDate should be used directly inside Event.

✅ Corrected Version of the Bad Example 1 (Without Schedule)

{
  "@id": "http://example.com/event/003",
  "@type": "schema:Event",
  "schema:name": "Grand Opening Concert",
  "schema:startDate": "2025-04-15",
  "schema:endDate": "2025-04-15"
}

Updated 22 days ago