XooCode(){

Duration

Duration is a schema.org DataType for any time span: video length, recipe cook time, course workload, event runtime, lease length, validity periods. Unlike Thing-based types, Duration is a primitive value type, like Number or Text. There is no "@type": "Duration" entity node; instead, you provide a Duration value as a string in ISO 8601 format on a property that expects a Duration.

The type hierarchy is DataType → Quantity → Duration (a parallel branch to Thing). Properties that accept Duration include duration (Movie, VideoObject, AudioObject, Event), timeRequired (CreativeWork, HowTo, TechArticle), cookTime/prepTime/totalTime (Recipe), courseWorkload (Course), leaseLength (Accommodation), validFor (Credential), estimatedFlightDuration (Flight).

Full example of schema.org/Duration json-ld markup

The markup is verified as valid with Rich Results Test from Google.

schema.org/Duration
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Movie",
  "name": "The Children's Doctor",
  "duration": "PT1H42M"
}
</script>

ISO 8601 duration format

Duration values follow ISO 8601: P[n]Y[n]M[n]DT[n]H[n]M[n]S. The leading P stands for "period". Times after a date use a T separator. Examples: P3Y (3 years), P6M (6 months), P2W (2 weeks), PT1H (1 hour), PT30M (30 minutes), PT45S (45 seconds), PT1H30M (1 hour 30 minutes), P1DT12H (1 day 12 hours).

Common gotchas

The M after the date portion means months; the M after T means minutes. P30M is 30 months; PT30M is 30 minutes. The T separator is required when using time units, even with no date portion. Forgetting the T is the most common error: P1H30M is invalid; PT1H30M is correct.

Duration vs Number for minutes

Some properties accept either Duration or Number. Recipe's cookTime historically accepted Number minutes but now expects Duration. Use the ISO 8601 form for forward compatibility. A bare number like 60 for "60 minutes" is ambiguous (60 what?) and may not parse on validators that strictly enforce Duration.

Minimal valid version

The smallest markup that still produces a valid Duration entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/Duration (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Movie",
  "name": "The Children's Doctor",
  "duration": "PT1H42M"
}
</script>

Google rich results this unlocks

Duration is a structural type. It does not produce a rich result on its own.

Its value comes from combining it with a primary type whose markup earns a rich result (Article, Product, Event, and so on). Duration becomes the trunk that the primary type branches off viamainEntityorbreadcrumb. Include it on every page as the backbone of your markup.

Common Duration mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

  1. 01

    Missing T separator for time

    Wrong
    "duration": "P1H30M"
    Right
    "duration": "PT1H30M"

    The T separator is required when expressing time units (hours, minutes, seconds). Without T, the parser cannot tell H means hours vs some other interpretation. Date-only durations skip T (P3Y for 3 years), but time durations require it (PT1H for 1 hour).

  2. 02

    Using M for both months and minutes ambiguously

    Wrong
    "duration": "P30M" intending 30 minutes
    Right
    "duration": "PT30M" for 30 minutes; "P30M" means 30 months

    M after the date portion (no T) means months. M after T means minutes. P30M is 30 months. PT30M is 30 minutes. The T disambiguates.

  3. 03

    Plain number instead of ISO 8601

    Wrong
    "cookTime": 60 (intending 60 minutes)
    Right
    "cookTime": "PT1H"

    Schema.org Duration properties expect ISO 8601 strings, not plain numbers. A bare 60 is ambiguous (60 what units?) and may not pass strict validators. Always use the ISO 8601 form: PT1H, PT45M, P3D.

Schema properties in this example

DurationdurationtimeRequiredcookTimeprepTimetotalTimecourseWorkloadleaseLengthvalidForestimatedFlightDuration

About the example data

Used everywhere in the Xoo universe: The Children's Doctor documentary's runtime (PT1H42M), recipe cook times, course workloads, podcast episode lengths.

Comments

Loading comments...

Leave a comment