Skip to content
screenjson

For educators

ScreenJSON for Educators

A classroom-friendly way to teach screenplay structure, analyse canonical scripts, and run writing workshops on top of a format that students can actually inspect.

Last updated January 2026

Screenplay structure is a teachable thing — when it’s visible

Teaching screenplay structure from flat PDFs is hard, because the structure isn’t on the page; it’s in the reader’s head. Students learn to recognise a slugline, a cue, a parenthetical, a transition, but the page itself doesn’t say “this is a slugline” — it says “this is 11-point Courier Prime, bold, flush left, preceded by a blank line.”

ScreenJSON flips that. Every structural element of a screenplay becomes an explicit, named, typed node. That makes it a genuinely useful teaching artifact: a student can open a screenplay in a text editor, see "type": "slugline" next to the line, and understand what that line is, not just what it looks like.

A short classroom workflow

  1. Pick a canonical script that students have read. (Most feature studios will not object to academic use of their own screenplays; check your institution’s licensing first.)
  2. Convert it to ScreenJSON with screenjson-export — free, open source, Docker-only, no account required.
  3. Ask structural questions. “How many scenes are there?” “How many have dialogue vs. action only?” “How does the average scene length change in Act III?” These are three-line jq queries, and they make structure visible in a way that reading the PDF never can.
  4. Ask character questions. “Who speaks the most?” “At what page does the antagonist first appear?” “Does the protagonist’s dialogue count rise or fall across the script?”
  5. Compare two scripts. With two or more ScreenJSON documents you can compute real statistics — scene-count distributions, dialogue/action ratios, character talk-time. Students can see that a Shane Black screenplay and a Tony Gilroy screenplay are measurably different in ways they may have sensed but couldn’t articulate.

Writing workshops

For hands-on writing workshops, the same structural explicitness lets students see their own work differently:

  • Students write in their preferred tool.
  • Export to .fdx, convert to ScreenJSON.
  • Import into a viewer or a small classroom tool that highlights proportions — action vs. dialogue, scene count per act, average scene length, character talk-time.

The goal isn’t to reduce writing to metrics; it’s to show students, without a teacher having to say it, whether a scene is front-loaded with action or talk, whether a character has gone silent for ten pages, whether Act II has swelled past the outline.

Suggested exercises

Scene taxonomy (beginner)

Give students a ScreenJSON file. Ask them to count, using jq:

  • Total scenes
  • Interior vs. exterior
  • Night vs. day
  • Scenes with more than 5 elements
  • Scenes with no dialogue

Each is one line:

jq '.document.scenes | length' script.json
jq '[.document.scenes[] | select(.heading.context == "INT")] | length' script.json

Character arcs (intermediate)

Give students the list of character UUIDs and ask them to plot the per-scene dialogue count for each character across the script. Produces a genuinely illuminating chart.

Diff two drafts (intermediate)

Give students two ScreenJSON files — draft 3 and draft 4 of the same script. Ask them to find every scene that was added, removed, or materially rewritten. Because every scene has a stable UUID, diff is trivial; because every element has one too, fine-grained diff is also trivial.

Structural rewrite (advanced)

Take an existing ScreenJSON document. Ask students to write a small script — in any language — that rearranges scene order, re-casts a character, or swaps action and dialogue for a specific sequence, then re-emits the document through screenjson export -f pdf or -f fountain. They will see the difference structural editing makes vs. linear editing.

On licensing and fair use

The ScreenJSON schema is open. The reference CLI is MIT-licensed. Both can be used freely in a classroom. The contents of any specific screenplay — the text itself — are subject to copyright. Check your institution’s fair-use policy and stick to scripts your institution has the right to use for instruction.

For introductory classes, plenty of screenplays have been released into the public domain or under permissive licenses, and the ScreenJSON project maintains a small corpus of example documents for exactly this purpose.

Next