Last updated: 21 November 2026 · This page is the public documentation of our marking scheme
haAplo uses AI models to write some texts for websites: page titles, descriptions, short sentences, FAQ pages and more.
Every HTML element we inject or serve with generated content carries the
attribute data-haaplo-ai="<markId>". The markId is a
short identifier (ha- followed by lowercase letters and digits).
Example:
<title data-haaplo-ai="ha-9x8c7v">Red wines from Piedmont: Barolo and Barbaresco</title>
A parser can rely on this: an HTML element is marked by
haAplo if and only if it has a data-haaplo-ai attribute; a
JSON-LD entity was generated by haAplo if and only if it has a
haaplo:aiProvenance key; a JSON-LD block with a
haaplo:aiManifest key is a page manifest (section 3).
Every JSON-LD entity we generate carries a haaplo:aiProvenance
node saying who generated it, when, with which model, with which rulebook
version, and whether a person approved it. The haaplo: prefix is
declared in @context and resolves to
https://haaplo.com/ai-transparency#. Example:
<script type="application/ld+json" data-haaplo-ai="ha-x7k2m1">
{
"@context": ["https://schema.org", { "haaplo": "https://haaplo.com/ai-transparency#" }],
"@type": "Organization",
"name": "Example S.r.l.",
"url": "https://example.it",
"haaplo:aiProvenance": {
"haaplo:markId": "ha-x7k2m1",
"haaplo:generator": "haAplo (https://haaplo.com)",
"haaplo:model": "claude-haiku-4-5, claude-sonnet-4-6",
"haaplo:rulebookVersion": "2.0.2",
"haaplo:generatedAt": "2026-11-17T06:00:00.000Z",
"haaplo:humanApproved": false,
"haaplo:schema": "https://haaplo.com/ai-transparency"
}
}
</script>
| Field | Type | Meaning |
|---|---|---|
haaplo:markId | string | Identifier of the marked block; the SAME value appears in the data-haaplo-ai attribute of the element that carries it |
haaplo:generator | string | Who generated the content |
haaplo:model | string | The AI model(s) that wrote any of its words, comma-separated, or "none — deterministic template" when no AI model wrote a word of it. A block that repeats a text an AI model wrote for the page (an approved title in a breadcrumb, the questions of an approved FAQ page) names that model too |
haaplo:rulebookVersion | string | The version of the haAplo rulebook in force when this block was built; the text inside can be older (see haaplo:generatedAt) |
haaplo:generatedAt | string (ISO 8601) | When the content was written. Missing when we do not know it: we never put a guessed date |
haaplo:approvedAt | string (ISO 8601) | When the website owner approved it; only on approved content (FAQ and About pages) |
haaplo:humanApproved | boolean | true only when a person reviewed and approved this content before publication. A structured-data block that repeats an approved text was not itself approved: false |
haaplo:schema | string (URL) | This page, the documentation of the scheme |
An attribute says which element was written by AI; on its own it is just an identifier. The manifest is one JSON-LD block per page that says, for every mark on the page, what the element is, which model wrote it, when, and when the website owner approved it. It names who holds editorial responsibility (the website: its name and address, never a private person), carries the time it was signed, and is signed with Ed25519.
It lists what can be on the page: if the page changed after the
approval, a listed text may not be served. A reader confirms each entry by
finding the element with that markId. Manifests are served on pages with
approved texts and on new pages served through our Cloudflare Worker. On
websites connected with the WordPress plugin, the PrestaShop module or the
Shopify app there is no manifest: there, the marks are the attribute, the
provenance node and the text banner. The manifest has no @type:
it is not a schema.org entity. Example (indented here; the real block is on
one line):
<script type="application/ld+json" data-haaplo-ai="ha-1q2w3e">
{
"@context": { "haaplo": "https://haaplo.com/ai-transparency#" },
"@id": "https://example.it/wines#haaplo-ai-manifest",
"haaplo:aiManifest": {
"haaplo:page": "https://example.it/wines",
"haaplo:generator": "haAplo (https://haaplo.com)",
"haaplo:rulebookVersion": "2.0.2",
"haaplo:schema": "https://haaplo.com/ai-transparency",
"haaplo:editorialResponsibility": { "haaplo:name": "Example Wines", "haaplo:url": "https://example.it" },
"haaplo:marks": [
{
"haaplo:markId": "ha-9x8c7v",
"haaplo:element": "title",
"haaplo:model": "claude-haiku-4-5",
"haaplo:generatedAt": "2026-10-14T08:00:00.000Z",
"haaplo:approvedAt": "2026-10-16T09:00:00.000Z",
"haaplo:humanApproved": true
}
],
"haaplo:signedAt": "2026-11-17T06:00:00.000Z"
},
"haaplo:signature": {
"haaplo:algorithm": "Ed25519",
"haaplo:canonicalization": "RFC 8785",
"haaplo:publicKey": "63e808f3d436c2a7eba14261c5318a5db72fb05f7ec9640ffe7792568dc27f1a",
"haaplo:value": "…base64…"
}
}
</script>
| Field | Type | Meaning |
|---|---|---|
@id | string (URL) | The page address followed by #haaplo-ai-manifest |
haaplo:aiManifest | object | The signed content: every field below except the signature |
haaplo:page | string (URL) | The page the manifest describes |
haaplo:generator, haaplo:rulebookVersion, haaplo:schema | string | As in the provenance node (section 2) |
haaplo:editorialResponsibility | object | Who holds editorial responsibility for the page: haaplo:name (the website's name) and haaplo:url (its address) |
haaplo:marks | array | One entry per AI-written element: haaplo:markId, haaplo:element, haaplo:model, haaplo:generatedAt, haaplo:approvedAt, haaplo:humanApproved |
haaplo:element | string | What the mark touches: one of the values in the table below |
haaplo:signedAt | string (ISO 8601) | When the manifest was signed, by our server's clock; inside the signed content |
haaplo:signature | object | haaplo:algorithm ("Ed25519"), haaplo:canonicalization ("RFC 8785"), haaplo:publicKey (32 bytes, hexadecimal) and haaplo:value (the signature, base64). A manifest without it is not signed. |
The values of haaplo:element:
| Value | The AI-written element |
|---|---|
title | The page title |
meta description | The meta description |
og:title | The social preview title |
og:description | The social preview description |
og:image | The social preview image (the image is yours; the choice was proposed by AI) |
twitter:title | A copy of an approved title |
twitter:description | A copy of an approved description |
twitter:image | A copy of an approved preview image |
img alt | An image description |
h1 | The main heading |
heading level | The level of an existing heading (the words are the website's own) |
link text | The text of a link |
new paragraph | A new sentence placed before an existing paragraph |
new list | An «In brief» list |
FAQ page | A whole FAQ page |
about page | A whole About page |
<script type="application/ld+json"> whose JSON has a haaplo:aiManifest key.haaplo:aiManifest, as parsed from the JSON.JSON.stringify writes them. Take its UTF-8 bytes.haaplo:signature → haaplo:value from base64: it is an Ed25519 signature (RFC 8032) of those bytes.haaplo:publicKey is one of haAplo's published keys below, then verify the signature with it. Anyone can sign a manifest with a key of their own: a manifest signed with another key is not ours.haAplo's published Ed25519 public key (hexadecimal):
63e808f3d436c2a7eba14261c5318a5db72fb05f7ec9640ffe7792568dc27f1a
A reference implementation for Node.js 18 or later:
const crypto = require("node:crypto");
const HAAPLO_KEYS = ["63e808f3d436c2a7eba14261c5318a5db72fb05f7ec9640ffe7792568dc27f1a"];
// RFC 8785 for the values a manifest uses: strings, booleans, arrays, objects
function canonical(v) {
if (Array.isArray(v)) return "[" + v.map(canonical).join(",") + "]";
if (v && typeof v === "object") {
return "{" + Object.keys(v).sort().map((k) => JSON.stringify(k) + ":" + canonical(v[k])).join(",") + "}";
}
return JSON.stringify(v);
}
// block: the parsed JSON of the <script> that has "haaplo:aiManifest"
function verifyManifest(block) {
const sig = block && block["haaplo:signature"];
if (!sig || sig["haaplo:algorithm"] !== "Ed25519") return "not signed";
if (!HAAPLO_KEYS.includes(sig["haaplo:publicKey"])) return "not signed by haAplo";
try {
const key = crypto.createPublicKey({
key: Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), Buffer.from(sig["haaplo:publicKey"], "hex")]),
format: "der",
type: "spki",
});
const bytes = Buffer.from(canonical(block["haaplo:aiManifest"]), "utf8");
return crypto.verify(null, bytes, key, Buffer.from(sig["haaplo:value"], "base64")) ? "valid" : "invalid";
} catch {
return "invalid";
}
}
Text files we generate with AI (the approved content in the fix ZIP) start with a one-line HTML comment carrying the same fields:
<!-- data-haaplo-ai="ha-x7k2m1" · AI-generated by haAplo · model: … · rulebook 2.0.2 · human approved: yes. … Marking scheme: https://haaplo.com/ai-transparency -->
The HTML you paste yourself (the .html files in
approved-content/ of the fix ZIP, and
what the dashboard's copy button puts on your clipboard) and the pages that
the WordPress plugin, the PrestaShop module and the Shopify app create start
with the same line; the block below it carries the attribute with the same
markId.
Files built by templates carry a plain signature instead (for example
# robots.txt — generated by haAplo on …): no AI model writes
them. When a Markdown version or llms.txt copies a text that an AI model
wrote for one of your pages, a banner right below the signature line says
so and names the marks it comes from:
<!-- data-haaplo-ai="ha-3m4n5b" · AI-generated by haAplo · model: none — deterministic template · rulebook 2.0.2 · human approved: yes. Contains text written by AI and approved by the website owner: the page elements marked ha-9x8c7v, ha-2s3d4f. Marking scheme: https://haaplo.com/ai-transparency -->
Questions about the scheme: [email protected].