#Data schema

The JSON contract between the extraction CLI and the SPA lives in a single file, src/schema.ts. There are exactly two document kinds:

storePath is the universal join key: FileEntry.storePath matches the file strings in each option's declarations and definitions.

#Versioning

Bump EXTRACTOR_VERSION on any schema or extractor change — every cached blob becomes stale at once.

#Type overview

classDiagram
  class Manifest {
    version
    extractor
    outputs OutputNode
    outputNames
    warnings
  }
  class FlakeInfo {
    ref
    path
    rev
    narHash
  }
  class InputInfo {
    name
    nodeKey
    transitive
    storePath
    follows
  }
  class FileEntry {
    id
    relPath
    origin FileOrigin
    storePath
    git
  }
  class ImportEdge {
    from
    to
  }
  class ConfigRef {
    id
    kind
    dataFile
    status
  }
  class GraftInfo {
    output
    input
    added
    inherited
  }
  class ConfigData {
    version
    id
    fileIndex
  }
  class OptionEntry {
    loc
    type
    isDefined
    highestPrio
    customized
    value
  }
  class DeclarationRef {
    file
  }
  class DefinitionRef {
    file
    value
    valueError
  }
  class FileOptionRefs {
    defines
    declares
  }
  Manifest --> FlakeInfo : flake
  Manifest --> "many" InputInfo : inputs
  Manifest --> "many" FileEntry : files
  Manifest --> "many" ImportEdge : importEdges
  Manifest --> "many" ConfigRef : configurations
  Manifest --> "many" GraftInfo : grafts
  ConfigData --> "many" OptionEntry : options
  ConfigData --> "many" FileOptionRefs : fileIndex
  OptionEntry --> "many" DeclarationRef : declarations
  OptionEntry --> "many" DefinitionRef : definitions

OutputNode is a recursive union (attrset | leaf | omitted | unknown) normalized from nix flake show --json; FileOrigin is self | input (optionally patched) | unknown.

#Join keys and the file id codec

• storePath join: DeclarationRef.file / DefinitionRef.file are absolute /nix/store/... paths (or the sentinel below). They join against FileEntry.storePath to attribute options to files.
• File id codec: makeFileId / parseFileId produce and parse "self:<rel>" | "input:<name>:<rel>". Per their JSDoc this format is a client-server protocol, not just a display convention — serve's /data/file/<id> route re-derives input files from the id (re-fetching through Nix when the store path has been GC'd; see CLI reference). Every construction and parse site must go through these helpers. App-internal "unknown:…"/"inline" buckets are opaque; parseFileId returns null for them.
• fileIndex: ConfigData.fileIndex maps storePath → indices into options, split into defines / declares (FileOptionRefs), precomputed so the SPA never scans thousands of options per click.

#Definition priorities

PRIO records the well-known lib.mkOverride values (lower wins):

An option is customized when isDefined && highestPrio !== null && highestPrio < PRIO.optionDefault (see toEntry in src/extract/options.ts) — a real definition beat the declared default. fileIndex.defines only counts customized definitions, because every defaulted option carries a mkOptionDefault definition pointing at its declaring module, which would otherwise make nixpkgs "define" everything.

#Sentinels and grafts

• UNKNOWN_FILE = "<unknown-file>" — the file string the module system uses for inline/anonymous modules; it appears as a fileIndex key and in declaration/definition refs.
• GraftInfo marks a top-level output that extends an input's same-named namespace (e.g. lib = nixpkgs.lib.extend …). The heuristic lives in src/extract/extract.nix: at least 90% of the input's attr names must reappear in the output (and the input must have at least 5 names; outputs consisting only of per-system names never count). The manifest records only the added keys plus an inherited count so the UI can hide the inherited bulk.

#Reference

The full generated API reference is at https://kris.net/flake-explorer/docs/api/ (CI-generated, site only). The source of truth is src/schema.ts.