Skip to content

Zio.ontology()

Create an ontology and populate it with data. Both actions belong to this bundle—creating the paper is the first part, inserting values into that paper is the second.

TBox and ABox — two terms in this manual

Section titled “TBox and ABox — two terms in this manual”
  • TBox (ontology) — what can exist: node types · relationships · attributes. Handled with Zio.ontology().
  • ABox (knowledge graph) — what actually exists: individual nodes · edges · values. Handled with Zio.node().

Changing the ontology does not rewrite already built knowledge graphs (no retroactive application). twin_id is an ID for a single TBox. The point in time of that TBox is marked by version_tag (v1… current version).

The ontology records which attributes belong to which nodes and what connects to what. It is the paper drawn in the web Ontology Schema Editor. When writing skills in an IDE there is no screen, so create it here and confirm later on the web.

Five ways to read an ontology — “Analyze for me” covers all five

Section titled “Five ways to read an ontology — “Analyze for me” covers all five”

An ontology is not just design (nodes · edges). The web ontology view also consists of these five parts. When a stakeholder says “Analyze for me”, “Summarize for me”, “Status”, “How far have we come?” look at all five and speak about them — a single call to Zio.ontology(twin_id).overview() gives you everything. If an existing skill only reads the design, do not use that skill; instead call overview().

Aspect Detailed read What to say
Goal goal() · questions() “Possible n / Goal m”, what is lacking for unresolved items, readiness per KR, KPI disconnected
Version versions() · diff() v1 → … → current version, one line per version and changes
Minutes decisions() · decision(uuid) What was decided and why in each session, any AI suggestions
Design info() Nodes · edges · attributes, warnings (missing key · missing source)
Check check() Isolated nodes, number of questions to re‑evaluate

If nothing is pointed out, do not create—ask instead — the same for all handles

Section titled “If nothing is pointed out, do not create—ask instead — the same for all handles”

First read what the stakeholder points at—nodes · attributes · relationships · expected questions · KR · minutes—using (info() · questions() · Zio.kpi.list() · decisions()). If something is missing or there are multiple, do not create a new one; ask and stop.

  • “Create a relationship between A and B” but both are missing → “A and B do not exist yet. Shall we create them first?” (If the item was postponed in minutes, mention that as well)
  • “Remove question ○○” but such a question does not exist → “It does not exist yet. Should we add it and move it outside the scope?”
  • “Delete KR X” but there are two with the same name → show both and ask which one.

When you create something, do so at that moment, and do not fabricate attributes or source that are missing—leave them blank and state what was left empty. Record everything in the results (newly created items, associated minutes · KPI · dictionary lines) — to prevent unknowns from arising.

This is the place where a person describes their workflow in natural language, and it is converted into an ontology. The SDK fills in coordinates, colors, and internal identifiers—just write the meaning.

from zio_ontology import Zio
got = Zio.ontology.create(
title="업무관리",
nodes=[
{"name": "Worklog", "title": "업무일지", "display_property": "subject",
"properties": [
{"name": "worklog_id", "title": "일지ID", "unique": True, "source": "@worklog_id"},
{"name": "subject", "title": "제목", "source": "@subject"},
]},
{"name": "Work", "title": "작업",
"properties": [
{"name": "work_name", "title": "작업명", "unique": True, "source": "@works.name"},
]},
],
edges=[{"source": "Worklog", "target": "Work", "rel": "HAS_WORK", "label": "일지의 작업"}],
)
tid = got["twin_id"]
for w in got["warnings"]:
print(w) # 오류가 안 나서 놓치기 쉬운 것들. 담당자에게 그대로 옮기십시오
Method Description
Zio.ontology.create(title, nodes, edges) Creates a new ontology and returns its twin_id (the ID of one ontology (TBox) – it stays the same even if the version changes). You may omit nodes and edges, or add them later individually.
Zio.ontology.list() List of ontologies: {twin_id, title, description, status, node_count, edge_count, current_version, updated_at} – current_version is the last saved version (or None if never saved), updated_at is the time it was last edited (same as the web list tile).
↓ From here on are operations that pick up a single ontology — you prefix with Zio.ontology(twin_id) before the dot. They are not called directly like list() or create(). See the section “Build an Ontology” below for how to use them.
Zio.ontology(twin_id).overview() First step when analyzing or summarizing — all five categories at once: {title, description, status, current_version, updated_at, design: {nodes, edges, warnings, unmapped, isolated}, versions: {current_note, list}, decisions: [{title, meeting_date, made, has_proposal}], goal: {total, target, ok, gap, todo, out, ratio, krs, by_version}, check: {to_judge, skipped}}. “Possible n / Target m” is goal.ok / goal.target.
Zio.ontology(twin_id).info() Reads the entire ontology: {twin_id, title, nodes[], edges[], warnings[]}.
.update(title, description, status) Changes the ontology’s label.
.drop() Deletes the ontology. Existing Neo4j nodes (the knowledge graph) are untouched — the ontology is just a reference sheet, so even if there are hundreds of thousands of nodes you can delete the sheet. The state before deletion remains in the version list as dropped‑… – see the “Version” box below.
.new_version(decision=None, note=None, next_note=None) Closes this round as a version and opens a new one — same meaning as “Save as a new version” on the web UI. The current state becomes version v_n (starting with v1). The meeting notes for the current state are moved to that version. note is a single line for that version (v_n) – e.g., new_version(note="○○"). next_note is a single line for the newly opened current state (the next thing to do — leave blank if unknown). decision (the UUID of the meeting notes being written) creates the new current state as part of that meeting. You call it twice: ① after reflection and inspection when closing the round, ② before reflecting a new meeting with new_version(decision=새회의록) – you must open the hand to save changes immediately; otherwise the meeting’s changes won’t be captured in the new round. If there is no change after the last version, no new version is created. {twin_id, version_tag, opened, current_version, note, decision}. The old snapshot() has been removed (it had a different meaning on the web).
.set_note(note, version=None) Edits a single line – like the title line in the web timeline. If version is omitted it edits the current state; if provided it edits that specific version (v1, v2, …). It’s just one text field; the shape and changed count stay the same. An empty string deletes the line. Use this when correcting an existing line (typo, later addition) – adding a line during a new round is done with new_version(note=…).
.versions(limit=50, before_id=None) List of versions. The top entry is the most recently saved one. {twin_id, versions: [{id, version_tag, comment, diff_summary, created_by, author_note, created_at}]} – no snapshot body. The next page uses the last line’s id as before_id.
.version(tag) Reads a single version in full (including schema_snapshot). Read‑only.
.diff(from_tag=None, to_tag=None) Difference of meanings between two versions. If one side is omitted it compares with the current state. {twin_id, from, to, sizes, diff: {nodes, edges, properties, counts, …}} – sizes are total sizes (node · relationship · property count; don’t count manually). nodes, edges, properties list names of added/changed/dropped items (e.g., node Symptom, edge Symptom-[HAS_STEP]->Step, property Symptom.severity).
.record_decision(title, rationale, meeting_date=None, attendees=None, notes=None, author_note=None) Creates a new set of meeting notes – in progress (not yet attached to any line). If rationale is empty it rejects. notes is the raw markdown text of the meeting notes (not a path). If there’s already an in‑progress meeting note it rejects (you must edit that one instead).
.update_decision(decision, title=None, rationale=None, …, notes=None) Edits only the provided fields of a meeting note. It can be edited after being attached to a line; the version stays unchanged.
.decisions(open=False, limit=50, before_id=None) List of meeting notes (most recent first, no raw text). If open=True it returns only the in‑progress one (there is at most one). made is the line that created that note (v1, v2, … or “current state”; if in progress it’s None).
.decision(uuid) A single meeting note – raw markdown (meeting_notes_markdown), the line it was made on (made), and the elements changed from the previous version (target_elements).
.bind_decision(uuid, version=None) Binds a meeting note that has no line to a later line – “oh, I forgot to leave a meeting note for the first version”. version is the target version (v1, v2, …); if omitted it’s the current state. If the line already has a meeting note it rejects. No unbinding handle exists.
.add_node(name, title, properties=[], display_property=None) Adds a node. display_property is the name shown inside the circle in the graph and you give one property name. Names starting with _ are reference nodes pointing to nodes in other ontologies; they only carry the key (PK) – see the box below.
.update_node(name, title, description, display_property) Edits a node’s label. You cannot change name – changing it won’t affect existing nodes labeled with that name (the ontology does not retroactively apply to past data). There is no rename handle; if you really need to rename you must create a new node and delete the old one, then decide what to do with the old label’s nodes.
.drop_node(name) Deletes a node. Also deletes all attached edges and returns how many were removed. Leaving orphaned edges would break the web UI.
.add_property(node, name, title, type, unique, required, source) Adds a property slot. Read the two boxes below for unique and source. type is one of string, integer, float, boolean, datetime, date, time, json; if omitted it defaults to string. The same format applies to the properties=[…] argument in .add_node(properties=[…]) ({"name", "type", "unique", …}).
.update_property(node, name, ...) Edits only the provided fields; others stay unchanged.
.drop_property(node, name) Removes a property. If it was display_property, that slot is cleared too – the graph shows an empty circle for the removed property.
.add_edge(source, target, rel, label, source_key, target_key) Connects two nodes. rel is the actual Neo4j relationship name – e.g., WRITTEN_BY in (Worklog)-[:WRITTEN_BY]->(Author). label is a screen‑only description. source_key, target_key specify which properties to join on (can be multiple). Edges only define relationships; they have no property slots.
.drop_edge(source, target, rel=None) If rel is omitted it deletes all edges between the two nodes.

Versions — editing does not automatically create a new one

Section titled “Versions — editing does not automatically create a new one”

There is always just one “current state” (the ontology itself). Versions are only historical snapshots – logs. Collection agents and graph views do not read versions. Lines are v1, v2, … and the topmost “current state”.

Because an ontology is source code, editing does not stack a new version automatically. Before reflecting a new business meeting you open a round with new_version(decision=…); after reflection and inspection you close it with new_version(note=…). It’s like a Git commit – the name (v1, v2) has no meaning; reading involves just one line and the meeting notes. What is saved on the web and via SDK ends up in one list (the web “Version Management” timeline).

  1. Open before editing. If you edit directly, the previous state isn’t kept – a rollback base must be created manually.
  2. Comparison only looks at meaning. Coordinates and colors are ignored – moving a node is not a difference. Edges are compared as (source)-[rel]->(target); changing rel shows up as “one missing + one added” because it’s a different relationship in Neo4j.
  3. Past versions are read‑only. There is no way to edit them (like Git history). To revert to an old shape you open that version on the web and click “Restore this version”; before restoring, the current state is recorded in the version history so the history only grows forward, never backward. The SDK has no restore handle.
  4. Neo4j does not follow. Even if you go back to an old version, nodes that were already created remain; the ontology does not retroactively apply.
o = Zio.ontology(twin_id)
# 1. 고치기 전에 — 지금까지의 모양을 버전으로 닫는다 (처음이면 v1, note 는 그 버전의 한 줄)
o.new_version(note="1차 — 장애 대응 절차")
# 2. 고친다 — 고친 모양이 운영 중인 「현재판」이다
o.add_node("ProcedureStep", "작업세부단계", properties=[
{"name": "step_id", "unique": True, "source": "@step_id"}])
o.add_edge("Procedure", "ProcedureStep", "HAS_STEP")
# 3. 무엇이 바뀌었나 — 기록한 버전 ↔ 현재판
d = o.diff("v1")["diff"]
print(d["counts"]) # {'added_nodes': 1, 'added_edges': 1, ...}
print(d["nodes"]["added"]) # ['ProcedureStep']
# 이번 회차를 닫는다 — 이 모양이 v2, 한 줄은 이번에 한 일
o.new_version(note="작업세부단계 신설")

Meeting Notes — one round = one meeting note = one version

Section titled “Meeting Notes — one round = one meeting note = one version”

The ontology grows by repeating: business meeting → meeting notes → design reflection. One cycle is a “round” and appears as one line in the web “Version Management” timeline: the version created by that meeting (v1, v2, …, current state), the meeting notes (why), AI suggestions, target KPIs, and what changed from the previous version. The first version may have a meeting that created it – you can bind it later with bind_decision. Meeting notes are logs like versions – the runtime does not read them.

  1. Meeting notes attach to the line they were made on — lines are “v1, v2 …, current state” and each line has one meeting note.
  2. After a meeting you write notes → “in progress” (one per ontology). If you call new_version(decision=…) before editing, the current state is recorded as a version and that meeting’s notes are moved to that version; this meeting becomes the meeting of the new current state. The web does the same when you click “Save as a new version”.
  3. You can bind a meeting note later (bind_decision, the web “Write Meeting Notes” on the timeline) – it can even be for the first version.
  4. If there are no meeting notes, you edit the existing one instead of writing another (update_decision). The version stays unchanged.
  5. There is no delete handle. Meeting notes outlive the ontology – they remain even if the ontology is deleted.
o = Zio.ontology(twin_id)
# 1. 미팅이 끝나면 회의록을 쓴다 — 쓰는 중 (원문은 글 그대로, 시각은 한국 시각)
d = o.record_decision(
title="긴급 장애 대응 절차 세분화", meeting_date="2026-10-14 16:30",
attendees=["고객지원팀 김책임", "인프라팀 박선임"],
rationale="점검 없이 재기동해 2차 피해가 났다. 조치 전에 점검 스텝을 둔다.",
notes=open("meeting_20261014.md").read())
# 2. 고치기 전에 회차를 연다 — 지금 모양은 버전으로 닫히고, 이 회의록이 새 현재판의 회의
o.new_version(decision=d["uuid"])
# 3. 회의록대로 온톨로지를 고친다 — 이 회의가 만드는 새 현재판
o.add_node("ProcedureStep", "작업세부단계", properties=[
{"name": "step_id", "unique": True, "source": "@step_id"}])
# 이 회의로 바뀐 것 (마지막 버전 → 현재판)
o.decision(d["uuid"])["target_elements"]
# 빠뜨린 참석자는 그 회의록을 고친다 (버전은 그대로)
o.update_decision(d["uuid"], attendees=["고객지원팀 김책임", "인프라팀 박선임", "품질팀 이대리"])
# 첫 버전을 만든 회의를 나중에라도 남긴다
d0 = o.record_decision(title="첫 설계 인터뷰", rationale="현업 1차 인터뷰로 첫 설계를 세웠다.")
o.bind_decision(d0["uuid"], version="v1")

The expected questions are the goal of an ontology. Write down what the business wants to ask about in plain language, then judge whether this design can answer it. “Possible n / Target m” is the banner on the web “Goal” screen; as versions accumulate, n should increase. Questions connect to KPIs (KR) – KPIs belong to instances, not ontologies, and live in Zio.kpi (see the table below).

  1. Human‑defined — question text, connected KPI, resulting meeting notes, out of scope (the ontology does not answer that question).
  2. AI‑filled — judgment (possible / unresolved), basis, answering path, solving Cypher, nodes touched (judge). Within one round you can re‑judge to overwrite (like a compile result).
  3. Status values — todo unreviewed, ok possible, gap unresolved, out out of scope. Out of scope is excluded from the goal denominator; AI does not judge it – only when a person says so do you set and resolve it. When telling the owner use the screen names exactly (unreviewed · possible · unresolved · out of scope) – don’t change to “deficiency” or similar. The link between question and KR is also shown as “connected KPI · KPI not connected”.
  4. Changing a question text clears the judgment — it becomes a different question.
  5. KPIs only connect if they match. A single question usually has one KR – if you try to link multiple, explain why. Do not link KPIs that look similar but differ in period or unit (e.g., “How many cases per month?” vs. “Cases per day”); they are different indicators. If none matches leave it empty (“KPI not connected”) – that’s a cleanup item.
  6. If the pointed question · KR is missing or multiple, ask — see the box at the very front: “if nothing is pointed, do not create and ask”.
  7. Target KPIs (target_kpis) are only set when you say so – when a person says “this round targets ○○”. Do not automatically attach target KPIs to a meeting note just because the question links to a KR.
  8. After moving past a version the judgment on the current state becomes fixed like “judged in v2”; check() will re‑judge those questions.
Method (Ontology — Zio.ontology(twin_id)) Description
.questions(status=None, touches=None, kr=None) List of expected questions: [{id, question, judgment: {status, basis, path, checked_version, decision_uuid}, kr_uuids, cypher_query, touches}]. If touches="Part" it lists only questions that touch that node (“If I delete Part, which questions are affected?”). If kr="-" it returns only those with no connected KPI.
.add_question(question, kr=None, decision=None) Adds a question – starts as unreviewed. kr is the UUID of a connected KR (one or a list from Zio.kpi.list()); if there’s no matching KR do not force a link (“KPI not connected”). Duplicate text is rejected.
.update_question(id, question=None, kr=None, decision=None) Edits only the provided fields. kr replaces the current list ([] removes all). Setting decision="" clears the meeting note.
.exclude_question(id, reason) · .include_question(id) Marks a question as out of scope and resolves it (it becomes unreviewed). Deletion does not happen – it stays with a reason for “why not”. If reason is empty it rejects. Decide whether “remove” means out of scope or deletion.
.drop_question(id) Deletes a question (and its KPI link).
.goal(by_version=False) {total, target, ok, gap, todo, out, ratio, unlinked, krs: [{kr_uuid, name, objective, ok, target}]} – the banner on the web goal screen and KR card numbers. If by_version=True it adds by_version: [{version, saves, goal_counts}] (points in the “Goal by Version” graph; records before a version are None; current state always shows current judgments; saves is how many times that version was saved – mention this too).
.check() First step of inspection: {nodes, edges, warnings, unmapped, isolated, to_judge, skipped}. unmapped are node types before mapping (not a warning). isolated are nodes not touched by any edge; to_judge are questions to judge (unreviewed · previously judged); skipped are out of scope.
.judge(id, status, basis, path=None, cypher=None, touches=None) AI judgment – status is only "ok" or "gap". If basis is empty it rejects. For ok, provide the answer path and solving Cypher (the ontology’s labels · relationships as they are). For gap, describe what is missing. Out‑of‑scope questions are rejected. Do not use an ok without a basis. The returned value’s cypher_warnings lists any labels, relationship types, or properties used in the Cypher that do not exist in the ontology – if non‑empty the judgment has no basis, so either fix the Cypher or mark it as "gap".
.propose(decision, markdown) Writes the AI proposal for that meeting note – replaces everything (overwrites). The web only shows it. The proposal is a text; adding nodes/edges is done separately with add_node, etc. The meeting note’s raw text stays untouched. The structure of the proposal: ## Summary · ## Node · Property Proposal (basis) · ## Connection Proposal · ## Relationship to Expected Questions · ## Open Questions · ## Words for the Synonym Dictionary. One meeting note has one proposal and it overwrites everything – if you want a different story (e.g., an unresolved supplement) keep the first section and append a new section. If you only heard “give me a proposal” answer in conversation; record when asked to “record it”. “Apply the proposal” only changes nodes · properties · relationships – adding words to the synonym dictionary (Zio.glossary.add) and target KPIs (target_kpis) are done separately by a person. If you did both, note it in the result.
.target_kpis(decision, kr) The target KPIs for that round (meeting note) – the web “Target KPIs” in version management. It matches the list exactly ([] removes all). The returned added · removed are added to or removed from the result – if there is a removed, it means something was taken away, so include that in the outcome. update_question(kr=…) returns the same kind of change as kr_changes.
t = Zio.ontology(twin_id)
kr = Zio.kpi.list()[0]["results"][0]["uuid"] # 연결할 KR — 인스턴스의 KPI 에서 고른다
q = t.add_question("지난달 처리가 늦어진 건은 몇 건이고, 무엇 때문인가?", kr=kr, decision=d["uuid"])
t.exclude_question(q2_id, reason="외부 시스템이 맡는 일(2차 회의)") # 사람이 「범위 밖」이라 했을 때만
# 검사 — 구조 점검을 보고, 판정할 질문마다 그래프로 답하는 길을 짚는다
c = t.check()
print(c["warnings"], c["isolated"])
for x in c["to_judge"]:
t.judge(x["id"], "gap", basis="Part 에 재주문 기준 수량이 없습니다", touches=["Part"])
t.goal() # {'total': 12, 'target': 11, 'ok': 7, ...} — 웹 목표 화면의 「7/11」
Method (Instance — Zio.kpi · Zio.glossary) Description
Zio.kpi.list() One KR per O – [{uuid, title, results: [{uuid, name, unit, current, target, direction, improvement}]}]. The numbers are agreed with the business – only current · target exist; there is no actual performance field. Check first to avoid duplicating an O.
Zio.kpi.links(kr=None) Items connected to that KR – which ontology’s question (including judgment) and which round targets it. If omitted, returns all instances.
Zio.kpi.add_objective(title) · update_objective(o, title) · drop_objective(o) Objectives (O). You can pass back the returned dict unchanged. O’s that still have KRs are not deleted. add_objective · add_result return a similar field (name‑similar O · KR, [{uuid, name, objective, score}]) – do not block it. If not empty ask the person “is this the same as an existing ○○?” (e.g., “Inventory Check Runtime” ↔ “Inventory check runtime”). If they are the same, delete the newly created one and keep the old.
Zio.kpi.add_result(o, name, current, target, unit=None, direction="down") A KR (indicator) – e.g., “Inventory Check Runtime 12 h → 2 h”. direction is "down" (lower is better) or "up" (higher is better) – understand from the wording (decrease → down, increase → up). The server calculates improvement; negative means the direction was wrong.
Zio.kpi.update_result(kr, name=, current=, target=, unit=, direction=, objective=) · drop_result(kr) Edits only the provided fields. If you delete a KR, its connected questions stay but become “KPI not connected”.
Zio.glossary.list(q=None) Synonym dictionary – {entries: [{uuid, name, aliases, meaning}], more}. Read before designing – node names follow the dictionary’s names.
Zio.glossary.add(name, aliases=None, meaning=None) Adds to the dictionary. The dictionary name is case‑insensitive and unique – if it already exists you add only synonyms (merged: True). If added_aliases is empty there was nothing changed – say “already in the dictionary” and do not claim “I added it”. Changing a meaning is done with update(meaning=…); return the previous meaning as meaning_before.
Zio.glossary.update(name, new_name=, aliases=, remove_aliases=, meaning=) · drop(name) Edit or delete by dictionary name (or uuid). aliases only adds (existing synonyms stay); to remove you must specify remove_aliases=["word", …]. Do not silently delete others’ synonyms; deletion is separate. Return the result’s added_aliases · removed_aliases. If a word already exists, adding it ends with add alone (merged: True).
o = Zio.kpi.add_objective("현황 파악을 하루 단위에서 실시간으로")
Zio.kpi.add_result(o, "월말 집계 소요 시간", current=12, target=2, unit="시간", direction="down") # 개선율 83%
Zio.glossary.add("Supplier", aliases=["공급처", "거래처"], meaning="물품을 대 주는 곳")

Underscore (_) — shortcut to reference nodes in other ontologies

Section titled “Underscore (_) — shortcut to reference nodes in other ontologies”

When you need to connect to a node that already exists in another ontology (e.g., common Author, Project), you do not redefine it here; instead prefix the name with _. This is how the ontology shows “this node connects to that node” on the screen. Just follow these two rules.

  1. Prefix the node name with _ (_Author, _Project).
  2. Only list the key (PK) for properties – you only need the key to match; other fields are meaningless, so keep just one or two keys for readability.

When do you use _? If this ontology owns the node’s value (it fills it via collection) you use a normal node. If another ontology already owns it and you only need to connect, use _. You don’t have to look up whether it exists in another ontology – there is no guarantee that the same name means the same node; the criterion is “am I the owner?”.

“You can create it in an ontology but it won’t exist in Neo4j” is the key. When you save, _ is stripped and the node becomes a normal node with the same label (_Project → graph Project) via MERGE. It’s not redefinition; it’s reference, so you bring only the key and do not overwrite the title · membership · display name. Therefore no new insert/update occurs for _‑prefixed nodes.

Zio.ontology.create(title="WBS", nodes=[
{"name": "Worklog", "properties": [
{"name": "worklog_id", "unique": True, "source": "@id"}]},
{"name": "_Project", "properties": [ # 다른 온톨로지 노드 참조 (열쇠만)
{"name": "project_code", "unique": True, "source": "@project_code"}]},
], edges=[{"source": "Worklog", "target": "_Project", "rel": "BELONGS_TO"}])

add_node · create let you make it directly in the SDK – no need to go back to the web and edit. If you give a reference node’s key a source, collection data will automatically fill it; if you supply a value directly, use .save() with _Project and only the key.

unique — key that distinguishes the same node

Section titled “unique — key that distinguishes the same node”

The most important field among properties. It tells whether the node already exists or is new.

Number of unique keys What happens
0 Every time you run it, a new node is created (CREATE, not MERGE). Errors don’t occur until weeks later when you notice.
1 It merges on that value; if present it stays, otherwise it creates.
2 or more The values are joined with _ to form the key. If any field is empty, that node is not created at all.

If a chosen key’s value is empty, that single node is skipped – this prevents ghost nodes without keys.

If omitted the property stays empty. No error; the node is created with that field missing.

What you write Meaning
@issues.title The title inside the collection data’s issues.
@worklog_id The worklog_id in the collection data.
Just a string That literal becomes the value (a constant).

If the path after @ starts with an array, each element gets its own node – e.g., if issues has three items, you get three nodes. This is the only way to expand an array into multiple nodes.

Only write a path when you know the actual collection field. Look at Zio.ingestion.schemas()’s columns (or fetch one record with Zio.ingestion(name).fetch()) to decide. If you’re still designing and there’s no data yet, leave it blank – such node types will appear in info() · check() · overview() under unmapped (not a warning). They are normal during design; they become a list of things to map later. Don’t create fake paths like @customer_name just to get rid of warnings – the values will never come in, and nobody will notice.

Node properties sit flat with system fields; if they overlap, the system wins silently. The SDK blocks this.

Name Overlap causes
id · source · target · labels Graph uses them as identifiers – edges won’t be drawn
title · twin_id System overwrites on save
x·y·z·vx·vy·vz·fx·fy·fz·index·color Graph display is overwritten
Starting with _ Reserved for system (_display)
name Not blocked, but if used the automatic display name becomes that value

You build the ontology by holding it in your hands and drawing as you wish. Nodes and edges are defined by the ontology. Skills only pass values — they do not write any line about which edge goes in which direction.

Zio.node().merge() creates a single node. Edges must be added directly with merge_relation(). When nodes grow into dozens or form a tree, industry specialists may draw an ontology and then draw the same diagram again in Python. This bundle takes over that task.

Method Description
Zio.ontology(twin_id, entry_node=None) Retrieves one ontology. twin_id is the id of a single ontology (TBox), and it is stored as the twin_id attribute on nodes. entry_node is the root node name; it is only needed for writing.
.save(data) Creates nodes and edges exactly as drawn in the ontology. data is {node_name: [instances, …]}.

The two arguments are similar to the agent’s “ontology node connection.” The two fields where you choose an ontology and a starting node in the agent builder become arguments here.

# 에이전트가 부르는 모양 (수집 경로 — 값을 온톨로지의 @경로가 끌어온다)
execute_ontology_entry("lAOZtMeH", "Worklog", state)
# 스킬이 부르는 모양 (값을 직접 준다)
Zio.ontology("tNpBkLim", "WbsItem").save({
"WbsItem": [
{"project_code": "PRJ-0071", "item_name": "GS25 8월 정기점검",
"status": "진행중", "progress_pct": 62,
"parent_item_name": "GS25 정기점검 3Q"},
{"project_code": "PRJ-0071", "item_name": "GS25 정기점검 3Q",
"status": "진행중"},
],
"_Project": [{"project_code": "PRJ-0071"}],
"_Work": [{"worklog_id": "weekly_sjlee1_2026_32", "work_name": "8월 정기점검"}],
})

With this one call, two WbsItems are created, and the edges REPORT_ON, BELONGS_TO, and HAS_SUBTASK are added together. There is no edge code.

Item Rule
Node name Use exactly as written in the ontology. Keep any underscore prefixes (_Project). The SDK strips labels — the graph receives Project. Names not present in the ontology are quietly ignored.
Instance If it is a list, each element becomes one node. A single dict is also accepted. Attribute names must match those defined in the ontology.
Do not include name, _display, title, twin_id — the SDK attaches these automatically. Including them will overwrite computed values.

An edge is created only between nodes that were passed in this call. Even if the ontology draws it, if one side was not passed, the edge will not be created.

# _Project 를 안 넘기면
Zio.ontology("tNpBkLim", "WbsItem").save({"WbsItem": [...]})
# → WbsItem 은 선다
# → WbsItem -[BELONGS_TO]-> Project 는 안 선다
# 열쇠만 넘기면 붙는다
"_Project": [{"project_code": "PRJ-0071"}]

Therefore only keys with underscore prefixes are passed as keys. The purpose is to find an existing node and attach to it; the ontology that created the node fills its attributes. Passing only a key means the node’s attributes remain unchanged.

Self-referential edges are paired by the ontology

Section titled “Self-referential edges are paired by the ontology”

Edges that connect the same node, such as in WBS trees or precedence tasks, are paired according to the ontology’s “key mapping.” The skill simply records the parent name as an attribute.

Edge sourceKey targetKey
HAS_SUBTASK project_code, item_name project_code, parent_item_name
PRECEDES project_code, item_name project_code, previous_item_name

If the referenced parent does not yet exist, a placeholder node is created with only its name. When the parent’s value arrives later, it will be filled in. This approach was considered better than breaking the tree.

{
"written": True, # 썼는가
"saved": {"WbsItem": 2, "_Project": 1, "_Work": 1}, # 실제로 세운 수
"skipped": [
{"node": "WbsItem", "index": 3, "reason": "열쇠가 비었습니다"},
],
"message": "Data saved successfully to Neo4j.",
}

saved represents the number of lines written, not the number passed. If they differ, see skipped.

written means whether something was written rather than whether it succeeded. If the root key is empty and nothing was written, that is a judgment, not a failure — the value simply did not arrive, and a follow-up query will be made.

Rule Reason
All or none Nodes and edges are created in one batch. If something goes wrong midway, nothing is written to the graph. There is no half‑written graph.
Do not create if key is empty Prevents orphan nodes that cannot be found. The instance with an empty key is skipped; the rest proceed.
Idempotent on repeated runs If a node is missing, it is created; if it exists, it is updated. Re‑passing the same values does not increase node count.
Only update passed fields For existing nodes, only the fields provided in this call are written. Even if the ontology changes, previously written nodes are not overwritten.
Zio.node().merge() Zio.ontology().save()
What it creates A single node Nodes and edges drawn in the ontology
Edges Added directly with merge_relation() Handled by the ontology
Ontology Not consulted Consulted
When writing Modify a single attribute field; reflect re‑queries Create everything inferred as a whole

The node given as entry_node is the root of this data set. If its key is empty, the entire write operation is aborted — without a root, anything that remains will later be unreachable. That is why WbsItem was chosen as the root in the example above.

(주)지오유 · 경기 용인시 처인구 유림로154번길(유방동 673-2) 20-13

CEO 신달수·Business no. 142-81-36612·E-commerce no. 용인처인-0118호·Privacy officer 신달수·Email shindalsoo@gmail.com·Tel 1833-3623·Fax 02-6918-4006