The Web Has Margins Again: W3C Annotations for the Developer Community Graph

A talk on YouTube looks like a single object: one player, one title, one description, one URL. In a community graph it is something richer. The recording points to a talk; the talk points to its speakers, event, projects, and companies; those nodes lead to other talks, papers, podcasts, photographs, and the communities that brought them together.

We have begun making those relationships visible in two complementary ways. On the Functional TV channel, where we own the metadata, we add canonical devreal.ai node URLs directly to each video description while preserving the real talk abstract and removing obsolete conference promotions. For recordings published by other channels, we leave the source untouched and publish a standards-based annotation layer around it.

That second layer uses the W3C Web Annotation Data Model and the retrieval conventions of the W3C Web Annotation Protocol. It gives the web margins again: a portable place to describe, link, classify, and eventually address parts of a resource without requiring ownership of the resource itself.

What a Web Annotation is

A W3C Web Annotation is a web resource with an identity of its own. Its core is deliberately small:

• Target — the resource being annotated, such as a canonical YouTube watch URL.
• Body — what the annotation says or links to. It may be text, another web resource, structured data, or several bodies.
• Motivation — why the relationship exists: describing, linking, commenting, tagging, classifying, and so on.

The model is expressed as JSON-LD, using the shared annotation context at http://www.w3.org/ns/anno.jsonld. JSON-LD matters because the object is not merely an application-specific JSON response. Its terms resolve into a common semantic vocabulary, so another conforming client can interpret Annotation, body, target, and motivation without importing devreal.ai code.

An annotation may target an entire video or a more precise segment. A SpecificResource can carry a FragmentSelector conforming to the W3C Media Fragments specification—for example, t=30,60 for the interval from thirty to sixty seconds. Our first graph-preface annotations target whole recordings, but the representation is ready for timestamped claims, quotations, topic changes, demonstrations, and corrections.

Why this is different from editing a description

A platform description is useful, but it belongs to one platform and one account. Only the channel owner can change it. It is also a single text field: readable, indexable, and practical, but not a typed collection of independently addressable relationships.

An annotation layer has a different ownership model. The YouTube video remains where its publisher put it. We identify that URL as the target and publish our interpretation under our own domain. The annotation has a stable URL, provenance, creation time, media type, and motivation. The body can point directly to the canonical graph node for a person or talk. Anyone can retrieve it without asking YouTube to change anything.

This separation is especially important for a community archive. We want to say, “this recording depicts this talk, presented by this person, at this event, in connection with this project,” while keeping clear which facts came from the original publisher and which relationships are asserted by devreal.ai.

Cross-linking videos we publish

Functional TV is our own channel, so the most immediate interface is the video description itself. For every reviewed talk, the new preface links the recording to its canonical talk node and every applicable reviewed speaker, company, project, and event node. A divider follows the preface, then the genuine talk description continues unchanged.

The update is intentionally atomic per video. The same write that installs the graph preface removes recognized, obsolete conference announcements and their optional divider. Before every write we journal the complete old and new descriptions, title, channel, timestamp, and transaction identifier. Afterward we fetch fresh state and verify the description, title, channel, privacy status, and playlist membership. Ambiguous mappings are held rather than guessed.

Those links turn a platform field into a set of doors. A viewer can move from a video to a speaker, from the speaker to other talks and publications, or from an event to its recordings and photographs. The description remains useful inside YouTube, email previews, search results, and embedded players.

Annotating videos published elsewhere

For external videos we use the same canonical graph identities but a different delivery mechanism. devreal.ai currently publishes annotations for 4,735 external YouTube recordings. Every recording has a shareable viewer at /watch/<youtube-id>, an annotation collection at /annotations?youtube=<youtube-id>, and stable URLs for each individual annotation.

The collection response is served as application/ld+json with the W3C annotation profile. It uses AnnotationCollection and paginated AnnotationPage resources. Responses support GET, HEAD, and OPTIONS, include ETags, advertise the LDP container and annotation protocol constraints, and allow cross-origin retrieval. That last detail is essential: the annotations should be usable by another site, research notebook, browser extension, archive, or player—not only by our interface.

The viewer embeds the privacy-enhanced YouTube player and places the graph annotations beside it. It also advertises its annotation service in the HTML document and embeds the current annotations as JSON-LD. A person sees a navigable graph panel; software sees the same relationships in a standard form.

Tathagata Das: one target, three annotations

Consider Tathagata Das’s talk Spark Streaming: The State of the Union and the Road Beyond, recorded at Spark Summit East 2015. The source is the external YouTube video youtube.com/watch?v=--3sMbnamUs. We do not need control of that channel to connect it to the graph.

Open the annotated player and the recording is accompanied by three W3C annotations:

1. A describing annotation whose textual body explains that the video is represented in the developer community graph and lists its canonical nodes.
2. A linking annotation to the canonical talk node, Spark Streaming: The State of the Union and the Road Beyond.
3. A linking annotation to the canonical speaker node, Tathagata Das.

The describing annotation is a compact example of the model:

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "https://devreal.ai/annotations/youtube---3sMbnamUs-preface",
  "type": "Annotation",
  "motivation": "describing",
  "body": {
    "type": "TextualBody",
    "format": "text/plain",
    "language": "en",
    "purpose": "describing",
    "value": "This external talk video is annotated in devreal.ai..."
  },
  "target": "https://www.youtube.com/watch?v=--3sMbnamUs"
}

The two linking annotations have the same YouTube target, but their bodies are web resources: the talk URL and Tathagata’s person URL. Because each statement has its own identifier, clients can cite, cache, mirror, filter, or extend the relationships independently.

You can inspect the live annotation collection as JSON-LD, then follow any item to its permanent annotation URL. The source video, the human-readable viewer, the graph nodes, and the machine-readable statements are separate resources connected by explicit links.

A graph overlay that can travel

The room of mirrors is an apt metaphor. A video reflects a talk; a talk reflects a speaker; the speaker reflects companies, projects, publications, podcasts, and other appearances. The point is not to trap those reflections inside one interface. A standards-based annotation can travel while preserving its target, meaning, and provenance.

Our own channel descriptions make the graph visible at the source. W3C annotations let us offer the same navigable context for the wider web, under our own control and without pretending to own the media. Together they make a community archive less like a list of uploads and more like what it always was: a network of people and ideas, seen from many angles.