Read GraphML

Open
  • Is something wrong?
#8 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
typescript, xml
Domain
data

Research direction

Start with packages/formats/src/xml.ts and the RDF/XML parser, then read the JSON field mappings in packages/formats/src/json.ts and format registration in packages/formats/src/index.ts and detect.ts. Add GraphML parsing and registration, then update the CLI, playground, English and Chinese docs, tests and changeset listed in the issue. Done means extension and content detection work and a NetworkX GraphML fixture produces the same hashGraph as its node-link JSON counterpart.

Written by the indexing model from the issue text.

Description

enhancement formats help wanted
Why

GraphML is what NetworkX (nx.write_graphml), igraph, yEd and Gephi write, and what
LightRAG keeps its knowledge graph in
(graph_chunk_entity_relation.graphml). Today kgdiff recognises a GraphML document and stops
with "export it as JSON first"
(detect.ts#L166).
For the GraphRAG users kgdiff is built for, that is one step too many.

What

A graphml format in @kgdiff/formats, mapped with the same conventions as the JSON graph
shapes, so that one graph saved as GraphML and as NetworkX node-link JSON diffs as identical:

  • <node id> → node id. <edge source target> → edge, <edge id> → edge id.
  • <data key> values, typed by their <key attr.name attr.type for> declarations (string,
    int, long, float, double, boolean) with <default> values applied → fields. The
    label, type and predicate then come from the same field names the JSON reader uses
    (LABEL_KEYS, TYPE_KEYS, PREDICATE_KEYS in json.ts#L616-L621);
    everything else becomes attributes. Note that LightRAG's entity_type is not one of the type
    keys today; whether to add it (for JSON too) is worth deciding here.
  • Undirected graphs (edgedefault="undirected"): decide and document a stable endpoint order,
    so that a–b and b–a are the same edge.
  • Out of scope, each with a warning rather than an error: nested <graph>s, <hyperedge>,
    <port>, and yEd's y: drawing extensions (geometry, styles), which are dropped like the
    JSON reader's json-ignored-fields.
Where to start
  • Parse with the SAX-style parseXml that RDF/XML already uses
    (xml.ts#L115):
    no new dependency, external entities never loaded. One option is to turn GraphML into
    node-link records and hand them to the JSON reader's field mapping, which keeps the two in
    step.
  • Register the format: FormatId
    (index.ts#L24),
    a case in parseGraph next to rdfxml
    (index.ts#L239),
    .graphml in FORMAT_EXTENSIONS
    (detect.ts#L10),
    and return 'graphml' from content sniffing instead of throwing.
  • Everywhere formats are listed: the CLI's --format values
    (args.ts#L23)
    and display names
    (inputs.ts#L13),
    the playground
    (datasets.ts#L82),
    docs/formats.md (move GraphML out of "Recognised but not read") and the mapping table in
    docs/architecture.md, in English and Chinese.
  • Tests and fixtures in packages/formats/test/: a small file written by NetworkX and a
    LightRAG-style file with entity_type, description and source_id. The people.* and
    go-mini.* fixtures show how one graph in several syntaxes is checked for equality.
Done when
  • kgdiff a.graphml b.graphml works, with format detection from the extension and the content.
  • The same graph written by NetworkX as GraphML and as node-link JSON gives the same hashGraph.
  • Docs updated in both languages, and a changeset (pnpm changeset).

GEXF follows the same pattern: #9. Comment here before you start, so we don't duplicate work.

Dominant language
TypeScript
Stars
47
Forks
6
Avg merge
2h 32m
Merged PRs (30d)
22

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from iiwish/kgdiff

All issues in iiwish/kgdiff

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.