# Policy format

What Kapi reads in a policy file. The elements it keeps, the place to sign, the two tags, what it leaves out, the limits and the canonical file.

A policy is one HTML file. Kapi reads any HTML into its policy format, `kapi.works.policy/2`, says in plain words what it changed, and stores the result as one canonical file. People read that file, sign it and get it back as a PDF, so what someone signs is exactly what they saw.

## A whole policy

A short policy, as your AI writes it:

```html
<!doctype html>
<html lang="en-GB">
<head>
<meta charset="utf-8">
<meta name="kapi:act" content="acknowledge">
<meta name="kapi:signers" content="employees">
<title>Gifts and hospitality policy</title>
</head>
<body>
<h1>Gifts and hospitality policy</h1>
<p>Gifts and hospitality must not influence a decision, or look as though they could.</p>
<h2>What to do</h2>
<table>
  <caption>Gifts and hospitality, given or received</caption>
  <tr><th>What</th><th>What to do</th></tr>
  <tr><td>Worth up to £50</td><td>You may give or accept it.</td></tr>
  <tr><td>Worth more than £50</td><td>Ask your manager first, and record it in the gifts register.</td></tr>
</table>
<h2>Find out more</h2>
<ul>
  <li><a href="https://www.gov.uk/government/publications/bribery-act-2010-guidance">GOV.UK: Bribery Act 2010 guidance</a></li>
  <li>Questions: <a href="mailto:hr@example.com">hr@example.com</a></li>
</ul>
<h2>Confirming you have read this policy</h2>
<p>Confirm below that you have read this policy.</p>
<kapi-sign></kapi-sign>
</body>
</html>
```

## What Kapi keeps

| Element                              | For                                                                                                 |
| ------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `h1`                                 | The title. The first `h1` is the policy's title.                                                    |
| `h2`, `h3`, `h4`                     | Section headings. Kapi reads `h5` and `h6` as `h4`.                                                 |
| `p`                                  | Paragraphs.                                                                                         |
| `ul`, `ol`, `li`                     | Lists, up to four levels deep. An `ol` keeps its `start` and its `type`: `1`, `a`, `A`, `i` or `I`. |
| `blockquote`                         | Quoted words.                                                                                       |
| `table`, `caption`, `tr`, `th`, `td` | Tables. Header cells are `th`.                                                                      |
| `hr`                                 | A line between parts.                                                                               |
| `strong` or `b`, `em` or `i`         | Bold and italic words.                                                                              |
| `a href`                             | Links to `https://` pages and `mailto:` addresses.                                                  |
| `br`                                 | A line break.                                                                                       |
| `kapi-sign`                          | The place to sign.                                                                                  |

Containers such as `div`, `section`, `article`, `header` and `footer` keep what they hold. Every other element keeps its words.

## The place to sign

`<kapi-sign></kapi-sign>` marks where people acknowledge or sign. Kapi draws the place to sign there: the statement, then a tick and **Acknowledge**, or a signature, name, company and date and **Sign**. Put it after a sentence that says what people confirm, usually at the end.

A file without one gets one at the end. With more than one, Kapi keeps the first. One inside a sentence, a list or a table moves to just after it.

## Who receives it and what they do

Two optional tags in the head suggest how the policy starts:

```html
<meta name="kapi:act" content="acknowledge">
<meta name="kapi:signers" content="employees, partners, customers">
```

* `kapi:act` is `acknowledge`, for a tick and **Acknowledge**, or `sign`, for a signature.
* `kapi:signers` names any of `employees`, `partners` and `customers`.

Kapi starts the policy's settings from them, and you decide before you publish. The tags stay out of the canonical file.

## Title and language

The title is the first `h1`, else the file's `title`, else the file's name. The language is the `lang` of `html`, else `en-GB`.

## What Kapi leaves out

Kapi leaves out scripts, styles and classes, pictures and media, frames, form fields, and link targets that do not start with `https://` or `mailto:`. It keeps the words people should read, and shows hidden words. Kapi's checks list each change in these words:

| In the file | What Kapi says |
| --- | --- |
| Scripts | Kapi left out a script. Policies don't run code. |
| Styles, stylesheets and classes | Kapi left out the file's styling. Policies use Kapi's reading style, with text size and Listen. |
| Pictures, video, sound and embedded frames | Kapi left out a picture or embedded item. Policies hold words only. |
| Form fields and buttons | Kapi left out a form field. People sign in Kapi's own place to sign. |
| Links that do not start with https:// or mailto: | Kapi kept the words of a link that didn't start with https:// or mailto:, without the link. |
| Hidden words | Some words were hidden in the file. Kapi shows them, so people see everything they sign. |
| Merged table cells | Kapi split merged table cells, so each cell holds its own words. |
| Lists more than four levels deep | Kapi kept lists 4 levels deep and joined deeper levels to the level above. |
| A second place to sign | Kapi kept the first place to sign and left out the other one. |
| A title but no main heading | Kapi added the title as the main heading at the top. |
| No place to sign | Kapi added the place to sign at the end. |

These stop publishing until they are fixed:

| In the file | What Kapi says |
| --- | --- |
| No words | The policy has no words yet. |
| No main heading and no title | Add a title: a main heading at the top of the policy. |
| A main heading over 300 characters | Shorten the main heading to 300 characters or fewer. |
| More than 250,000 characters of words | This policy is too long. A policy holds at most 250,000 characters of words. |
| More than 2,000,000 characters of HTML | This file is too large for a policy. A policy holds at most 2 MB of HTML. |
| A file that is not a web page, such as a Word file renamed .html | Kapi couldn't read this as a web page. Save it as HTML, or upload it as Word or PDF. |

## Limits

| Limit | Value |
| --- | --- |
| HTML Kapi reads | 2,000,000 characters, about 2 MB |
| Words in a policy | 250,000 characters |
| Main heading | 300 characters |
| Levels in a list | 4 |

## The canonical file

Kapi stores only canonical files: `<!doctype html>`, `<html lang>`, a head with the charset and the title, then one block per line, with nested list items indented by two spaces. The same document always gives the same bytes. The policy above, as Kapi stores it:

```html
<!doctype html>
<html lang="en-GB">
<head>
<meta charset="utf-8">
<title>Gifts and hospitality policy</title>
</head>
<body>
<h1>Gifts and hospitality policy</h1>
<p>Gifts and hospitality must not influence a decision, or look as though they could.</p>
<h2>What to do</h2>
<table>
  <caption>Gifts and hospitality, given or received</caption>
  <tr><th>What</th><th>What to do</th></tr>
  <tr><td>Worth up to £50</td><td>You may give or accept it.</td></tr>
  <tr><td>Worth more than £50</td><td>Ask your manager first, and record it in the gifts register.</td></tr>
</table>
<h2>Find out more</h2>
<ul>
  <li><a href="https://www.gov.uk/government/publications/bribery-act-2010-guidance">GOV.UK: Bribery Act 2010 guidance</a></li>
  <li>Questions: <a href="mailto:hr@example.com">hr@example.com</a></li>
</ul>
<h2>Confirming you have read this policy</h2>
<p>Confirm below that you have read this policy.</p>
<kapi-sign></kapi-sign>
</body>
</html>
```

The document fingerprint is the lower-case hex SHA-256 of the canonical file's UTF-8 bytes. Each receipt and each signed copy records it, so a copy can be matched to the version it was signed against. Kapi's [example code of conduct](https://docs.kapiworks.com/build/examples/policies/code-of-conduct.html) has the fingerprint `710e4f0ccc6f0e414a3b6f51a35dc1ee93f9fb9afbd121933f3f1d6270c842bd`. To check it yourself:

```sh
curl -s https://docs.kapiworks.com/build/examples/policies/code-of-conduct.html | shasum -a 256
```