# inspection-ai/japanese-toxic-dataset architecture

> Architecture diagram of the GitHub repository inspection-ai/japanese-toxic-dataset, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inspection-ai/japanese-toxic-dataset
- Repository: https://github.com/inspection-ai/japanese-toxic-dataset

## Overview

1. **Repository purpose**
   - This is a **research dataset repository**, not an application or service.
   - It packages a **Japanese toxicity labeling schema** and a **sample annotated dataset** used in the paper *“Proposal and Evaluation of Japanese Toxicity Schema.”*

2. **Core artifacts**
   - `schema.md` defines the **annotation taxonomy and labeling rules**.
   - `data/subset.csv` contains the **annotated sentence-level data** following that schema.
   - `README.md` and `README_ja.md` serve as the **entry documentation** in English and Japanese.

3. **Primary architectural boundary**
   - The repo has a clean split between:
     - **Specification layer**: the schema document.
     - **Data layer**: the CSV dataset.
   - There is no runtime backend, model, API, or UI layer.

4. **Annotation model**
   - Each row in `data/subset.csv` represents a **single sentence** with a unique `id`.
   - The dataset encodes two kinds of labels:
     - **Toxicity level**: `Not Toxic`, `Hard to Say`, `Toxic`, `Very Toxic`
     - **Toxicity category**: `category_卑語`, `category_差別`, `category_迷惑行為`, `category_猥褻`, `category_出会い・プライバシー侵害`, `category_違法行為`, `category_偏向表現`

5. **Data schema structure**
   - The CSV is a **multi-label annotation table**: one sentence can have values across multiple toxicity categories.
   - `annotation_num` captures **how many annotators** contributed to the label set, which is important for interpreting agreement and confidence.

6. **Semantics of the labels**
   - The toxicity level columns represent a **severity scale**.
   - The category columns represent **why** a sentence is toxic, separating general severity from specific harmful content types.
   - This makes the dataset suitable for both **classification** and **schema evaluation** tasks.

7. **Documentation flow**
   - `README.md` is the main entry point and points users to the schema and dataset.
   - `schema.md` is the authoritative source for how annotations were defined.
   - `README_ja.md` and `schema_ja.md` mirror the documentation for Japanese readers.

8. **Likely usage pattern**
   - An engineer or researcher would first read the schema, then load `data/subset.csv` for analysis, model training, or evaluation.
   - The repo is designed to support **benchmarking toxicity detection in Japanese** rather than operational deployment.

9. **Technology footprint**
   - The only concrete data format is **CSV**, making the dataset easy to ingest from any language or ML stack.
   - There are no repository-specific build tools, dependencies, or infrastructure components.

10. **What an architecture diagram should show**
   - A documentation/specification node for the schema.
   - A dataset node for the CSV annotations.
   - A linkage from the schema to the dataset, indicating the schema governs the labels in the data.
   - Optional bilingual documentation nodes for English and Japanese access.

Main entry points: [`schema.md`](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/schema.md) (schema.md), [`data/subset.csv`](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/data/subset.csv) (data/subset.csv), [`README.md`](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/README.md) (README.md), [`README_ja.md`](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/README_ja.md) (README_ja.md)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_readme_en["README.md<br/>entry doc<br/>[README.md]"]
  node_readme_ja["README_ja.md<br/>entry doc<br/>[README_ja.md]"]
end

subgraph group_spec["Specification"]
  node_schema_en["schema.md<br/>schema spec<br/>[schema.md]"]
  node_schema_ja["schema_ja.md<br/>schema spec<br/>[schema_ja.md]"]
  node_label_model{{"Label system<br/>annotation model"}}
end

subgraph group_data["Dataset"]
  node_subset_csv[("data/subset.csv<br/>annotated CSV<br/>[subset.csv]")]
  node_sentence_rows["Sentence rows<br/>record layout"]
end

node_readme_en -->|"points to"| node_schema_en
node_readme_en -->|"points to"| node_subset_csv
node_readme_ja -->|"points to"| node_schema_ja
node_readme_ja -->|"points to"| node_subset_csv
node_schema_ja -.->|"mirrors"| node_schema_en
node_schema_en -->|"defines"| node_label_model
node_label_model -->|"governs"| node_sentence_rows
node_subset_csv -->|"implements"| node_sentence_rows
node_sentence_rows -.->|"conforms to"| node_schema_en
node_subset_csv -.->|"validated by"| node_schema_en

click node_readme_en "https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/README.md"
click node_readme_ja "https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/README_ja.md"
click node_schema_en "https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/schema.md"
click node_schema_ja "https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/schema_ja.md"
click node_subset_csv "https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/data/subset.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme_en,node_readme_ja toneBlue
class node_schema_en,node_schema_ja,node_label_model toneAmber
class node_subset_csv,node_sentence_rows toneMint
```

## Components

### Documentation

Entry points for English and Japanese readers.

- [README.md](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/README.md): entry doc · Main English entry point linking the schema and dataset. · `README.md`
- [README_ja.md](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/README_ja.md): entry doc · Japanese entry point mirroring the main documentation. · `README_ja.md`

### Specification

Annotation taxonomy and labeling rules.

- [schema.md](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/schema.md): schema spec · Authoritative definition of the toxicity taxonomy and annotation rules. · `schema.md`
- [schema_ja.md](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/schema_ja.md): schema spec · Japanese version of the annotation schema documentation. · `schema_ja.md`
- **Label system**: annotation model · Two-part labeling model combining toxicity severity with multi-label toxicity categories.

### Dataset

Annotated sentence-level sample data.

- [data/subset.csv](https://github.com/inspection-ai/japanese-toxic-dataset/blob/main/data/subset.csv): annotated CSV · Sentence-level annotated sample dataset with ids, annotator count, severity, and category labels. · `data/subset.csv`
- **Sentence rows**: record layout · One row per sentence, carrying a unique id and multi-label annotation values.

## Connections

- README.md → schema.md: points to · English documentation directs readers to the canonical schema.
- README.md → data/subset.csv: points to · English documentation introduces the sample dataset.
- README_ja.md → schema_ja.md: points to · Japanese documentation directs readers to the Japanese schema.
- README_ja.md → data/subset.csv: points to · Japanese documentation introduces the sample dataset.
- schema_ja.md → schema.md: mirrors · Japanese schema mirrors the English authoritative specification.
- schema.md → Label system: defines · The schema defines the severity scale and toxicity categories.
- Label system → Sentence rows: governs · The label model determines how each sentence row is annotated.
- data/subset.csv → Sentence rows: implements · The CSV stores the sentence-level annotation table.
- Sentence rows → schema.md: conforms to · Each row follows the annotation rules and label definitions in the schema.
- data/subset.csv → schema.md: validated by · Dataset labels are interpreted against the schema.