Direct answer

Swoopr's Knowledge Graph is generated from the same registries that power the public site, with stable entity IDs, explicit content-resource roles, typed relationships, provenance metadata, and build-time validation. The graph does not rely on title similarity or keyword co-occurrence as if they were facts. Explicit registry metadata is authoritative; page-level links and structured fields are supporting evidence; controlled inference is a separate, confidence-scored layer.

A production graph build is reproducible. Given the same content-registry revision and graph rules, it produces the same canonical node identities and explicit relationships. The export records which registry revision it represents, when it was generated, and any exclusions or unresolved exceptions.

Methodology goals

The system is designed to solve six problems:

  1. give every important concept a stable identity;
  2. separate a concept from the pages and tools about it;
  3. identify one canonical educational owner where deeper ownership is needed;
  4. express prerequisite, source, formula, tool, provider, and comparison relationships explicitly;
  5. carry freshness and provenance for facts that change;
  6. make graph integrity testable in CI.

These goals are deliberately narrower than "connect everything to everything." A dense graph can be worse than a sparse one if the edge vocabulary is vague or the evidence is weak.

Source systems

Content registry

The content registry is the authoritative inventory for publishable Swoopr resources. It provides route, title, content type, indexability, canonical role, primary entity ID, parent hub, and declared relationships. The graph compiler never creates a second resource simply because the same page appears in a sitemap and a content registry. URL normalization happens before node creation.

Glossary registry

The glossary registry is the primary lexical source for canonical names, aliases, abbreviations, disambiguation notes, and fast definitions. "P/E ratio," "PE ratio," and "price-to-earnings ratio" resolve to one concept ID. The graph ingests canonical terms, not every visible glossary synonym as an independent entity.

Tool registry

The tool registry distinguishes public interactive products from internal functions. A public tool must have a stable public URL, human-readable name, purpose, inputs, outputs, methodology, limitations, and related educational concepts. Internal build or API actions remain internal unless Swoopr intentionally documents them for a user-facing technical audience.

Learning-path and academy registries

These systems provide explicit sequence information. Their prerequisite and next-step relationships are stronger evidence than inferred topic similarity because the editorial sequence is deliberate.

Authority and source registry

The authority registry normalizes primary organizations and provider identities such as the SEC, IRS, FINRA, Federal Reserve, CFTC, S&P Dow Jones Indices, MSCI, FTSE Russell, and others used across the site. Each record contains canonical name, aliases, organization type, approved domains, jurisdiction, and scope. This registry enables provider-domain validation: a link labeled as S&P Dow Jones Indices should not silently resolve to an MSCI domain.

Stable entity IDs

Entity IDs should survive title and URL changes. A stable concept ID takes the form:

Swoopr:concept:price-to-earnings-ratio

A resource ID takes the form:

Swoopr:content:guide:price-to-earnings-ratio

The entity is the thing. The content resource is Swoopr's representation of the thing. This distinction is essential for redirects and migrations. If a guide moves from one URL to another, the concept ID should not change. If a glossary definition and long-form guide coexist, they share the concept ID while retaining distinct resource IDs.

Graph layers

The graph exposes three compatible layers.

Concept layer

Nodes represent financial concepts, real-world organizations, securities, indexes, asset classes, market structures, formulas, risks, and other things a learner can reason about.

Content layer

Nodes represent Swoopr pages, definitions, quick answers, tools, tables, datasets, learning resources, and policies.

Journey layer

Edges describe educational progression: prerequisite, next step, previous step, commonly confused with, comparison, and recommended verification source.

Layering avoids several common graph errors. It prevents a page URL from becoming the only identity for a concept. It prevents a calculator from being treated as the same object as the formula it implements. It also lets Swoopr change navigation without rewriting the underlying concept graph.

Relationship vocabulary

Relationship terms are finite and documented. The compiler rejects unknown predicates unless they are added through an ontology change. High-value predicates include:

  • IS_A
  • PART_OF
  • ABOUT
  • DEFINES
  • EXPLAINS
  • CANONICAL_PAGE
  • REQUIRES_KNOWLEDGE_OF
  • NEXT_TOPIC
  • COMPARES_WITH
  • DIFFERS_FROM
  • USES
  • IMPLEMENTS
  • HAS_FORMULA
  • SUPPORTED_BY
  • SOURCED_FROM
  • GOVERNED_BY
  • PROVIDED_BY
  • CONSTITUENT_OF
  • TRACKS
  • REDIRECTS_TO

The methodology prefers the most specific defensible predicate. RELATED_TO is available for genuinely general relationships, but it should not become the default because an implementation is easier when every edge uses the same generic label.

Evidence and confidence

Every edge states how it was established.

  • OBSERVED means explicit structured metadata, a verified public relationship, or a primary source.
  • INFERRED means the relationship was derived from controlled rules and remains a candidate or confidence-scored edge.
  • BENCHMARKED means the relationship is expected from an authoritative external taxonomy or domain model and should be reconciled against Swoopr coverage.
  • RECOMMENDED means the edge does not exist yet and belongs to a remediation package.

The public graph normally displays observed relationships. Inferred relationships may be shown when useful, but the UI must distinguish them from observed ones.

Canonical ownership

A canonical educational owner is the resource that answers the concept's broadest, deepest educational intent. Supporting resources can coexist when their jobs differ.

The graph compiler flags:

  • more than one canonical guide for the same concept;
  • a page that self-identifies as canonical while its registry assigns another owner;
  • two resources with the same H1 and materially overlapping intent;
  • glossary entries that duplicate a deep guide rather than linking to it;
  • data pages that duplicate explanatory copy instead of linking to the canonical guide.

A flagged conflict is not automatically deleted. It enters a migration workflow with KEEP, RECLASSIFY, MERGE, or REDIRECT as explicit outcomes.

Temporal model

Any edge whose truth can change must carry review metadata. For example, a constituent relationship should have an effective date and source snapshot. A tax limit should carry a tax year and jurisdiction. A regulator rule should identify the governing authority and effective date. A market-data value should carry its observation timestamp and provider.

A graph that omits time can be syntactically correct while semantically wrong. Stable definitions can use a lighter review cadence without losing provenance.

Build pipeline

A production build follows this sequence:

  1. Content and source registries are loaded.
  2. IDs and aliases are normalized.
  3. Explicit nodes are created.
  4. Explicit relationships are compiled.
  5. Canonical ownership is validated.
  6. Authority domains are checked.
  7. Temporal requirements are checked.
  8. Allowed inference rules run separately and attach confidence scores.
  9. Orphan and degree-anomaly checks run.
  10. JSON, JSON-LD, CSV, GraphML, Mermaid summaries, and the public explorer dataset are generated.
  11. Sitemap and LLM discovery artifacts are reconciled.
  12. Only then is the graph published.

Validation rules

Build failures include:

  • duplicate stable entity IDs;
  • multiple canonical owners for the same concept;
  • missing edge targets;
  • self-canonical redirects;
  • canonical resources returning redirects or errors;
  • public internal-action nodes;
  • volatile edges without required provenance;
  • authority labels pointing to unapproved domains;
  • graph registry revision different from the content registry revision.

Warnings can include zero-degree strategic hubs, unusually high node degree, generic edges where a more specific type exists, and concepts lacking a canonical guide without an explicit no-guide-needed reason.

Freshness model

The graph makes freshness measurable rather than claiming it cannot drift. Each public build exposes:

  • graph build timestamp;
  • source registry build timestamp;
  • source registry revision;
  • source registry hash;
  • node and edge totals;
  • coverage exceptions;
  • validation status.

If a content deployment and graph deployment are atomic, revision parity should be exact. If infrastructure requires a short delay, the public explorer shows "update pending" until parity is restored.

Accessibility

The graph export and public explorer are designed from the structured text outward. A person using a screen reader should be able to search for an entity, hear its definition, move through grouped relationships, and follow standard links.

The visualization is an enhancement, not the only representation of the data. The text-based representation is the primary layer.

Change management

Ontology changes deserve the same care as route changes. Adding a new relationship type or merging two entity classes can affect thousands of edges. Changes should be versioned, reviewed, tested against a graph fixture, and documented.

The best graph methodology is conservative about identity and explicit about uncertainty. It should make it difficult to publish a wrong relationship accidentally and easy to trace why a correct relationship exists.

Frequently asked questions

What is the purpose of Swoopr's knowledge graph?

The knowledge graph gives every important concept a stable identity, separates a concept from the pages about it, identifies one canonical educational owner where needed, expresses prerequisite and comparison relationships explicitly, carries freshness and provenance for facts that change, and makes graph integrity testable in CI.

Why use stable entity IDs instead of page URLs?

A stable ID survives title and URL changes. If a guide moves from one URL to another, the concept ID does not change. If a glossary definition and long-form guide coexist, they share the concept ID while retaining distinct resource IDs. This is essential for redirects and migrations.

What is the difference between observed and inferred relationships?

OBSERVED means explicit structured metadata, a verified public relationship, or a primary source. INFERRED means the relationship was derived from controlled rules and remains a candidate or confidence-scored edge. The public graph displays observed relationships; inferred relationships may be shown but the UI must distinguish them.

What causes a graph build to fail validation?

Build failures include: duplicate stable entity IDs, multiple canonical owners for the same concept, missing edge targets, self-canonical redirects, canonical resources returning errors, public internal-action nodes, volatile edges without required provenance, and authority labels pointing to unapproved domains.

How does the graph handle facts that change over time?

Any edge whose truth can change must carry review metadata. For example, a constituent relationship should have an effective date and source snapshot. A tax limit should carry a tax year and jurisdiction. A graph that omits time can be syntactically correct while semantically wrong.