Client-driven resource retrieval.

Defines types for specifying what data to retrieve in REST/JSON APIs, including property selection, linked resource expansion, and—for collections—filtering, ordering, and pagination:

• Query — Resource retrieval query
• Model — Property value specification
• Expression — Computed expression for transforms and paths
• Transforms — Standard value transformations

Provides utilities for converting between serialized and structured representations:

• encodeQuery / decodeQuery — codecs for URL-safe query strings
• encodeCriterion / decodeCriterion — codecs for Query criterion keys

Query Patterns

Resource Queries

A Query specifies which properties to retrieve from a single Resource and how deeply to expand linked resources. No over-fetching of unwanted fields, no under-fetching requiring additional calls:

const query: Query = {
  id: "",               // resource identifier
  name: "",             // string property
  price: 0,             // numeric property
  available: true,      // boolean property
  vendor: {             // nested resource
    id: "",
    name: ""
  }
};
Copy

Collection Queries

Collection queries are nested inside a managing resource that owns the collection, following REST/JSON best practices. Singleton array projections retrieve filtered, sorted, and paginated results with arbitrarily deep expansions in a single call - no over-fetching, no under-fetching:

const query: Query = {
  items: [{                                 // collection owned by parent
    id: "",
    name: "",
    price: 0,
    vendor: { id: "", name: "" },           // nested resource
    ">=price": 50,                          // price ≥ 50
    "<=price": 150,                         // price ≤ 150
    "~name": "widget",                      // name contains "widget"
    "?category": ["electronics", "home"],   // category in list
    "^price": 1,                           // sort by price ascending
    "^name": -2,                            // then by name descending
    "@": 0,                                 // skip first 0 results
    "#": 25                                 // return at most 25 results
  }]
};
Copy

Localized Content

For multilingual properties, use TagRange keys to select language tags to retrieve:

const query: Query = {
  id: "",
  name: { "*": "" },                   // all available languages
  description: { "en": "", "fr": "" }, // English or French
  keywords: { "en": [""], "fr": [""] } // multi-valued, English or French
};
Copy

Computed Properties

Queries can define computed properties using expressions combining property paths with Transforms.

Plain transforms operate on individual values:

const query: Query = {
  id: "",
  name: "",
  price: 0,
  "vendorName=vendor.name": "",       // property path
  "releaseYear=year:releaseDate": 0   // transform
};
Copy

Aggregate transforms operate on collections:

const query: Query = {
  items: [{
    vendor: { id: "", name: "" },    // group by vendor
    "items=count:": 0,               // count of items per vendor
    "avgPrice=avg:price": 0          // average price per vendor
  }]
};
Copy

Faceted Search

Aggregates enable faceted search patterns, computing category counts, value ranges, and totals in a single call:

// Category facet with product counts

const categoryFacet: Query = {
  items: [{
    "category=sample:category": "",
    "count=count:": 0,
    "^count": "desc"
  }]
};

// → { items: [
//      { category: "Electronics", count: 150 },
//      { category: "Home", count: 89 }
//    ]}

// Price range for slider bounds

const priceRange: Query = {
  items: [{
    "min=min:price": 0,
    "max=max:price": 0
  }]
};

// → { items: [{ min: 9.99, max: 1299.00 }] }

// Total product count

const productCount: Query = {
  items: [{
    "count=count:": 0
  }]
};

// → { items: [{ count: 284 }] }
Copy

Query Serialization

Multiple formats are supported for transmission as URL query strings in GET requests:

Mode	Format
json	Percent-Encoded JSON
base64	Base64 encoded JSON
form	Form-encoded

JSON Serialization

Directly encodes Query objects using operator key prefixes.

Form Serialization

Supports application/x-www-form-urlencoded encoding via the form mode. The format encodes queries as label=value pairs where:

• Labels use the same prefixed operator syntax as Query constraint keys
• Each pair carries a single value; repeated labels are merged into arrays where accepted
• Postfix aliases provide natural form syntax for some operators:
  • expression=value for ?expression=value (disjunctive matching)
  • expression<=value for <=expression=value (less than or equal)
  • expression>=value for `>=expression=value (greater than or equal)

Encoding notes:

• Some operator characters are unreserved in RFC 3986 and remain unencoded: ~ (like), ! (all)
• Reserved characters in values are percent-encoded: & (separator), = (key/value), + (space), % (escape)

category=electronics
  &category=home
  &~name=widget
  &price>=50
  &price<=150
  &^price=asc
  &@=0
  &#=25
Copy

This query:

1. Filters items where category is "electronics" OR "home"
2. Filters items where name contains "widget"
3. Filters items where price is between 50 and 150 (inclusive)
4. Sorts results by price ascending
5. Returns the first 25 items (offset 0, limit 25)

Query Grammar

The following grammar elements are shared by both JSON and Form serialization formats.

Expressions

Expressions identify properties or computed values combining an optional result name, a pipeline of Transforms, and a property path:

expression  = ( name '=' )? transform* path?
name        = identifier
transform   = identifier ':'
path        = identifier ( '.' identifier )*
Copy

• Identifiers follow Identifier rules (ECMAScript names)
• Transforms form a pipeline applied right-to-left (functional composition order)
• An empty path computes aggregates over the input collection

name                         // simple property
user.profile.email           // nested property path
total=sum:items.price        // named computed sum
round:avg:scores             // pipeline: inner transform applied first
count:                       // empty path (aggregate over collection)
Copy

Values

Values are serialized as JSON primitives:

value       = primitive | localized
primitive   = null | boolean | number | string
localized   = string '@' tag
Copy

• IRIs are serialized as strings
• Localized strings (Dictionary) combine a value with a language tag suffix (e.g., "text"@en)
• The encoder always produces double-quoted strings; the decoder accepts unquoted strings as a shorthand