Export changes as KGCL

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

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
python, typescript
Domain
backend, cli

Research direction

Read packages/core/src/types.ts and formatHunk in packages/core/src/i18n.ts, then compare the exporter and argument handling in packages/cli/src/markdown.ts and packages/cli/src/args.ts. Inspect examples/datasets/ontology-release/ and resolve the listed grammar, unsupported-change, CURIE, and package questions in a comment before coding. Done means the example produces a KGCL snapshot accepted by the reference parser, with CLI docs in English and Chinese and a changeset.

Written by the indexing model from the issue text.

Description

enhancement help wanted
Why

KGCL (Knowledge Graph Change Language) is how the OBO
community writes ontology changes down: rename, obsolete … with replacement, move … from … to …, create synonym, create edge, and so on. Ontology editors and bots already read and
apply it. A KGCL export would let a reviewer go from "here is what changed" in kgdiff to a
change list the OBO tooling understands, and makes kgdiff easier to adopt in ontology
repositories.

What

kgdiff a.obo b.obo --kgcl [file] (CLI) and a toKgcl(result) function (library) that write
one KGCL command per change.

docs/delta-format.md already sketches the mapping
(Relation to other formats).
Hunks carry the semantics KGCL has words for (move, merge, rename); the delta carries the
primitive operations for everything else. Roughly:

kgdiff KGCL
rename (node.set label) rename X from 'old' to 'new'
move hunk move X from P to Q
merge hunk, deprecation with replacedBy obsolete X with replacement Y
alias added / removed create synonym 'a' for X / remove synonym
node.add / node.remove create node X 'label' / delete X
edge.add / edge.remove create edge X R Y / delete edge X R Y

Check every command against the current KGCL grammar; the table is a starting point, not the spec.

Open questions (answer them in a comment before writing code)
  • Changes KGCL cannot express (attribute edits it has no command for, splits): skip with a
    warning, or emit them as comments?
  • Ids: KGCL wants CURIEs. Full IRIs from RDF inputs need compacting (compactIri in
    @kgdiff/formats), with the file's own prefixes.
  • Which package: @kgdiff/core stays format-agnostic and dependency-free, so this probably
    belongs next to the CLI's markdown.ts, or in a small new package.
Where to start
  • Hunk and op types: packages/core/src/types.ts; how hunks are worded: formatHunk in
    packages/core/src/i18n.ts.
  • An exporter with the same shape: packages/cli/src/markdown.ts (--markdown), and how
    options with an optional file argument are parsed: json / delta / markdown in
    packages/cli/src/args.ts.
  • Test data: examples/datasets/ontology-release/ has merges, a split, moves, renames and
    obsoletions.
Done when
  • The ontology-release example exports to KGCL that the reference parser
    (kgcl-schema, Python) accepts, checked once by hand and
    pinned as a golden snapshot in packages/cli/test/__snapshots__/.
  • docs/cli.md documents the option (en + zh), plus a changeset.
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.