Policy format

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 policyCopy Anchor Link

A short policy, as your AI writes it:

<!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 keepsCopy Anchor Link

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

The place to signCopy Anchor Link

<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 doCopy Anchor Link

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

<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 languageCopy Anchor Link

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 outCopy Anchor Link

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:

These stop publishing until they are fixed:

LimitsCopy Anchor Link

The canonical fileCopy Anchor Link

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:

<!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 has the fingerprint 710e4f0ccc6f0e414a3b6f51a35dc1ee93f9fb9afbd121933f3f1d6270c842bd. To check it yourself:

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