Skip to content

docs(catalog): open the rule pages with what they cover and cut repeats #554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aicayzer merged 3 commits into from
Oct 21, 2026
Merged

docs(catalog): open the rule pages with what they cover and cut repeats #554

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ed96d6e
docs(catalog): open the rule pages with what they cover and cut repeats
aicayzer Oct 21, 2026
a2ca5e4
docs(catalog): keep the catalog rule pages exact and check their footers
aicayzer Oct 21, 2026
dd9a71e
Merge branch 'main' into docs/rewrite-catalog
aicayzer Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/docs/catalog/edges.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ title: Edges
description: The edge types every instance ships, and what each one carries.
---

Any type can be the source of every edge type.
An edge is a typed, directed link from one item, its source, to another, its target, as [Properties, metadata and edges](/properties-metadata-and-edges#edges) explains. Any type can be the source of every edge type.

<include cwd>src/generated/catalog/edge-types.md</include>

`reverse_name` is the name an edge goes by read from its target. In a folder, the source item's file writes an edge. Where an edge's section gives `written_at` as `target`, the target item's file writes it instead, under its reverse name. Where it gives `none`, no file writes the edge: `in-folder` places an item in a folder, and a folder never renders it. An edge type that gives no `written_at` is written at its source.
The reverse name is the edge's name read from its target. In a [synced folder](/guides/sync-a-folder), the source item's file writes the edge, unless its section below gives `written_at`: `target` puts it in the target item's file under its reverse name, and `none` in no file.

## Fields every edge has

Expand Down
61 changes: 23 additions & 38 deletions content/docs/catalog/field-kinds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,51 +3,36 @@ title: Field kinds
description: The kinds of value a type's field can hold, and what Marfa accepts for each.
---

Each kind and rule links to the contract rule behind it.
Each field of a type holds one kind of value, named by its `type`. **A value Marfa doesn't accept for its kind is refused `400 invalid_properties`**, and `details.errors` names the field. A device applies these rules to whole numbers and URLs offline, and queues nothing it refuses.

## Kinds

| Kind | Holds |
| --- | --- |
| [`string`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-length-cap) | Text of up to `maxLength` UTF-16 code units, or 100,000 where the field sets none. |
| [`number`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-number-exact) | A number. A whole number must be one Marfa serves back with the same digits (see Values). |
| [`integer`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-number-exact) | A whole number, with the same rule on its digits. |
| [`boolean`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-invalid) | `true` or `false`. |
| [`url`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesurl-value) | An absolute URL that the WHATWG URL Standard accepts (see Values). |
| [`email`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-invalid) | An email address. |
| [`datetime`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesdatetime-value) | A date as `YYYY-MM-DD`, or a date and time with a zone, such as `2026-03-01T09:30:00Z`. |
| [`date`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesdatetime-refused) | A calendar date as `YYYY-MM-DD`, with no time. |
| [`enum`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesfield-grammar) | One of the field's `enum_values`. |
| [`array`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesarray-items) | A list. `items_type` names the kind of its elements, and `maxItems` caps their number. |
| [`object`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-invalid) | A JSON object. |
| [`thumbnail`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsthumbnail-format) | A PNG, JPEG or WebP data URI that decodes to at most 16 KiB. |

A value of the wrong shape is refused `400 invalid_properties`, and `details.errors` names the field.
| `string` | Text of up to `maxLength` UTF-16 code units, or 100,000 where the field sets none. It can't hold U+0000. |
| `number` | A number. A whole number must be written in the shortest digits of its 64-bit float, so Marfa serves it back unchanged: `1500000000000000001` and `-0` are refused. Send a whole number that must keep every digit as a `string`. |
| `integer` | A whole number, written the same way. |
| `boolean` | `true` or `false`. |
| `url` | An absolute URL that the WHATWG URL Standard accepts once whitespace is trimmed from both ends. Marfa stores it without that whitespace and without tab, line feed and carriage return characters. |
| `email` | An email address. |
| `datetime` | A date and time with a zone, such as `2026-03-01T09:30:00Z`, or a date alone, as `YYYY-MM-DD`. A time with no zone is refused. |
| `date` | A date alone, as `YYYY-MM-DD`. A date with a time is refused. |
| `enum` | One of the field's `enum_values`. |
| `array` | A list. `items_type` names the kind of its elements, and `maxItems` caps their number. |
| `object` | A JSON object. |
| `thumbnail` | A PNG, JPEG or WebP data URI that decodes to at most 16 KiB. |

The rule on whole numbers holds at any depth, and also in an edge's `properties` and an extension's data. A bulk write that breaks it is refused whole, and `details.index` gives the entry's position.

## Formats

| Format | What Marfa does |
| --- | --- |
| [`url`, `email`, `datetime`, `date`, `thumbnail`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesformat-collapses) | On a `string` field, stores the field as that kind. On an array of strings, stores an array of that kind. |
| [Its own kind](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesformat-own-type) | On a field of the kind the format names, such as a `url` field, stores the field without the `format`. |
| [`bcp47`, `iso3166`](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesformat-string-only) | Keeps the format as a label on a `string` field: `bcp47` for a language tag, as on `language`, and `iso3166` for a country code, as on `country`. Marfa doesn't check the value. |
| [Kind-naming format elsewhere](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesformat-refused) | Refuses `url`, `email`, `datetime`, `date` or `thumbnail` on any other kind, and `thumbnail` on an array, with `400` `invalid_schema`. |
| [`bcp47`, `iso3166` elsewhere](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesformat-string-only-refused) | Refuses them on any kind but `string` with `400` `invalid_schema`. |

## Values
A field's `format` refines its kind:

| Rule | Marfa allows or refuses |
| Format on the field | What Marfa does |
| --- | --- |
| [Null character](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-nul) | A string that holds U+0000 is refused `400` `invalid_properties`. |
| [Exact whole numbers](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-number-exact) | A whole number must be written in the shortest digits of its 64-bit float. `1500000000000000001`, 2^60 (`1152921504606846976`) and `-0` are refused `400` `invalid_properties`. Send a value that must keep every digit as a `string`. |
| [Where it applies](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-number-exact-bulk) | At any depth, including an edge's `properties` and an extension's data. A bulk write is refused whole, and `details.index` gives the entry's position. |
| [Numbers Marfa takes](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md#itemsproperty-number-kept) | A whole number in its shortest digits, such as `1152921504606847000`, and a number with a fraction or an exponent. |
| [URL trimming](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesurl-value) | Marfa trims whitespace from both ends, as JavaScript's `String.prototype.trim` does, then parses the value as an absolute URL. |
| [URL storage](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesurl-stored) | Marfa stores the URL without the trimmed whitespace and without tab, line feed and carriage return characters. |
| [ASCII host](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesurl-punycode) | On a special scheme such as `http`, a host that is ASCII after percent-decoding is taken whatever its labels hold, so `http://xn--` is a URL. |
| [Non-ASCII host](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesurl-idna) | Must be valid IDNA. `http://bücher.xn--` is refused `400` `invalid_properties`. |
| [Forbidden host](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md#typesurl-host-refused) | A forbidden domain code point, or a last label that is a number where the host isn't a valid IPv4 address, is refused `400` `invalid_properties`. |
| [URL on a device](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md#deviceurl-idna-unassigned) | A device applies the same URL rules offline. It also refuses a special-scheme URL whose host holds a code point its IDNA tables leave unassigned. |
| [Numbers on a device](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md#devicenumber-exact) | A device refuses the same whole numbers offline and queues nothing. |

The rules behind this page are in the [items](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md), [types](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md) and [device](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md) chapters of the contract.
| `url`, `email`, `datetime`, `date` or `thumbnail` on a `string` field | Stores the field as that kind. An array of strings takes any of the first four, and becomes an array of that kind. |
| A format that names the field's own kind, such as `url` on a `url` field | Stores the field without the `format`. |
| `bcp47` or `iso3166` on a `string` field | Keeps the format as a label, for a language tag (as on `language`) or a country code (as on `country`). Marfa doesn't check the value. |
| `url`, `email`, `datetime`, `date` or `thumbnail` where the rows above don't allow it, and `bcp47` or `iso3166` on any kind but `string` | Refuses the type with `400 invalid_schema`. |

The rules behind this page are in the [items](https://github.com/withmarfa/marfa/blob/main/conformance/spec/items.md), [types](https://github.com/withmarfa/marfa/blob/main/conformance/spec/types.md) and [device](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md) chapters of the contract, including how Marfa reads a URL's host.
Loading
Loading