Repository navigation
Expand file tree
/
Copy pathhome.mjs
More file actions
334 lines (315 loc) · 13.1 KB
/
Copy pathhome.mjs
File metadata and controls
334 lines (315 loc) · 13.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
/**
* home.mjs — the landing page.
*
* The job of this page, borrowed from the specification sites that do it well:
* say what the thing is in one sentence, show it working before asking anyone
* to read anything, then teach the two rules that surprise people. Everything
* deeper is a link.
*/
import { codeBlock } from "./highlight.mjs";
import { SITE } from "./layout.mjs";
const FILTER_EXAMPLE = `{
"$and": [
{ "status": "available" },
{ "$or": [
{ "species": { "$in": ["cat", "dog"] } },
{ "tags": { "$some": { "$in": ["rescue", "senior"] } } }
]},
{ "born": { "$gte": "2020-01-01" } }
]
}`;
const OPENAPI_EXAMPLE = `paths:
/pets/search:
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
filter:
$ref: '${SITE.schemaUrl}'
limit:
type: integer`;
const MCP_EXAMPLE = `{
"name": "search_pets",
"description": "Search the pet catalogue.",
"inputSchema": {
"type": "object",
"properties": {
"filter": { "$ref": "${SITE.schemaUrl}" }
}
}
}`;
const QUERY_EXAMPLE = `QUERY /pets HTTP/1.1
Host: api.example.com
Content-Type: application/json
{ "filter": { "status": "available" } }`;
const SHORTHAND_BEFORE = `{
"status": "available",
"species": "cat"
}`;
const SHORTHAND_AFTER = `{
"$and": [
{ "status": { "$eq": "available" } },
{ "species": { "$eq": "cat" } }
]
}`;
const UNKNOWN_EXAMPLE = `// Does NOT match a pet whose status is absent or null
{ "status": { "$ne": "archived" } }
// Does match them: UNKNOWN is resolved to TRUE
{ "status": { "$ne": "archived", "$unknownAs": true } }`;
const CAPABILITIES_EXAMPLE = `{
"queryLanguage": "${SITE.schemaUrl}",
"profiles": ["core", "strings", "ranges", "collections"],
"fields": {
"status": { "values": ["available", "pending", "sold"] },
"born": { "type": "string", "format": "date" }
}
}`;
export function homeBody() {
return `
<section class="hero">
<div class="wrap hero-inner">
<div class="hero-copy">
<img class="hero-logo" src="/assets/logo.svg" alt="" width="88" height="88">
<h1>Predicates, as JSON.<br>Described by a schema.</h1>
<p class="lede">
OpenPredicate is an open standard for the <strong>filter</strong> half of a search API — a
JSON-encoded, SQL-flavoured predicate language defined by a single JSON Schema. Write the
grammar once, and every <code>POST /…/search</code>, every <code>QUERY /…</code> and every
search tool you hand an agent speaks it.
</p>
<div class="cta">
<a class="btn primary" href="/spec/">Read the specification</a>
<a class="btn" href="/playground/">Try a filter</a>
<a class="btn ghost" href="${SITE.repo}" rel="noopener">GitHub</a>
</div>
<ul class="badges">
<li>JSON Schema draft 2020-12</li>
<li>Grammar <code>v${SITE.grammarVersion}</code></li>
<li>MIT licensed</li>
<li>No dependencies</li>
</ul>
</div>
<div class="hero-code">
${codeBlock(FILTER_EXAMPLE, "json", { label: "Available cats and dogs, or any rescue, born since 2020" })}
</div>
</div>
</section>
<section class="band">
<div class="wrap">
<h2 class="section-title">Why a standard for this at all</h2>
<p class="section-lede">
Search endpoints attract bespoke query syntaxes. Each arrives as an opaque string
— <code>?q=status:open AND born>2020</code> — that no schema can validate, no generator can
type, and no client can build safely. Structuring the predicate as JSON changes what the rest
of your stack can do with it.
</p>
<div class="cards three">
<article class="card">
<h3>One grammar, every endpoint</h3>
<p>
The schema covers the predicate and nothing else — no projection, ordering or pagination.
That restraint is what makes it reusable: those parts differ per API, the filter does not.
Clients learn one language instead of one syntax per endpoint.
</p>
</article>
<article class="card">
<h3>Validated where APIs are already described</h3>
<p>
JSON Schema is the interchange format of OpenAPI 3.1 and it is what an MCP
<code>inputSchema</code> is. So a filter validates in CI, shows up in generated docs, and
becomes a real type in a generated client — with no new toolchain.
</p>
</article>
<article class="card">
<h3>Servers say what they cannot do</h3>
<p>
No server implements every operator. A server advertises
<a href="/operators/">profiles</a> and publishes a capability document, so a client learns
the limits from a schema rather than from a runtime error.
</p>
</article>
</div>
</div>
</section>
<section class="band alt">
<div class="wrap">
<h2 class="section-title">The two rules worth learning first</h2>
<p class="section-lede">
Most of the language is guessable. These two are not, and between them they account for nearly
every surprise. They are normative — <a href="/spec/">the spec</a> pins them down in §4.
</p>
<div class="rule">
<div class="rule-copy">
<h3><span class="num">1</span> Siblings mean AND. A bare value means equals.</h3>
<p>
At every level, sibling members are combined with implicit AND, and a scalar in the value
position is shorthand for <code>$eq</code>. The two filters on the right are the same
filter. You only need <code>$and</code> when you want the same field twice, or when you
are nesting it inside <code>$or</code>.
</p>
</div>
<div class="rule-code">
${codeBlock(SHORTHAND_BEFORE, "json", { label: "What you write" })}
${codeBlock(SHORTHAND_AFTER, "json", { label: "What it means" })}
</div>
</div>
<div class="rule">
<div class="rule-copy">
<h3><span class="num">2</span> Comparison is three-valued, and only TRUE matches.</h3>
<p>
A comparison against a field that is <code>null</code> or absent is neither TRUE nor FALSE
— it is UNKNOWN, and only TRUE matches. So a negation does <em>not</em> sweep up the
records that have no value at all, which is the SQL behaviour and almost never what someone
expects the first time.
</p>
<p>
When you do want them, say so with <code>$unknownAs</code>. Making it explicit is the whole
point: the filter records the decision instead of leaving it to the server.
</p>
<table class="truth">
<caption>Only TRUE matches</caption>
<thead><tr><th>Field</th><th><code>{"$ne": "archived"}</code></th><th>Matches?</th></tr></thead>
<tbody>
<tr><td><code>"open"</code></td><td>TRUE</td><td class="yes">yes</td></tr>
<tr><td><code>"archived"</code></td><td>FALSE</td><td class="no">no</td></tr>
<tr><td><code>null</code></td><td>UNKNOWN</td><td class="no">no</td></tr>
<tr><td>absent</td><td>UNKNOWN</td><td class="no">no</td></tr>
</tbody>
</table>
</div>
<div class="rule-code">
${codeBlock(UNKNOWN_EXAMPLE, "json", { label: "Resolving UNKNOWN explicitly" })}
</div>
</div>
</div>
</section>
<section class="band">
<div class="wrap">
<h2 class="section-title">Two integration points, one schema</h2>
<p class="section-lede">
Because the grammar is a JSON Schema, integrating it is a <code>$ref</code>. Both of the
places an API is described today already speak the format.
</p>
<div class="cards two">
<article class="card code-card">
<h3>From an OpenAPI document</h3>
<p>Reference the schema from the request body. It validates in CI and types your clients.</p>
${codeBlock(OPENAPI_EXAMPLE, "yaml", { label: "OpenAPI 3.1 · POST /pets/search" })}
</article>
<article class="card code-card">
<h3>As an MCP tool's inputSchema</h3>
<p>
The grammar becomes the contract a model writes filters against, with each operator's
<code>description</code> carried along as the instructions.
</p>
${codeBlock(MCP_EXAMPLE, "json", { label: "MCP tool definition" })}
</article>
</div>
<div class="cards two">
<article class="card code-card">
<h3>Or as the body of an HTTP QUERY</h3>
<p>
<a href="https://www.rfc-editor.org/rfc/rfc10008" rel="noopener">RFC 10008</a> gives search
a safe, cacheable method with a body. A predicate is exactly what that body needs to be.
</p>
${codeBlock(QUERY_EXAMPLE, "http", { label: "OpenAPI 3.2 · QUERY /pets" })}
</article>
<article class="card code-card">
<h3>And the server declares its slice</h3>
<p>
A capability document states the profiles served and each field's domain, so a client can
narrow its filters before it sends one.
</p>
${codeBlock(CAPABILITIES_EXAMPLE, "json", { label: "GET /pets/capabilities" })}
</article>
</div>
</div>
</section>
<section class="band alt">
<div class="wrap">
<h2 class="section-title">Start where you are</h2>
<div class="cards three">
<article class="card link-card">
<h3><a href="/guide/">How to design a search API</a></h3>
<p>
The five decisions behind a search endpoint — where the filter goes, what grammar it
speaks, how to describe it to developers and to agents, and how to say no — with what this
specification settles for each.
</p>
</article>
<article class="card link-card">
<h3><a href="/spec/">Specification</a></h3>
<p>
The normative text: the data model, three-valued logic, coercion, every operator's
semantics, the safety limits and the error model. Versioned and immutable per release.
</p>
</article>
<article class="card link-card">
<h3><a href="/operators/">Operator reference</a></h3>
<p>
Every operator, grouped by the profile that carries it, generated from the schema — so it
is the grammar's own description of itself, not a retelling.
</p>
</article>
<article class="card link-card">
<h3><a href="/playground/">Playground</a></h3>
<p>
Write a filter, watch it validate against the real schema in your browser, and see the
error a conforming server would return.
</p>
</article>
<article class="card link-card">
<h3><a href="/schema/v${SITE.grammarVersion}/open-predicate-schema.json">The schema</a></h3>
<p>
One file, no dependencies, served at its own <code>$id</code>. Vendor it or
<code>$ref</code> it. <code>${SITE.schemaUrl.replace(SITE.origin, "")}</code>
</p>
</article>
<article class="card link-card">
<h3><a href="/problems/">Error conditions</a></h3>
<p>
Five conditions a rejected filter can carry, each with a dereferenceable type URI for
RFC 9457 Problem Details.
</p>
</article>
<article class="card link-card">
<h3><a href="${SITE.repo}/blob/main/COMPARISON.md" rel="noopener">Compared with GraphQL</a></h3>
<p>
What this overlaps with, what it deliberately does not, and what a JSON-Schema-native
alternative would still need. The gaps are admitted in writing.
</p>
</article>
</div>
</div>
</section>
<section class="band status-band">
<div class="wrap narrow">
<h2 class="section-title">Honest status</h2>
<p>
OpenPredicate is <strong>pre-1.0</strong>. The grammar, the operator set and profile grouping,
the null and three-valued semantics and the error model are stable enough to review and to
build against — they are what the schema, the spec and the test suite pin down. The grammar may
still change before 1.0, and every break is recorded in the
<a href="/changelog/">changelog</a> with a migration note.
</p>
<p>
What is reachable today: the schema is served from the URL that identifies it, as
<code>application/schema+json</code> with permissive CORS and immutable caching, so you can
<code>$ref</code> it by URL. The package is published as
<a href="https://www.npmjs.com/package/@open-predicate/open-predicate" rel="noopener"><code>@open-predicate/open-predicate</code></a>
if you would rather vendor the file. Pin the versioned <code>$id</code> either way — it never
moves, and an unversioned one does not exist.
</p>
<p class="muted">
Stewarded by the <a href="${SITE.org}" rel="noopener">OpenPredicate</a> organisation, whose
purpose is to take this grammar to an open standard and push for its adoption. Disagreement is
the most useful contribution at this stage —
<a href="${SITE.repo}/issues" rel="noopener">open an issue</a>.
</p>
</div>
</section>
`;
}