A set is a chain of sequels in release order, and every metadata provider has one. A franchise is bigger. It is one long story that crosses films and series: the Marvel films with the series that run between them, Star Wars with The Clone Wars cut into runs between two films, or Alien with its prequels first. No provider holds that order. TMDB collections hold films only, in release order. Wikidata numbers a series but does not date a timeline. The MCU timeline is marketing that moves. So a person writes the order, from research, and this repository holds the result.

Layout #

franchise.schema.json      the JSON Schema every file validates against
AGENTS.md                  how to add or edit a franchise
<Franchise>/franchise.yaml the order, the calendar, the eras, the universes
<Franchise>/AGENTS.md      how that order was built, and why

Each franchise directory holds two files. franchise.yaml is the data. AGENTS.md is the method: the sources, the judgment calls with the alternative not taken, the weak numbers, and the open questions. Read it before you edit the YAML.

The file #

# yaml-language-server: $schema=../franchise.schema.json
name: Star Wars

sources:
  - https://www.starwars.com/news/star-wars-movies-and-series-guide

art:
  poster: https://image.tmdb.org/t/p/original/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg
  fanart: https://image.tmdb.org/t/p/original/iY2ujEY2m68OTTlPFTiHub9joHS.jpg
  logo: https://image.tmdb.org/t/p/original/vswPivs3yuUsk5aW6DbnyeNQ4GX.png
  banner: https://artworks.thetvdb.com/banners/v4/movie/71/banners/6222794af3445.jpg

calendar:
  unit: years
  zero: Battle of Yavin
  before: BBY
  after: ABY

universe: Canon

eras:
  - name: Age of Rebellion
    from: -5
    to: 4

order:
  - movie: tmdb:1893
    title: "Star Wars: Episode I - The Phantom Menace"
    released: "1999-05-19"
    time: { from: -32, to: -32 }
  - series: tvdb:83268
    title: "Star Wars: The Clone Wars"
    released: "2008-10-03"
    seasons:
      - season: 1
        time: { from: -22, to: -22 }
      - season: 3
        episodes: [S03E01, S03E03-S03E22]
        note: Lucasfilm's order plays S03E02 before S02E16.
  - movie: tmdb:74849
    title: "The Star Wars Holiday Special"
    released: "1978-11-17"
    universes: [Legends]
    time: { from: 1, to: 1 }

name and order are required. Everything else is optional.

Part	What it is
`name`	The name to show.
`sources`	The pages the author read for the order and the times. The next author reads them first.
`art`	Links to art for the whole franchise. The repository holds links and never image bytes. A link points at a public image a reader may fetch. The first film's collection art on TMDB is the usual source.
`calendar`	The franchise's own clock. Without it, the file holds an order and nothing dates it.
`universe`	The universe the story happens in. An entry that names no universes of its own is in this one.
`eras`	Named stretches of the timeline, each with a span. Needs a calendar. Spans may overlap.
`order`	The story order, first to last.

Entries #

An entry is one film or one series. A film is movie with a provider id. A series is series with a provider id and, when only part of it plays here, a seasons list.

A provider id is scheme:id. Films use tmdb and series use tvdb. Another scheme is legal, and a reader resolves it only if its own collection knows that scheme.

A series with no seasons means the whole show. A season with no episodes means the whole season, in aired order. An episodes list holds codes like S03E01 or ranges like S03E03-S03E22, in the order they play. Specials are season 0. The same show may appear again further down for the seasons that play after a film, and the same season may appear again inside one show when the story order cuts it into runs.

Episode codes follow TheTVDB's numbering for the show. That is not always aired order. TheTVDB numbers Firefly in aired order, so its pilot is S01E11, and the Firefly file lists S01E11 first. A collection numbered by another provider needs a different list, and the directory's AGENTS.md says which numbering the file follows.

Every entry, season included, may carry these:

Field	What it is
`title`	The name to show when no collection holds the member. The title carries no year. `released` carries the date.
`released`	The real-world date as an ISO 8601 string in quotes: `"1999"`, `"1999-05"`, or `"1999-05-19"`, as much of the date as is known. On a film it is the first public release, which TMDB shows as its primary date. On a series it is the day the first episode aired, which TheTVDB shows as First Aired. It is never the story's own calendar, which `time` carries. An entry with no `released` is a coming release with no announced date. Not on a season.
`time`	The span of the entry, as `{ from, to }`. Needs a calendar.
`universes`	Every universe whose story this entry continues or joins, when that is more than the franchise's own universe. Several names mean the entry belongs to all of them at once. Not on a season.
`note`	Free text for the next author.

Art #

The art block holds up to five links, and every key is optional. The repository holds links and never image bytes. A link points at a public image a reader may fetch. The first film's collection art on TMDB is the usual source.

Key	What it is
`poster`	A 2:3 portrait image.
`fanart`	A 16:9 background image with no title on it.
`landscape`	A 16:9 image that carries the title or the logo.
`logo`	A transparent PNG of the franchise's wordmark.
`banner`	A wide thin strip, about 5:1.

These are Kodi's names for the same five art kinds, so a reader that knows Kodi's names knows these. Each directory's AGENTS.md says where each link came from and which kinds that franchise has none of.

Times #

A calendar needs a unit, either years or days. Without zero, before, and after, the times are plain calendar years, which is what the Marvel films count in. With zero, the times count from the named event, as Star Wars counts from the Battle of Yavin and The Walking Dead counts days from the outbreak.

before and after are short marks of at most six characters, such as BBY and ABY. A reader prints the mark after the magnitude of the time: before on a time before the zero, after on the zero and every time past it. A time of -233 with before: BBY reads "233 BBY", with no minus sign. The marks never carry a sentence; that is what zero is for. A reader prints the zero once, as one caption for the whole timeline: "Years from the Battle of Yavin", "Days from the outbreak", "Years from the Fall of the Twelve Colonies". Leave the marks out where the franchise has no short ones. A days calendar without them reads "Day 1141", and a years calendar without them keeps the minus sign on the times before the zero.

A time is from and to in the calendar's unit, and they are equal for a story that stays in one year. A time on a show covers every season under it, and a time on a season overrides it. A flashback inside one film does not widen its span; the span is the film's main setting. An entry with no time has a place in the order and no place on a timeline.

Universes #

A franchise often holds more than one telling of its story, or a branch the story itself makes. The Sony Spider-Man films that No Way Home reaches are not Earth-616. The 1984 Dune is not Villeneuve's. The Fox X-Men films fork at Days of Future Past. The universes field carries that.

The rule is about story, not about place. An entry names every universe whose story it continues or joins, even when the story never goes there. The file's own universe names the main one, and an entry names universes only when it belongs to more than that one. One name means the entry belongs to that universe. Several names mean it belongs to all of them at once, as Spider-Man: No Way Home brings two other Spider-Man stories into Earth-616 and names all three. A reader may draw the main universe as the line and every other universe as a side lane beside the year it meets the main story. An entry with several universes crosses those lanes.

How a reader uses the file #

A reader walks order depth first. That walk is the story order, one position per film or episode. A whole show or a whole season expands to the episodes the reader's collection holds, so a show that is still airing fills in with no edit to the file.

A member need not be in the reader's collection. The reader draws it as a gap with its title, and the gap fills when the title arrives. A gap whose released is ahead of today, or missing, is a coming release. Any other gap is a title to go find.

The order and the times can disagree, and both are right. A list drawn from order follows the list. A timeline drawn from time follows the spans. Deadpool and Wolverine is set in 2024 and plays after The Marvels, set in 2026, because that is where the story reaches it.

Validation #

Install the commit hooks with prek:

prek install

The hooks run yamlfmt to format changed YAML files, then yamllint to check them. If formatting changes a file, review and stage the fix before committing again. To format and lint every tracked YAML file:

prek run --all-files

Formatting does not validate franchise membership or the schema.

Every file opens with a yaml-language-server comment that points at the schema, so an editor with YAML support validates it as you type. To check every file from a shell:

uv run --with pyyaml --with jsonschema python3 -c '
import glob, json, jsonschema, yaml
schema = json.load(open("franchise.schema.json"))
for path in sorted(glob.glob("*/franchise.yaml")):
    data = yaml.safe_load(open(path))
    jsonschema.validate(data, schema)
    for entry in data["order"]:
        if "released" not in entry:
            print("  unreleased:", entry.get("title"))
    print("ok", path)
'

Contributing #

Add a directory with franchise.yaml and AGENTS.md, or edit an existing one. Two rules hold for every edit:

Never remove a member. Add and reorder, so a wrong edit leaves a wrong order and never a lost film.
Verify every provider id by fetching its page and reading the title. Provider slugs mislead, and an id from memory is wrong about one time in ten.

AGENTS.md in this directory has the full method. It is written for an agent, and it works for a person.

Open questions #

A film with chapters set centuries apart, like Predator: Killer of Killers, holds one span. The schema has no way to give it three.
A franchise names films and series only. Books, comics, and games wait on a scheme for them, and each directory's AGENTS.md says where they would slot.
art carries one image per kind for the whole franchise. Art for a single film or series is the reader's own to find.
banner is hard to source. Thirteen files have none, and each directory's AGENTS.md says why. fanart.tv, the other source, answers a fetch with a Cloudflare challenge.

License #

Everything here is dedicated to the public domain under CC0 1.0. Use it, copy it, change it, and ship it, with no attribution required.

Clone this repository

Fiction franchises #