---
id: 10031
title: JSONL Schema & Concept Seed Extraction
state: CLOSED
labels:
  - enhancement
  - ai
  - architecture
assignees:
  - tobiu
createdAt: '2026-04-15T21:56:33Z'
updatedAt: '2026-04-17T08:21:29Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10031'
author: tobiu
commentsCount: 0
parentIssue: 10030
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking:
  - '[x] 10032 ConceptService & Source Code Wiring'
closedAt: '2026-04-17T07:35:03Z'
---
# JSONL Schema & Concept Seed Extraction

## Objective
Define the JSONL schema for concept nodes and edges, and populate the initial concept graph by extracting from existing curated sources.

## Context
Phase 1, Step 1 of the Concept Ontology epic (#10030). The concept graph starts as standalone JSONL files — no database dependency.

## Deliverables

### 1. JSONL Schema Definition
Create `nodes.jsonl` and `edges.jsonl` at `.neo-ai-data/concepts/`:

**Node schema** (one concept per line):
```jsonl
{"id":"multi-threading","name":"Multi-Threading Architecture","tier":1,"description":"...","uniqueToNeo":true,"tags":["architecture","workers"]}
```

**Edge schema** (one relationship per line):
```jsonl
{"source":"two-tier-reactivity","target":"push-reactivity","type":"PARENT_CONCEPT"}
{"source":"push-reactivity","target":"file-src/core/Config.mjs","type":"IMPLEMENTED_BY"}
```

**Edge types**: `PARENT_CONCEPT`, `IMPLEMENTED_BY`, `EXPLAINED_BY`, `EXEMPLIFIED_BY`, `REQUIRES`

### 2. Gitignore Exception
Add negation rule to `.gitignore`:
```
!.neo-ai-data/concepts/
```

### 3. Concept Extraction Sources
- **Primary**: `learn/tree.json` (filtered — skip DevIndex, Tutorials, JavaScript basics, Comparisons)
- **Secondary**: `learn/benefits/ArchitectureOverview.md` headings → Tier 1 concepts
- **Tertiary**: Human curation pass to validate Teaching Test filter

### 4. README.md
Schema documentation and contribution guide at `.neo-ai-data/concepts/README.md`.

## The Teaching Test (Filter)
A concept is included if:
1. A developer needs to understand it to USE Neo.mjs productively
2. It cannot be learned by simply reading one API doc page
3. It answers "how" or "why" questions, not just "what"

## Expected Output
~80-100 CONCEPT nodes with hierarchy, ~200 PARENT_CONCEPT edges, concept descriptions from existing docs.

## Acceptance Criteria
- [ ] `nodes.jsonl` and `edges.jsonl` exist and are valid JSONL
- [ ] `.gitignore` negation rule works (files tracked by git)
- [ ] Concepts pass the Teaching Test
- [ ] README documents the schema

Origin Session ID: 496c0120-29aa-4b02-a804-d5a32ff6b5eb

## Timeline

- 2026-04-15T21:56:35Z @tobiu added the `enhancement` label
- 2026-04-15T21:56:35Z @tobiu added the `ai` label
- 2026-04-15T21:56:35Z @tobiu added the `architecture` label
- 2026-04-15T21:56:55Z @tobiu cross-referenced by #10032
- 2026-04-15T21:57:46Z @tobiu cross-referenced by #10035
- 2026-04-15T21:58:13Z @tobiu added parent issue #10030
- 2026-04-15T21:58:30Z @tobiu marked this issue as blocking #10032
- 2026-04-17T07:26:49Z @tobiu referenced in commit `00a06d5` - "feat: add concept ontology JSONL schema and initial 59-concept seed (#10031)

- Create .neo-ai-data/concepts/nodes.jsonl with 59 concepts across 4 tiers
- Create .neo-ai-data/concepts/edges.jsonl with 169 typed relationships
  (53 PARENT_CONCEPT, 14 REQUIRES, 58 EXPLAINED_BY, 44 IMPLEMENTED_BY)
- Add learn/agentos/ConceptOntology.md guide with schema docs, Teaching Test,
  tiering system, and integration architecture diagram
- Register guide in learn/tree.json under Agent OS section
- Fix .gitignore to track .neo-ai-data/concepts/ while ignoring parent dir"
- 2026-04-17T07:27:26Z @tobiu cross-referenced by PR #10047
- 2026-04-17T07:35:04Z @tobiu referenced in commit `593c918` - "feat: add concept ontology JSONL schema and initial 59-concept seed (#10031) (#10047)

- Create .neo-ai-data/concepts/nodes.jsonl with 59 concepts across 4 tiers
- Create .neo-ai-data/concepts/edges.jsonl with 169 typed relationships
  (53 PARENT_CONCEPT, 14 REQUIRES, 58 EXPLAINED_BY, 44 IMPLEMENTED_BY)
- Add learn/agentos/ConceptOntology.md guide with schema docs, Teaching Test,
  tiering system, and integration architecture diagram
- Register guide in learn/tree.json under Agent OS section
- Fix .gitignore to track .neo-ai-data/concepts/ while ignoring parent dir"
- 2026-04-17T07:35:04Z @tobiu closed this issue
- 2026-04-17T07:39:50Z @tobiu referenced in commit `a444940` - "chore: convert ASCII art diagrams to mermaid in ConceptOntology guide (#10031)"
- 2026-04-17T08:21:29Z @tobiu assigned to @tobiu
- 2026-04-17T13:44:36Z @tobiu cross-referenced by #10050
- 2026-04-19T10:20:30Z @tobiu cross-referenced by PR #10084
- 2026-04-19T10:33:36Z @tobiu cross-referenced by #10030

