Guide

How to design a search API

Every search endpoint faces the same five decisions, and most of them get made by accident. This is what each one costs, and what the OpenPredicate specification settles so you do not have to settle it again.

1. Where the filter goes

A query string is fine while filters stay flat. The moment someone needs available cats and dogs, or any rescue born since 2020, there is no natural way to write that as key–value pairs, and the usual response is to invent a small language inside one parameter:

GET /pets?q=status:open AND (species:cat OR tags:rescue)

That string is now an API surface with no schema, no validator and no generated client. The alternative is a JSON body, which nests for free and can be described by a schema:

{
  "filter": {
    "$and": [
      { "status": "available" },
      { "born": { "$gte": "2020-01-01" } }
    ]
  },
  "sort": [{ "field": "born", "direction": "desc" }],
  "limit": 50,
  "cursor": "eyJvZmZzZXQiOjUwfQ"
}

Note what is and is not in there. The filter is one member; sorting, pagination and limits are siblings. That separation is deliberate — a predicate is the part every search endpoint has in common, while result shaping differs per resource. OpenPredicate specifies the value of filter and nothing around it, which is what lets one grammar serve endpoints whose results have nothing else in common.

On the method. POST for search is a compromise: it is neither safe nor cacheable, which is why intermediaries cannot help you. RFC 10008 defines QUERY — a method that takes a body and is safe and cacheable. Where your stack supports it, it is the right answer; where it does not, POST /…/search is the conventional fallback. Keep the body identical between them.

2. What the filter says

Once the filter is JSON, it needs a grammar. The parts that decide whether that grammar survives contact with a real API are rarely the operators:

OpenPredicate answers these in the specification: evaluation is three-valued, so a comparison against a missing field is UNKNOWN and only TRUE matches; nesting is explicit rather than precedence-based; coercion is defined; and there are stated safety limits. The grammar itself is one JSON Schema file with no dependencies, so a client can validate before sending.

The one that surprises everyone. {"status": {"$ne": "archived"}} does not match a record that has no status at all. Not-equal against a missing field is UNKNOWN, and UNKNOWN is not a match. This is SQL's behaviour; the point of writing it down is that $unknownAs then lets a clause opt out on purpose rather than by accident.

3. How it is described

A search endpoint now has two audiences — developers reading an OpenAPI document, and models being handed a tool. Because the grammar is a JSON Schema, both are a $ref.

In an OpenAPI document

Reference the schema from the request body. The filter becomes part of the contract: it validates in CI, and generated clients get types for the one part users most often get wrong.

paths:
  /pets/search:
    post:
      summary: Search pets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [filter]
              properties:
                filter:
                  $ref: 'https://openpredicate.tech/schema/v0.4.0/open-predicate-schema.json'
                limit:
                  type: integer
                  maximum: 200

The failure mode to avoid is typing filter as a bare object, or as a string holding a bespoke expression. Either way the document describes the envelope and says nothing about the contents.

As an MCP tool's inputSchema

A tool that takes query: string makes the model guess a syntax and leaves you parsing whatever it guessed. A tool whose inputSchema spells out the grammar gives the model something to aim at and gives you something to validate against before the filter reaches a database.

{
  "name": "search_pets",
  "description": "Find pets matching a filter.",
  "inputSchema": {
    "type": "object",
    "required": ["filter"],
    "properties": {
      "filter": { "$ref": "https://openpredicate.tech/schema/v0.4.0/open-predicate-schema.json" },
      "limit": { "type": "integer", "maximum": 200 }
    }
  }
}

Every operator in the schema carries a description, so the instructions travel with the contract instead of being duplicated into a prompt that drifts. The operator reference is generated from those same descriptions — it is the grammar describing itself.

4. What this endpoint actually serves

No endpoint serves the whole grammar over every field. Regular expressions over an unindexed column are a table scan; a date range on a partition key is cheap. So a server has to say which slice it serves, and the honest place for that is a capability document rather than prose in a wiki.

{
  "queryLanguage": "https://openpredicate.tech/schema/v0.4.0/open-predicate-schema.json",
  "profiles": ["core", "strings", "ranges"],
  "fields": {
    "status": {
      "operators": ["$eq", "$ne", "$in"],
      "type": "string",
      "values": ["available", "pending", "sold"]
    },
    "born": {
      "operators": ["$gt", "$gte", "$lt", "$lte", "$between"],
      "type": "string",
      "format": "date-time"
    }
  }
}

This is what lets a client narrow a filter before sending it, and it is the document you hand a model as context. In OpenPredicate the unit a server advertises is the profile: core is required of every implementation, the rest are optional and named. Serving only part of a profile is allowed — advertising it in that case is not.

5. How you say no

A filter you cannot serve deserves a better answer than 400 Bad Request. The client's next move depends entirely on why: a malformed filter is a bug to fix, an unknown field may be a typo, and an unsupported operator means fall back to a different query. Collapsing all three into one status forces a guess.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://openpredicate.tech/problems/unsupported-operator",
  "title": "Unsupported operator",
  "status": 400,
  "detail": "The operator $regex is not served on this endpoint.",
  "pointer": "/filter/$and/1/title/$regex"
}

OpenPredicate names five conditions and gives each a type URI that dereferences to its own explanation — paste it from a log and you land on the page. The pointer is an RFC 6901 JSON Pointer into the request body, because a client facing a dozen nested clauses otherwise has no way to know which one to change.

A checklist

• The filter is a JSON object in the body, not a bespoke string in a query parameter.
• Filtering is separate from sorting, pagination and projection.
• The grammar is a schema you can $ref, and it is pinned by version.
• Missing-field behaviour is written down, not left to each implementation.
• There is a stated bound on nesting depth and filter size.
• The endpoint publishes which operators and fields it accepts.
• A rejection says which of a known set of conditions applies, and points at the clause.
• The same grammar serves your HTTP API and your agent tooling.

If you would rather not decide all of that yourself, that list is what the specification is. You can try a filter in the browser against the real grammar, or $ref the schema and start.

Questions people actually ask