# Edges (/edges) How one item links to another, and how the link's type decides what happens when either item goes to the bin. An **edge** links one item, its source, to another, its target, such as a note `about` a book. It's a record of its own, with its own `id`, properties and [version](/versions), so writing an edge never moves either item's version. ```http title="Request" POST /edges Content-Type: application/json { "source_id": "", "target_id": "", "edge_type": "about" } ``` A new item can carry its edges in the same write: `POST /items` takes `edges`, an object from each edge type to the IDs of the targets. If the instance refuses any edge, it creates neither the item nor its edges. ## Edge types [#edge-types] Every edge has an **edge type**, which sets the rules its edges follow: * **Which types each end can be.** Most shipped edge types join any two items, but an `in-collection` edge must point at a container and an `in-folder` edge at a folder. A registered edge type can name its own. * **How many edges an end holds.** A child has one parent, a message is in one thread, and a new item supersedes one old one. * **Whether its edges can loop.** No edge links an item to itself. `parent-of` and `supersedes` refuse an edge that would close a loop, and so do `attached-to` and `comments-on`, through any mix of the two. * **What the bin does across it**, as [Moving an item to the bin](#moving-an-item-to-the-bin) shows. * **Its labels**, the headings an app shows at each end, such as Children and Parent. A write that breaks one is refused with `400 edge_constraint_violation`, or `400 edge_cycle` for a self-link or a loop of `parent-of` or `supersedes`. Marfa ships eleven edge types, and a key that may write edge types can [register more](/api-reference/edge-types/registerEdgeType). The Catalog's [Edges](/catalog/edges) page lists each one's labels and limits. ### Where an item sits [#where-an-item-sits] | Edge type | Use it when | Example | | - | - | - | | `parent-of` | An item sits under another in a hierarchy. The source is the parent, and an item has at most one parent. | A task `parent-of` its subtasks | | `in-collection` | You gather items into a container, in order. | A recipe in a collection of dinners | | `in-thread` | Messages make one conversation, in order. A message is in at most one thread. | An email in its thread | | `attached-to` | An item, such as a file or a page of a scan, exists only for another. The source is the attachment. | A receipt photo attached to an expense | | `comments-on` | An item is a comment on another item, or a reply to a comment. | A reply to a comment on a draft | | `in-folder` | A [synced folder](/run/sync-a-folder) writes it for you, with the file's `path`. | A note in your `Notes` folder | ### How two items relate [#how-two-items-relate] | Edge type | Use it when | Example | | - | - | - | | `about` | One item is on the subject of another. | A note about a book | | `references` | One item's text links to or embeds another, or a program links them for its own use. | A note that links to another note | | `excerpt-of` | An item is a passage taken from another, such as a highlight or a clip, and carries its own text. | A highlight from a book | | `derived-from` | An item was made from another, and both stay valid. | A summary written from an article | | `supersedes` | A new item replaces an old one. | This year's lease superseding last year's | ## Read an item's edges [#read-an-items-edges] An item read carries its outbound edges in `edges`, keyed by edge type, up to 50 of each type. Add `include=backrefs` for the edges that point at it, and `include=neighbors` for the items at the other ends. [List an item's edges](/api-reference/edges/listItemEdges) and [List an item's backrefs](/api-reference/edges/listItemBackrefs) page through the rest. A key reads an edge only when it may read the edge type, which its [edge map](/access#what-a-credential-reaches) grants, and the source item. ## Moving an item to the bin [#moving-an-item-to-the-bin] An edge type's `cascade_on_delete` decides what the bin does across its edges. The shipped edge types use three of the four choices: * **`cascade`, on `parent-of`.** Moving a parent to the bin takes its children with it, at every depth, and never the other way. * **`with-hosts`, on `attached-to` and `comments-on`.** The source is a **part** of its target, its **host**. A part goes to the bin once its last host does, comes back when any host is restored, and is purged with the host that took it once no host is left. Archiving a host, or deleting the edge, leaves the part where it is. * **`orphan`, on the other eight.** The other item stays active, and so does the edge. So a note moved to the bin takes its child note and its comments with it, and leaves the book it's `about` where it is. A registered edge type can choose any of the four, including `block`, which refuses to move either end into the bin while the edge holds it. A purge is never blocked: it deletes the item's edges at both ends. The rules behind this page are in the [edges](https://github.com/withmarfa/marfa/blob/main/conformance/spec/edges.md) chapter of the contract.