# ddot.it

> ddot.it is a minimal, plain-text triple syntax for building a personal or enterprise knowledge graph across any tool or document type. It is token-efficient, Markdown-compatible, and easy to type on any keyboard.

ddot.it lets you embed typed links (triples) directly in any text — source code comments, Markdown, YAML, AsciiDoc, plain text, and more. A **ddot collector** reads those sources, extracts all triples, and combines them into a single knowledge graph in Connected JSON (CJ) format.

For writing ddot.it, just read write.md and skip the rest.

## Syntax - for Parsing

### Codepoints

Newline normalisation is applied before parsing: `CR LF` → NL, `LF` → NL, `CR` → NL.
Whitespace is stripped from the start and end of names. Whitespace (`WS`) is TAB plus every
Unicode space separator (category `Zs`) — so NBSP (U+00A0) and NARROW NO-BREAK SPACE (U+202F)
count as whitespace, because they are visually indistinguishable from a space. Zero-width
characters (U+200B, U+FEFF) are category `Cf` and are ordinary text.

### Tokens

Symbol characters (`.`, `,`, `;`, `!`) form **maximal runs**; a run is a special token only at its
special length. Everything else is text (`TX`), so `Node.js` and `U.S.A.` contain no operator.

| Token | Meaning                       | Regex                |
|-------|-------------------------------|----------------------|
| `DT2` | exactly two dots              | `(?<!\.)\.{2}(?!\.)` |
| `DT4` | exactly four dots             | `(?<!\.)\.{4}(?!\.)` |
| `CM2` | exactly two commas            | `(?<!,),{2}(?!,)`    |
| `SC2` | exactly two semicolons        | `(?<!;);{2}(?!;)`    |
| `EM2` | exactly two exclamation marks | `(?<!!)!{2}(?!!)`    |

### Formal Grammar (EBNF)

A document is a sequence of lines. There is no chunking construct: an omitted subject continues
the subject of the previous line.

```
Snippet     := Line*

// Ordered choice: a Line is a Triple if one can be derived, otherwise NotATriple.
Line        := WS* Triple WS* NL
              | NotATriple NL

NotATriple  := (WS | DT2 | DT4 | CM2 | SC2 | EM2 | TX)*

DoubleDot   := WS* DT2 WS*
QuadDot     := WS* ( DT4 | DT2 WS+ DT2 ) WS*

Triple      := Subject?
               ( DoubleDot Relation DoubleDot | QuadDot )
               Object
               WS* Meta?

Subject     := TextExcept{NL,DT2,DT4}
Relation    := TextExcept{NL,DT2,DT4}
Object      := TextExcept{NL,CM2}

Meta              := CM2 WS* MetaInline WS*
                   | MetaBlockOpen NL (MetaBlock NL)? WS* CM2 WS*
MetaBlockOpen     := CM2 | NL WS* CM2
MetaInline        := ( MetaTripleInline (SC2 MetaTripleInline)* )
                   | MetaTextInline
MetaTripleInline  := DoubleDot MetaRelation DoubleDot MetaObjectInline
                   | QuadDot MetaObjectInline
MetaBlock         := MetaTripleInBlock (NL MetaTripleInBlock)*
                   | MetaTextBlock
```

Fields may contain spaces; only the operators delimit them. Leading/trailing whitespace is
stripped. `Object` is mandatory and non-empty. Incomplete triples are silently ignored.

The normative definition is the Parse Specification (`site/spec/ddot-it-parse.adoc` (rendered at /spec/ddot-it-parse.html)).

### Typed Link

- Syntax: `aaa .. bbb .. ccc`
- Effect: "aaa" links to "ccc" with link type "bbb"
- With metadata: `aaa .. bbb .. ccc ,, ddd`

### Untyped Link

- Syntax: `aaa .... ccc` (or `aaa .. .. ccc`)
- Effect: "aaa" links to "ccc" with default link type `links to`

### Additional Properties

Omit the subject to add more properties to the last subject:
```
Dirk Hagemann .. works at .. SAP
.. knows .. Claudia Stern
.. phone .. 123-456-789
```

### Metadata

Short form (single triple): `aaa .. bbb .. ccc ,, ..since.. 2010`

Long form (multiple metadata triples):
```
aaa .. bbb .. ccc ,,
..since.. 2010
..fictive.. yes
,,
```

Several inline pairs are separated by `;;`: `,, ..since.. 2025 ;; ..until.. 2027`.
Inside a multi-line `,,` block a `;;` is ordinary text.

Metadata can also be a plain string: `aaa .. bbb .. ccc ,, see also the appendix`.
Free metadata text carries the built-in relation `text`, so that is
`{"type": "text", "to": "see also the appendix"}` — NOT `links to`. The untyped form
`,, .... 2025` is the one that means `links to`, and it is emitted with no `type` at all.

### Standard Relation Types

| Name          | Aliases                | Semantics                                                                 |
|---------------|------------------------|---------------------------------------------------------------------------|
| `related`     | `rel`, `is related`    | Undirected link between A and B                                           |
| `same as`     | `is same as`           | A and B refer to the same concept                                         |
| `is alias of` |                        | Like `same as` but with a clear main concept (symlink semantics)          |
| `links to`    | `link`, `see also`     | Directed untyped link; default when `....` is used                        |
| `has tag`     | `tag`                  | A has tag B; not transitive                                               |
| `has type`    | `type`, `is a`         | A has type B (like rdf:type); inherited via `has subtype`                 |
| `has subtype` | `subtype`              | Transitive specialisation; cycles imply `same as`                         |

### Example

```
Project Eagle .. started in .. 2024
.. doc site .. example.com/docbase/8dcjsid

John Doe .. leads .. Project Eagle ,, .. since .. 2025
Project Eagle .... Moonshot
```

## Commands

Commands are URLs starting with `ddot.it/` (or abbreviated with `!!`). The **slash and a name are
required**; `?` and `#` do not terminate a command but introduce its query and fragment, so
`!!block?end=EOS` is a single command. A command is part of the text of the field holding it.

- `ddot.it` — a document *marker*, not a command. It hints that the file contains ddot.it syntax.
  Readers scan **every** file by default, so the marker only selects files in the optional
  "exclude non-marked files" mode.
- `ddot.it/this` — refers to the current document as the triple subject
- `ddot.it/on` — start processing this region (include)
- `ddot.it/off` — stop processing this region (exclude)
- `ddot.it/block` — the rest of the value is taken verbatim from the following lines,
  up to a blank line or a custom `?end=MARKER`. Allowed in the subject, object,
  metadata-object and metadata-text positions, and only when it ends its line.

## Output: Triple Events

Each recognized triple fires a JSON event:
```json
{ "from": "Project Eagle", "type": "started in", "to": "2024",
  "kind": "markdown", "source": "/README.md", "location": 1 }
```

Fields: `from` (subject), `type` (relation; **omitted** for untyped links — a consumer defaults a
missing `type` to `links to`), `to` (value), `meta` (array of `{type?, to}`, same keys as the
triple), `kind`, `source`, `location` (1-based line number). Key order is fixed:
`from`, `type`, `to`, `meta`, `kind`, `source`, `location`. A line that is not a triple emits
nothing.

The normative definition is the Parse Specification, section "Triple Events"
(`site/spec/ddot-it-parse.adoc`, rendered at /spec/ddot-it-parse.html#events).

## Knowledge Graph Data Model

Triples are stored as a tree: **entity → type → value → entries**. Each entry holds source location (`kind`, `url`, `line`) and optional metadata. Duplicate triples produce multiple entries for the same (entity, type, value) key.

Output is in [Connected JSON](https://j-s-o-n.org) (CJ) format, convertible to other graph formats at [GraphInOut.com](https://graphinout.com).

## Documentation

- [User Guide](https://ddot.it/user-guide.html): Full syntax reference, commands, and standard relation types
- [Developer Guide](https://ddot.it/developer-guide.html): Architecture, formal syntax grammar, triple event spec, collector spec

## Reader Specs

- [Markdown Reader](https://ddot.it/reader-markdown.html): Plain text, HTML comments, code blocks, section attributes
- [AsciiDoc Reader](https://ddot.it/reader-asciidoc.html): Line/block comments, listing blocks, block attributes
- [XML Reader](https://ddot.it/reader-xml.html): XML comments, element text; pom.xml patterns
- [YAML Reader](https://ddot.it/reader-yaml.html): Comments, string values; docker-compose patterns
- [Java Reader](https://ddot.it/reader-java.html): Line comments, block comments, Javadoc, `@DdotIt` annotation
- [Plain Text Reader](https://ddot.it/reader-plaintext.html): Any line of plain text
- [HTML Reader](https://ddot.it/reader-html.html): HTML comments, element text, `data-ddot` attributes
- [PowerPoint Reader](https://ddot.it/reader-powerpoint.html): Slide text, speaker notes

## Optional

- [GraphInOut.com](https://graphinout.com): Convert Connected JSON to other graph formats (RDF, GraphML, etc.)
- [j-s-o-n.org](https://j-s-o-n.org): Connected JSON format specification