@koona/kpin 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +9 -0
- package/README.md +63 -2
- package/bin/kpin.js +169 -0
- package/package.json +67 -4
- package/schema-1.json +259 -0
- package/src/address.js +180 -0
- package/src/index.d.ts +153 -0
- package/src/index.js +10 -0
- package/src/one-click.js +29 -0
- package/src/read.js +359 -0
- package/src/text.js +256 -0
package/LICENSE.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# License
|
|
2
|
+
|
|
3
|
+
Everything in this folder is dedicated to the public domain under **CC0 1.0 Universal**: the specification of the `.kpin` list format in `README.md`, its JSON Schema `schema-1.json`, the examples in `examples/`, the conformance suite in `conformance/` (its `.kpin` files included), and the reference reader and validator in `js/` (the package `@koona/kpin`, with its code and tests). To the extent possible under law, its authors have waived all copyright and related or neighboring rights to it. Copy, adapt and implement it in any tool, open or closed, without asking or crediting.
|
|
4
|
+
|
|
5
|
+
The code in `js/` is under CC0 too, so the format, its suite and its reference reader share one licence and the reader can be copied into any project. CC0 grants no patent licence and comes with no warranty: the code is provided as is.
|
|
6
|
+
|
|
7
|
+
The legal code of the dedication: https://creativecommons.org/publicdomain/zero/1.0/legalcode
|
|
8
|
+
|
|
9
|
+
This folder is the repository [koona-project/kpin](https://github.com/koona-project/kpin), and Koona Pin keeps a copy of it in its `docs/kpin/`. The dedication covers this folder only. Koona Pin's code that reads and writes the format, and the tests that run the suite, are under the GNU GPL 3.0 ([LICENSING.md](https://github.com/andmetoo/koona-pin/blob/main/LICENSING.md)). The reader in `js/` is a port of Koona Pin's reader, which its authors dedicate here under CC0. "Koona" and "Koona Pin" are trademarks ([TRADEMARKS.md](https://github.com/andmetoo/koona-pin/blob/main/TRADEMARKS.md)): implementing the format needs no permission, but a tool should not present itself as Koona.
|
package/README.md
CHANGED
|
@@ -1,3 +1,64 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @koona/kpin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The reference reader and validator of the [`.kpin` list format](https://github.com/koona-project/kpin/blob/main/README.md) 1.x, reader rules of revision **2026-11**. It reads and checks `.kpin` files without Koona Pin, and passes the whole [conformance suite](https://github.com/koona-project/kpin/blob/main/conformance).
|
|
4
|
+
|
|
5
|
+
- ESM with TypeScript types, no runtime dependencies. Its command is `kpin`.
|
|
6
|
+
- Runs in Node 18 and later, and in browsers.
|
|
7
|
+
- Dedicated to the public domain under CC0 1.0, like the spec ([LICENSE.md](https://github.com/koona-project/kpin/blob/main/LICENSE.md)).
|
|
8
|
+
|
|
9
|
+
## Read a list
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
import { read } from "@koona/kpin";
|
|
13
|
+
|
|
14
|
+
const answer = read(bytes); // a Uint8Array or ArrayBuffer as it came, or a string
|
|
15
|
+
if (answer.answer === "ready") {
|
|
16
|
+
const { title, links, feeds, counts, skipped } = answer.list;
|
|
17
|
+
} else {
|
|
18
|
+
console.log(answer.answer, answer.why); // not_a_list, needs_newer_app, other_app (with app), too_big, empty
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Give `read` the file's bytes when you have them: it refuses bytes that aren't UTF-8 as not a list, as the spec says. A string has already been decoded by someone else.
|
|
23
|
+
|
|
24
|
+
A `ready` list is what the suite's `list` describes: `title`, `version`, `newer`, `sections` (how many have a name), `meta`, `counts`, `links` and `feeds`. On top of that, `skipped` says where each skipped item or detail was (`sections[0].items[2]`) and why. `why` on a refusal is meant for a person. It isn't part of the format, so don't match on it.
|
|
25
|
+
|
|
26
|
+
The rules the vector files test are exported too:
|
|
27
|
+
|
|
28
|
+
| Export | Rule of the spec |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `line(text, max)`, `description(text, max)`, `tag(text)`, `withoutInvisible`, `isInvisible`, `joinerStays` | [Text](https://github.com/koona-project/kpin/blob/main/README.md#text) |
|
|
31
|
+
| `linkUrl(raw)`, `feedUrl(raw)` → `{ url }` or `{ skip: "invalid" \| "not_web" }`; `webAddress(raw)` → address or `null`; `publicHost(hostname)` | [Addresses](https://github.com/koona-project/kpin/blob/main/README.md#addresses) |
|
|
32
|
+
| `repeatKey(url)`: equal keys are the same page | [Repeats](https://github.com/koona-project/kpin/blob/main/README.md#repeats) |
|
|
33
|
+
| `oneClick(link)` → the list's address or `null` | [The one-click link](https://github.com/koona-project/kpin/blob/main/README.md#the-one-click-link) |
|
|
34
|
+
|
|
35
|
+
Limits and names are exported as constants: `MAX_BYTES`, `MAX_ITEMS`, `MAX_SECTIONS`, `TAGS_PER_LINK`, `URL_BYTES`, `REVISION` and the rest.
|
|
36
|
+
|
|
37
|
+
## Validate files
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npx @koona/kpin validate list.kpin other.kpin
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
list.kpin: ready: "Small web starter", version 1.0
|
|
45
|
+
3 links, 2 feeds, 2 sections
|
|
46
|
+
skipped: 1 not web
|
|
47
|
+
items[3] "ftp://example.com/file": not an http or https address
|
|
48
|
+
other.kpin: not_a_list: title is missing, not a string or empty once cleaned
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- `--json` prints one JSON document, `{ "revision", "files": [{ "path", "ok", "answer", "list" | "why", ... }] }`.
|
|
52
|
+
- `--schema` also checks each file against [schema-1.json](https://github.com/koona-project/kpin/blob/main/schema-1.json), the schema a writer must satisfy. It needs `ajv` and `ajv-formats` beside `@koona/kpin` (`npm install @koona/kpin ajv@8 ajv-formats@3`). They are optional peer dependencies, so the reader itself installs nothing.
|
|
53
|
+
- `--quiet` prints only the files that fail.
|
|
54
|
+
- `-` in place of a file reads stdin to its end, once per run: `curl -s https://example.org/list.kpin | npx @koona/kpin validate -`.
|
|
55
|
+
|
|
56
|
+
The exit status is 0 when every file is a ready list (and, with `--schema`, valid to the schema), 1 when any isn't, and 2 for a usage error.
|
|
57
|
+
|
|
58
|
+
## Unicode and URLs
|
|
59
|
+
|
|
60
|
+
The reader uses the JavaScript engine's Unicode data (`\p{Script=…}`, `\p{Extended_Pictographic}`, `\p{White_Space}`, `toLowerCase`) and its WHATWG URL parser. The spec asks for the Unicode properties of version 16.0 or later. An engine with older data, such as Node 18 (Unicode 15.1, `process.versions.unicode`), passes the suite, but it may judge a joiner next to a character assigned in Unicode 16.0 differently. URL parsers may also differ at the edges: Node's parser accepts `https://xn--/`, for example, while Rust's `url` crate refuses it.
|
|
61
|
+
|
|
62
|
+
## Tests
|
|
63
|
+
|
|
64
|
+
From the repository's root: `npm ci && npm test` runs the conformance suite, the reader's own tests, the CLI tests and the type check. `npm run test:pack` packs the package as npm would publish it, unpacks it outside the checkout and runs its `--schema`: run it after changing what the package ships. CI runs both, on the runner's Node and on Node 18.
|
package/bin/kpin.js
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// kpin validate <file...>: each file's answer, what was read and what was skipped and why.
|
|
3
|
+
import { readFileSync, existsSync, openSync, readSync, closeSync } from "node:fs";
|
|
4
|
+
import { read, MAX_BYTES, REVISION } from "../src/index.js";
|
|
5
|
+
|
|
6
|
+
const USAGE = `Usage: kpin validate [--json] [--schema] [--quiet] <file...> (- reads stdin)
|
|
7
|
+
|
|
8
|
+
Reads each .kpin file as a reader of the .kpin list format 1.x does (reader rules of
|
|
9
|
+
revision ${REVISION}) and prints its answer: ready, not_a_list, needs_newer_app,
|
|
10
|
+
other_app, too_big or empty, with the counts of a ready list and every item or
|
|
11
|
+
detail that was skipped, and why.
|
|
12
|
+
|
|
13
|
+
--json one JSON document on stdout: { "revision", "files": [ ... ] }
|
|
14
|
+
--schema also check each file against schema-1.json (needs the packages
|
|
15
|
+
ajv and ajv-formats installed beside kpin)
|
|
16
|
+
--quiet print only files that are not ready (or not schema-valid)
|
|
17
|
+
|
|
18
|
+
Exit status: 0 when every file is a ready list (and, with --schema, valid to the
|
|
19
|
+
schema), 1 when any is not, 2 for a usage error.`;
|
|
20
|
+
|
|
21
|
+
function fail(message) {
|
|
22
|
+
process.stderr.write(`${message}\n\n${USAGE}\n`);
|
|
23
|
+
process.exit(2);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* The bytes of a file, or of stdin for `-`, read to the end, at most one past the limit: a bigger
|
|
28
|
+
* file is too big whatever it holds. Read in chunks rather than by the size the file system
|
|
29
|
+
* reports, which is 0 for a pipe, `/dev/stdin` or a process substitution.
|
|
30
|
+
*/
|
|
31
|
+
function bytesOf(path) {
|
|
32
|
+
if (path === "-" && process.stdin.isTTY) process.stderr.write("kpin: reading a .kpin list from stdin (end it with Ctrl-D, or Ctrl-Z then Enter on Windows)\n");
|
|
33
|
+
const fd = path === "-" ? 0 : openSync(path, "r");
|
|
34
|
+
try {
|
|
35
|
+
// One buffer to read into, and a copy of exactly what each read gave, so a pipe that hands
|
|
36
|
+
// over a few KB at a time holds no more than the file.
|
|
37
|
+
const chunk = Buffer.allocUnsafe(64 * 1024);
|
|
38
|
+
const chunks = [];
|
|
39
|
+
let total = 0;
|
|
40
|
+
while (total <= MAX_BYTES) {
|
|
41
|
+
let n;
|
|
42
|
+
try {
|
|
43
|
+
n = readSync(fd, chunk, 0, chunk.length, null);
|
|
44
|
+
} catch (error) {
|
|
45
|
+
// A non-blocking stdin with nothing yet: wait a moment and read again.
|
|
46
|
+
if (error.code !== "EAGAIN") throw error;
|
|
47
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
if (n === 0) break;
|
|
51
|
+
chunks.push(Buffer.from(chunk.subarray(0, n)));
|
|
52
|
+
total += n;
|
|
53
|
+
}
|
|
54
|
+
return total > MAX_BYTES ? new Uint8Array(MAX_BYTES + 1) : Buffer.concat(chunks, total);
|
|
55
|
+
} finally {
|
|
56
|
+
if (fd !== 0) closeSync(fd);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
async function schemaChecker() {
|
|
61
|
+
let Ajv, addFormats;
|
|
62
|
+
try {
|
|
63
|
+
({ default: Ajv } = await import("ajv/dist/2020.js"));
|
|
64
|
+
({ default: addFormats } = await import("ajv-formats"));
|
|
65
|
+
} catch {
|
|
66
|
+
fail("--schema needs ajv and ajv-formats: npm install ajv@8 ajv-formats@3");
|
|
67
|
+
}
|
|
68
|
+
const ajv = new Ajv({ allErrors: true });
|
|
69
|
+
addFormats(ajv);
|
|
70
|
+
// In a checkout of the repository, its own schema: a copy left in js/ by a pack that stopped
|
|
71
|
+
// halfway is never read. Installed, the package's copy, which tools/pack-files.mjs writes.
|
|
72
|
+
// A checkout has both the suite and the schema beside js/; an install's parent folder
|
|
73
|
+
// (node_modules) has neither, whatever other packages it holds.
|
|
74
|
+
const rootSchema = new URL("../../schema-1.json", import.meta.url);
|
|
75
|
+
const checkout = existsSync(rootSchema) && existsSync(new URL("../../conformance/cases.json", import.meta.url));
|
|
76
|
+
const schema = checkout ? rootSchema : new URL("../schema-1.json", import.meta.url);
|
|
77
|
+
const validate = ajv.compile(JSON.parse(readFileSync(schema, "utf8")));
|
|
78
|
+
return (bytes) => {
|
|
79
|
+
let doc;
|
|
80
|
+
try {
|
|
81
|
+
const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); // drops a byte order mark
|
|
82
|
+
doc = JSON.parse(text);
|
|
83
|
+
} catch {
|
|
84
|
+
return { valid: false, errors: ["not UTF-8 JSON"] };
|
|
85
|
+
}
|
|
86
|
+
const valid = validate(doc);
|
|
87
|
+
return { valid, errors: valid ? [] : validate.errors.map((e) => `${e.instancePath || "/"} ${e.message}`) };
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
|
|
92
|
+
const WHY = {
|
|
93
|
+
repeated: "a repeat of an earlier page",
|
|
94
|
+
not_web: "not an http or https address",
|
|
95
|
+
invalid: "no usable address",
|
|
96
|
+
unknown_type: "an item type this reader does not know",
|
|
97
|
+
not_an_object: "not an object",
|
|
98
|
+
unknown_field: "a field this reader does not know",
|
|
99
|
+
};
|
|
100
|
+
|
|
101
|
+
/** How a file is named in the text output: stdin as (stdin), not as the argument `-`. */
|
|
102
|
+
const label = (path) => (path === "-" ? "(stdin)" : path);
|
|
103
|
+
|
|
104
|
+
function human(file) {
|
|
105
|
+
const out = [];
|
|
106
|
+
const { result: r } = file;
|
|
107
|
+
const name = label(file.path);
|
|
108
|
+
if (file.error) out.push(`${name}: cannot read: ${file.error}`);
|
|
109
|
+
else if (r.answer !== "ready") out.push(`${name}: ${r.answer}${r.app ? ` (${r.app})` : ""}: ${r.why}`);
|
|
110
|
+
else {
|
|
111
|
+
const { list } = r;
|
|
112
|
+
const c = list.counts;
|
|
113
|
+
out.push(`${name}: ready: "${list.title}", version ${list.version}${list.newer ? " (newer than 1.0)" : ""}`);
|
|
114
|
+
out.push(` ${plural(c.links, "link")}, ${plural(c.feeds, "feed")}, ${plural(list.sections, "section")}`);
|
|
115
|
+
const skipped = [
|
|
116
|
+
c.repeated && `${c.repeated} repeated`,
|
|
117
|
+
c.not_web && `${c.not_web} not web`,
|
|
118
|
+
c.invalid && `${c.invalid} invalid`,
|
|
119
|
+
c.skipped_items && plural(c.skipped_items, "unknown item"),
|
|
120
|
+
c.skipped_details && plural(c.skipped_details, "unknown detail"),
|
|
121
|
+
].filter(Boolean);
|
|
122
|
+
if (skipped.length) out.push(` skipped: ${skipped.join(", ")}`);
|
|
123
|
+
for (const s of list.skipped) {
|
|
124
|
+
const what = s.field ? ` "${s.field}"` : s.type ? ` "${s.type}"` : s.url ? ` ${JSON.stringify(s.url)}` : "";
|
|
125
|
+
out.push(` ${s.at || "(the list)"}${what}: ${WHY[s.reason]}`);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
if (file.schema) out.push(file.schema.valid ? " schema: valid" : ` schema: not valid\n${file.schema.errors.map((e) => ` ${e}`).join("\n")}`);
|
|
129
|
+
return out.join("\n");
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
async function main(argv) {
|
|
133
|
+
const [command, ...rest] = argv;
|
|
134
|
+
if (command === "--help" || command === "-h" || command === "help") {
|
|
135
|
+
process.stdout.write(`${USAGE}\n`);
|
|
136
|
+
return 0;
|
|
137
|
+
}
|
|
138
|
+
if (command !== "validate") fail(command ? `Unknown command: ${command}` : "No command given.");
|
|
139
|
+
const flags = new Set(rest.filter((a) => a.startsWith("--")));
|
|
140
|
+
const paths = rest.filter((a) => !a.startsWith("--"));
|
|
141
|
+
for (const flag of flags) if (!["--json", "--schema", "--quiet"].includes(flag)) fail(`Unknown option: ${flag}`);
|
|
142
|
+
if (paths.length === 0) fail("No file given.");
|
|
143
|
+
if (paths.filter((p) => p === "-").length > 1) fail("- (stdin) can be given once: there is one stdin to read.");
|
|
144
|
+
const check = flags.has("--schema") ? await schemaChecker() : null;
|
|
145
|
+
|
|
146
|
+
const files = paths.map((path) => {
|
|
147
|
+
let bytes;
|
|
148
|
+
try {
|
|
149
|
+
bytes = bytesOf(path);
|
|
150
|
+
} catch (error) {
|
|
151
|
+
return { path, error: error.code ?? error.message, ok: false };
|
|
152
|
+
}
|
|
153
|
+
const result = read(bytes);
|
|
154
|
+
const file = { path, result };
|
|
155
|
+
if (check) file.schema = bytes.length > MAX_BYTES ? { valid: false, errors: [`not checked: more than ${MAX_BYTES} bytes`] } : check(bytes);
|
|
156
|
+
file.ok = result.answer === "ready" && (!file.schema || file.schema.valid);
|
|
157
|
+
return file;
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
if (flags.has("--json")) {
|
|
161
|
+
const shown = files.map(({ path, error, result, schema, ok }) => ({ path, ...(path === "-" ? { stdin: true } : {}), ok, ...(error ? { error } : result), ...(schema ? { schema } : {}) }));
|
|
162
|
+
process.stdout.write(`${JSON.stringify({ revision: REVISION, files: shown }, null, 2)}\n`);
|
|
163
|
+
} else {
|
|
164
|
+
for (const file of files) if (!flags.has("--quiet") || !file.ok) process.stdout.write(`${human(file)}\n`);
|
|
165
|
+
}
|
|
166
|
+
return files.every((f) => f.ok) ? 0 : 1;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
process.exitCode = await main(process.argv.slice(2));
|
package/package.json
CHANGED
|
@@ -1,6 +1,69 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@koona/kpin",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Reference reader and validator of the .kpin list format: read and check .kpin files without Koona Pin",
|
|
5
|
+
"license": "CC0-1.0",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/koona-project/kpin.git",
|
|
10
|
+
"directory": "js"
|
|
11
|
+
},
|
|
12
|
+
"homepage": "https://github.com/koona-project/kpin/tree/main/js#readme",
|
|
13
|
+
"keywords": [
|
|
14
|
+
"kpin",
|
|
15
|
+
"koona",
|
|
16
|
+
"list",
|
|
17
|
+
"bookmarks",
|
|
18
|
+
"feeds",
|
|
19
|
+
"validator"
|
|
20
|
+
],
|
|
21
|
+
"exports": {
|
|
22
|
+
".": {
|
|
23
|
+
"types": "./src/index.d.ts",
|
|
24
|
+
"default": "./src/index.js"
|
|
25
|
+
},
|
|
26
|
+
"./schema-1.json": "./schema-1.json",
|
|
27
|
+
"./package.json": "./package.json"
|
|
28
|
+
},
|
|
29
|
+
"types": "./src/index.d.ts",
|
|
30
|
+
"bin": {
|
|
31
|
+
"kpin": "bin/kpin.js"
|
|
32
|
+
},
|
|
33
|
+
"files": [
|
|
34
|
+
"src",
|
|
35
|
+
"bin",
|
|
36
|
+
"schema-1.json",
|
|
37
|
+
"LICENSE.md"
|
|
38
|
+
],
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public"
|
|
41
|
+
},
|
|
42
|
+
"engines": {
|
|
43
|
+
"node": ">=18"
|
|
44
|
+
},
|
|
45
|
+
"sideEffects": false,
|
|
46
|
+
"scripts": {
|
|
47
|
+
"test": "node --test test/conformance.test.js test/read.test.js test/cli.test.js && tsc -p test",
|
|
48
|
+
"test:pack": "node --test test/pack.test.js",
|
|
49
|
+
"prepack": "node tools/pack-files.mjs copy",
|
|
50
|
+
"postpack": "node tools/pack-files.mjs remove"
|
|
51
|
+
},
|
|
52
|
+
"peerDependencies": {
|
|
53
|
+
"ajv": "^8.12.0",
|
|
54
|
+
"ajv-formats": "^3.0.0"
|
|
55
|
+
},
|
|
56
|
+
"peerDependenciesMeta": {
|
|
57
|
+
"ajv": {
|
|
58
|
+
"optional": true
|
|
59
|
+
},
|
|
60
|
+
"ajv-formats": {
|
|
61
|
+
"optional": true
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
"devDependencies": {
|
|
65
|
+
"ajv": "8.20.0",
|
|
66
|
+
"ajv-formats": "3.0.1",
|
|
67
|
+
"typescript": "7.0.2"
|
|
68
|
+
}
|
|
69
|
+
}
|
package/schema-1.json
ADDED
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://koona.app/pin/schema/list-1.json",
|
|
4
|
+
"title": "Koona list (.kpin), version 1.x",
|
|
5
|
+
"description": "A shareable list of links and feeds for Koona Pin: the envelope shared by Koona apps with the payload of app \"pin\", kind \"list\". This schema is what a writer must produce; readers are more tolerant and are described in its specification (README.md of https://github.com/koona-project/kpin). Four rules of a writer cannot be written here: a file of at most 2 MB (2,097,152 bytes), at most 5,000 items across all sections and the top level, addresses of at most 2,048 bytes in UTF-8 (maxLength counts characters), and text with a visible character once cleaned, which a text made only of tag characters passes here and fails in a reader. Dedicated to the public domain under CC0 1.0.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": [
|
|
8
|
+
"format",
|
|
9
|
+
"app",
|
|
10
|
+
"kind",
|
|
11
|
+
"version",
|
|
12
|
+
"title"
|
|
13
|
+
],
|
|
14
|
+
"anyOf": [
|
|
15
|
+
{
|
|
16
|
+
"required": [
|
|
17
|
+
"items"
|
|
18
|
+
],
|
|
19
|
+
"properties": {
|
|
20
|
+
"items": {
|
|
21
|
+
"type": "array",
|
|
22
|
+
"minItems": 1
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"required": [
|
|
28
|
+
"sections"
|
|
29
|
+
],
|
|
30
|
+
"properties": {
|
|
31
|
+
"sections": {
|
|
32
|
+
"type": "array",
|
|
33
|
+
"contains": {
|
|
34
|
+
"type": "object",
|
|
35
|
+
"required": [
|
|
36
|
+
"items"
|
|
37
|
+
],
|
|
38
|
+
"properties": {
|
|
39
|
+
"items": {
|
|
40
|
+
"type": "array",
|
|
41
|
+
"minItems": 1
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
],
|
|
49
|
+
"properties": {
|
|
50
|
+
"$schema": {
|
|
51
|
+
"type": "string",
|
|
52
|
+
"description": "Optional pointer to this schema, for editors. Readers ignore it."
|
|
53
|
+
},
|
|
54
|
+
"format": {
|
|
55
|
+
"const": "koona",
|
|
56
|
+
"description": "Permanent identifier shared by every Koona app."
|
|
57
|
+
},
|
|
58
|
+
"app": {
|
|
59
|
+
"type": "string",
|
|
60
|
+
"pattern": "^[a-z][a-z0-9-]{0,31}$",
|
|
61
|
+
"description": "The app the payload is for. Koona Pin reads \"pin\" and names the app for any other value."
|
|
62
|
+
},
|
|
63
|
+
"kind": {
|
|
64
|
+
"type": "string",
|
|
65
|
+
"pattern": "^[a-z][a-z0-9-]{0,31}$",
|
|
66
|
+
"description": "What the file holds. Version 1 of app \"pin\" defines \"list\"."
|
|
67
|
+
},
|
|
68
|
+
"version": {
|
|
69
|
+
"type": "string",
|
|
70
|
+
"pattern": "^1\\.(0|[1-9][0-9]{0,3})$",
|
|
71
|
+
"description": "MAJOR.MINOR of this app and kind, as text: \"1.10\" is not \"1.1\". A newer MINOR only adds optional fields and item types; a newer MAJOR is refused by older readers."
|
|
72
|
+
},
|
|
73
|
+
"generator": {
|
|
74
|
+
"type": "string",
|
|
75
|
+
"maxLength": 80,
|
|
76
|
+
"description": "What wrote the file, such as \"Koona Pin 2.4.0\". For diagnostics only, never for behaviour."
|
|
77
|
+
},
|
|
78
|
+
"id": {
|
|
79
|
+
"type": "string",
|
|
80
|
+
"pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
|
|
81
|
+
"description": "A slug that marks the same list across its updates."
|
|
82
|
+
},
|
|
83
|
+
"title": {
|
|
84
|
+
"type": "string",
|
|
85
|
+
"$ref": "#/$defs/text",
|
|
86
|
+
"maxLength": 120
|
|
87
|
+
},
|
|
88
|
+
"description": {
|
|
89
|
+
"type": "string",
|
|
90
|
+
"maxLength": 2000,
|
|
91
|
+
"description": "Plain text; line breaks are kept."
|
|
92
|
+
},
|
|
93
|
+
"author": {
|
|
94
|
+
"type": "object",
|
|
95
|
+
"properties": {
|
|
96
|
+
"name": {
|
|
97
|
+
"type": "string",
|
|
98
|
+
"maxLength": 120
|
|
99
|
+
},
|
|
100
|
+
"url": {
|
|
101
|
+
"$ref": "#/$defs/httpUrl"
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
},
|
|
105
|
+
"license": {
|
|
106
|
+
"type": "string",
|
|
107
|
+
"maxLength": 64,
|
|
108
|
+
"description": "An SPDX license identifier, such as CC0-1.0 or CC-BY-4.0. It covers the list itself, not the pages it links to."
|
|
109
|
+
},
|
|
110
|
+
"language": {
|
|
111
|
+
"type": "string",
|
|
112
|
+
"pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
|
|
113
|
+
"description": "The language of the list's text, as a BCP 47 tag."
|
|
114
|
+
},
|
|
115
|
+
"updated": {
|
|
116
|
+
"type": "string",
|
|
117
|
+
"format": "date",
|
|
118
|
+
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
|
|
119
|
+
"description": "The date the list was last checked or changed, YYYY-MM-DD."
|
|
120
|
+
},
|
|
121
|
+
"homepage": {
|
|
122
|
+
"$ref": "#/$defs/httpUrl",
|
|
123
|
+
"description": "Where the list is published."
|
|
124
|
+
},
|
|
125
|
+
"sections": {
|
|
126
|
+
"type": "array",
|
|
127
|
+
"maxItems": 200,
|
|
128
|
+
"items": {
|
|
129
|
+
"type": "object",
|
|
130
|
+
"required": [
|
|
131
|
+
"name",
|
|
132
|
+
"items"
|
|
133
|
+
],
|
|
134
|
+
"properties": {
|
|
135
|
+
"name": {
|
|
136
|
+
"type": "string",
|
|
137
|
+
"$ref": "#/$defs/text",
|
|
138
|
+
"maxLength": 120
|
|
139
|
+
},
|
|
140
|
+
"items": {
|
|
141
|
+
"$ref": "#/$defs/items"
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
},
|
|
146
|
+
"items": {
|
|
147
|
+
"$ref": "#/$defs/items",
|
|
148
|
+
"description": "The items that are in no section."
|
|
149
|
+
}
|
|
150
|
+
},
|
|
151
|
+
"$defs": {
|
|
152
|
+
"text": {
|
|
153
|
+
"type": "string",
|
|
154
|
+
"minLength": 1,
|
|
155
|
+
"pattern": "[^\\s\\u0000-\\u001f\\u007f-\\u009f\\u00a0\\u00ad\\u061c\\u1680\\u180e\\u2000-\\u200f\\u2028-\\u202f\\u205f-\\u2064\\u2066-\\u206f\\u3000\\ufeff\\ufff9-\\ufffb]",
|
|
156
|
+
"description": "One line of text with at least one visible character: not empty, and not only white space, control or invisible characters. The Unicode white space is named, not left to \\s, which some validators read as ASCII only. The tag characters (U+E0001, U+E0020 to U+E007F) lie outside the Basic Multilingual Plane, where patterns differ between validators, so they are not named here: a text made only of them passes this pattern and is still empty to a reader."
|
|
157
|
+
},
|
|
158
|
+
"httpUrl": {
|
|
159
|
+
"type": "string",
|
|
160
|
+
"maxLength": 2048,
|
|
161
|
+
"pattern": "^[Hh][Tt][Tt][Pp][Ss]?://[^/?#\\s]+",
|
|
162
|
+
"description": "An absolute http or https address with a host. A user name or password in it is dropped by readers; writers leave them out."
|
|
163
|
+
},
|
|
164
|
+
"items": {
|
|
165
|
+
"type": "array",
|
|
166
|
+
"maxItems": 5000,
|
|
167
|
+
"items": {
|
|
168
|
+
"oneOf": [
|
|
169
|
+
{
|
|
170
|
+
"$ref": "#/$defs/link"
|
|
171
|
+
},
|
|
172
|
+
{
|
|
173
|
+
"$ref": "#/$defs/feed"
|
|
174
|
+
},
|
|
175
|
+
{
|
|
176
|
+
"$ref": "#/$defs/unknown"
|
|
177
|
+
}
|
|
178
|
+
]
|
|
179
|
+
}
|
|
180
|
+
},
|
|
181
|
+
"link": {
|
|
182
|
+
"type": "object",
|
|
183
|
+
"required": [
|
|
184
|
+
"type",
|
|
185
|
+
"url"
|
|
186
|
+
],
|
|
187
|
+
"properties": {
|
|
188
|
+
"type": {
|
|
189
|
+
"const": "link"
|
|
190
|
+
},
|
|
191
|
+
"url": {
|
|
192
|
+
"$ref": "#/$defs/httpUrl"
|
|
193
|
+
},
|
|
194
|
+
"title": {
|
|
195
|
+
"type": "string",
|
|
196
|
+
"$ref": "#/$defs/text",
|
|
197
|
+
"maxLength": 500
|
|
198
|
+
},
|
|
199
|
+
"description": {
|
|
200
|
+
"type": "string",
|
|
201
|
+
"maxLength": 2000
|
|
202
|
+
},
|
|
203
|
+
"tags": {
|
|
204
|
+
"type": "array",
|
|
205
|
+
"maxItems": 20,
|
|
206
|
+
"uniqueItems": true,
|
|
207
|
+
"items": {
|
|
208
|
+
"type": "string",
|
|
209
|
+
"$ref": "#/$defs/text",
|
|
210
|
+
"maxLength": 64
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
},
|
|
215
|
+
"feed": {
|
|
216
|
+
"type": "object",
|
|
217
|
+
"required": [
|
|
218
|
+
"type",
|
|
219
|
+
"url"
|
|
220
|
+
],
|
|
221
|
+
"properties": {
|
|
222
|
+
"type": {
|
|
223
|
+
"const": "feed"
|
|
224
|
+
},
|
|
225
|
+
"url": {
|
|
226
|
+
"$ref": "#/$defs/httpUrl",
|
|
227
|
+
"description": "The address of the RSS, Atom or JSON feed itself. Readers do not follow feeds on this computer or the local network."
|
|
228
|
+
},
|
|
229
|
+
"site": {
|
|
230
|
+
"$ref": "#/$defs/httpUrl",
|
|
231
|
+
"description": "The site's home page."
|
|
232
|
+
},
|
|
233
|
+
"title": {
|
|
234
|
+
"type": "string",
|
|
235
|
+
"$ref": "#/$defs/text",
|
|
236
|
+
"maxLength": 500
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
},
|
|
240
|
+
"unknown": {
|
|
241
|
+
"type": "object",
|
|
242
|
+
"required": [
|
|
243
|
+
"type"
|
|
244
|
+
],
|
|
245
|
+
"properties": {
|
|
246
|
+
"type": {
|
|
247
|
+
"type": "string",
|
|
248
|
+
"not": {
|
|
249
|
+
"enum": [
|
|
250
|
+
"link",
|
|
251
|
+
"feed"
|
|
252
|
+
]
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
},
|
|
256
|
+
"description": "An item type from a newer 1.x. Valid; readers that do not know it skip it and count it."
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
}
|