Skip to main content

Schema piece - Event

Describes an Event, which occurs at a time and in a place, with optional extra information.

Triggers​

Should be added as a top-level node in the graph, when the content of a page describes an event.

Required properties​

A valid Event must have the following properties.

  • @type: Event.
  • @id: The site's home URL appended by #/schema/Event/{{ID}}, where {{ID}} is a unique identifier.
  • name: A string naming the event.
  • location: Either a Place or VirtualLocation node, describing where the event will take place.
  • startDate: The start date and time of the event in ISO-8601 format (including the UTC timezone offset).

Optional properties​

The following should be added whenever available and valid:

  • description: A text string describing or summarizing the event.
  • endDate: The end date and time of the event in ISO-8601 format (including the UTC timezone offset).
  • eventAttendanceMode: An EventAttendanceModeEnumeration, reflecting the attendance mode of the event (either OfflineEventAttendanceMode, OnlineEventAttendanceMode or MixedEventAttendanceMode).
  • image: An imageObject (or an array of imageObjects) representing the event, referenced by ID.
  • organizer: The Organization or Person responsible for organizing the event.
  • performer: A Person (or an array of Persons) performing at the event.

Conditional properties​

When the event is taking place at a physical location (or 'offline')​

  • location.name: The name of event location/venue.
  • location.address: The PostalAddress of the event location/venue.

When the event is 'virtual' (or 'online')​

  • location.url: The URL where the event will take place.

When the event has been cancelled​

  • eventStatus: An EventStatusType enumeration, set to EventCancelled.

When the event has been rescheduled​

  • eventStatus: An EventStatusType enumeration, set to EventRescheduled.
  • previousStartDate: The previous start date (or array of previous start dates) of the event in ISO-8601 format (including the UTC timezone offset).

When the event has one or more 'offers' (e.g., for ticketed events)​

  • offers: An Offer (or an array of Offers).

Failure scenarios​

If any of the required fields of the Event are missing or invalid, the node should not be output.

If a node is not output, any entities which would otherwise have declared a relationship with it should remove those references.

Examples​

Minimum criteria​

{
    "@context": "https://schema.org",
    "@graph": [
        {
            "@type": "Event",
            "@id": "https://www.example.com/#/schema/Event/abc123",
            "name": "My awesome party",
            "location": {
                "@type": "Place",
                "name": "Example Venue",
                "address": {
                    "@type": "PostalAddress",
                    "@id": "https://www.example.com/#/schema/PostalAddress/abc123",
                    "streetAddress": "123 Example Street",
                    "addressLocality": "Example Town",
                    "addressRegion": "Example Region",
                    "postalCode": "ABC 123",
                    "postOfficeBoxNumber": "123",
                    "addressCountry": "US"
                }
            },
            "startDate": "2025-07-21T19:00-05:00"
        }
    ]
}

Extended criteria​

{
    "@context": "https://schema.org",
    "@graph": [
        {
            "@type": "Event",
            "@id": "https://www.example.com/#/schema/Event/abc123",
            "name": "My birthday party",
            "description": "We're all getting together in at Example Venue in Fake Town to celebrate my special day!",
            "location": {
                "@type": "Place",
                "name": "Example Venue",
                "address": {
                    "@type": "PostalAddress",
                    "streetAddress": "123 Fake Street",
                    "addressLocality": "Fake Town",
                    "postalCode": "12345",
                    "addressRegion": "XY",
                    "addressCountry": "US"
                }
            },
            "startDate": "2025-07-21T19:00-05:00",
            "endDate": "2025-07-22T19:00-05:00",
            "eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode",
            "eventStatus": "https://schema.org/EventRescheduled",
            "previousStartDate": "2024-07-21T19:00-05:00",
            "offers": {
                "@type": "Offer",
                "@id": "https://www.example.com/#/schema/Offer/abc123",
                "priceSpecification": {
                    "@type": "PriceSpecification",
                    "price": "22.00",
                    "valueAddedTaxIncluded": "false",
                    "priceCurrency": "GBP"
                },
                "availability": "http://schema.org/InStock",
                "url": "https://www.example.com/example-product-page/",
                "seller": {
                    "@id": "https://www.example.com/#/schema/Organization/1"
                }
            },
            "image": {
                "@id": "https://www.example.com/uploads/example-image.jpg"
            },
            "organizer": {
                "@id": "https://www.example.com/#/schema/Organization/1"
            },
            "performer": {
                "@id": "https://www.example.com/#/schema/Person/abc123"
            }
        }
    ]
}