Client-driven resource retrieval.

Defines types for specifying the data envelope to retrieve in REST/JSON APIs, including property projection, linked resource expansion, and, for collections, filtering, sorting, and pagination.

Retrieval model

• Template — Resource retrieval template
• Projection — Collection property projection
• Slot — Template value model
• Cell — Projection value model
• Placeholder — Property value template
• Atomic — Atomic value template
• Locale — Localised text map template (structured language-tagged value)
• Union — Union-typed property template
• Branch — Union branch key
• Query — Constrained retrieval node
• Criteria — Collection retrieval constraints
• Binding — Named computed expression
• Expression — Computed expression
• Pipe — Transform pipe
• Path — Property path
• Options — Constraint option set
• Option — Constraint option
• Probe — Parsed Criteria or Projection key
• Operator — Constraint operator symbols
• Order — Sort order direction and precedence
• Transform — Value transforms for computed expressions
• Aggregate — Aggregate transform
• TransformSignature — Static typing profile of a Transform
• Transforms — Signature table covering every Transform

Type guards

• isTemplate — checks if a value is a Template
• isProjection — checks if a value is a Projection
• isSlot — checks if a value is a Slot
• isCell — checks if a value is a Cell
• isPlaceholder — checks if a value is a Placeholder
• isAtomic — checks if a value is an Atomic
• isLocale — checks if a value is a Locale
• isUnion — checks if a value is a Union
• isBranch — checks if a value is a Branch key
• isQuery — checks if a value is a Query over a given retrieval form
• isCriteria — checks if a value is a Criteria
• isCriterion — checks if an entry is a valid Criteria entry
• isSelector — checks if a value is a Criteria constraint key
• isBinding — checks if a value is a Binding
• isExpression — checks if a value is an Expression
• isOptions — checks if a value is an Options set
• isOption — checks if a value is an Option
• isOrder — checks if a value is an Order
• isProbe — checks if a value is a Probe
• isOperator — checks if a value is an Operator
• isTransform — checks if a value is a Transform
• isAggregate — checks if a value is an Aggregate

Accessors

• getOrderPrecedence — resolves an Order to its sort precedence
• getOrderDirection — resolves an Order to its sort direction

Codecs

• encodeTemplate — encodes a Template as URL-safe JSON
• decodeTemplate — decodes a Template from URL-safe JSON
• encodeCriteria — encodes a Criteria as a form-urlencoded string
• decodeCriteria — decodes a Criteria from a form-urlencoded string
• encodeProbe — encodes a Probe as a key string
• decodeProbe — decodes a Probe from a key string

Retrieval Patterns

Resource Retrieval

A Template 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 template: Template = {
  id: {},               // resource identifier
  name: {},             // string property
  price: {},            // numeric property
  available: {},        // boolean property
  vendor: {             // nested resource, expanded
    id: {},
    name: {}
  }
};
Copy

Every request is an object and every leaf is {}, the Atomic standing for the value as it comes: a literal, the reference of a linked resource left unexpanded, or the coalesced label of a localised property. A template carries no data of its own, so what a client writes is a pure statement of what it wants back. The empty request {} states nothing and brings back the server defaults.

Collection Retrieval

A collection is reached through the resource that owns it, following REST/JSON practice, and is constrained there: the entry naming it carries the Criteria keys that filter, sort, and paginate it alongside the per-item keys. A single call retrieves filtered, sorted, and paginated results with arbitrarily deep expansions:

const template: Template = {
  items: {

    id: {},                                // per-item keys
    name: {},
    price: {},
    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

Cardinality is not stated by the notation: the same entry shape serves a single-valued and a multi-valued property, and which one a field names is settled by the model. Constraints are simply meaningless on a single-valued property and are rejected there.

Localised Properties

A localised property is retrieved in either of two ways. An Atomic yields its coalesced label, the plain string resolved under the request's negotiated language priority; a Locale map yields the tagged values structurally, as a Dictionary restricted to the locales its TagRange keys select:

const template: Template = {
  id: {},
  label: {},                          // coalesced under language negotiation
  title: { "*": {} },                 // all available languages
  description: { "en": {}, "fr": {} } // English and French
};
Copy

The TagRange keys are RFC 4647 basic language ranges that filter which locales populate the map (the standalone * matches every tag, and a plain range such as en also matches more specific tags like en-US). Per-tag cardinality follows the property, not the template. Tag ranges select retrieved content only and are independent of Criteria: a Locale map carries TagRange keys, never constraint keys. Resource matching by localised text is done separately, at the enclosing collection via ?/!.

Computed Properties

Projections can define computed properties using expressions combining property paths with Transform.

Plain transforms operate on individual values and may project literals, linked resource references, nested templates expanding a linked resource inline, or Locale tag-range maps declaring a localised cell that yields a complete Dictionary value per row:

const projection: Projection = {
  "id=id": {},
  "name=name": {},
  "price=price": {},
  "vendorName=vendor.name": {},              // property path
  "releaseYear=year:releaseDate": {},        // transform
  "vendorRow=vendor": { id: {}, name: {} },  // nested template
  "label=title": { "*": {} }                 // localised cell (full Dictionary value per row)
};
Copy

A projection emits distinct rows: rows with the same combination of cell values collapse into one, so the result is the set of distinct binding tuples rather than a multiset. Distinctness spans the whole collection, folding both multi-valued fan-out duplicates and equal tuples from different items; include an identifying binding such as id (as above) to keep otherwise-equal items on separate rows.

Aggregate Grouping

Aggregate transforms operate on sets of values. A collection is evaluated under grouped semantics when at least one Projection binding resolves to an aggregate Expression; otherwise it stays ungrouped, every item is projected on its own, and an aggregate constraint reduces over the values its path gathers from the item under evaluation, filtering, sorting, or ranking the items by that reduction.

Under grouped semantics, each operator's role is determined by whether its expression references an aggregate transform:

• Projection bindings — non-aggregate bindings contribute to the grouping key and appear verbatim in the output row; aggregate bindings compute per-group summaries
• Filter constraints — non-aggregate filters restrict the input set before grouping; aggregate filters select groups after aggregation
• Ordering expressions — a non-aggregate ordering expression sorts the groups by one of the grouping keys; an aggregate ordering expression sorts them by its post-aggregation value

Grouping is fixed by the projection alone and is never inferred from a sort key: a non-aggregate ordering expression MUST reference an existing grouping key, and processors MUST reject one that matches none.

Rows sharing the same grouping-key values collapse into a single group. Aggregate filter and ordering constraints are independent of any projected bindings: an aggregate may appear in a constraint without being projected, and a projected aggregate may appear without being constrained.

Aggregate expressions use bag semantics over their inputs: count: (empty path) returns the number of rows in scope; a non-empty path (for example, sum:price) ranges over the values resolved by the path for each input row, with multi-valued path fan-outs contributing every resolved value individually. No implicit deduplication is applied: clients needing distinct-value aggregates project the value of interest as a non-aggregate grouping binding.

const template: Template = {
  items: {
    "vendor=vendor": { id: {}, name: {} },  // group by vendor
    "items=count:": {},                     // count of items per vendor
    "avgPrice=avg:price": {}                // average price per vendor
  }
};
Copy

The ungrouped reduction states cardinality constraints over a plain template, retrieving the vendors carrying at least three products:

const template: Template = {
  vendors: {
    id: {},
    name: {},
    ">=count:products": 3
  }
};
Copy

See Aggregate Transforms for the transform catalogue and cross-backend semantics.

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: Template = {
  items: {
    "category=category": {},
    "count=count:": {},
    "^count:": "desc"
  }
};

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

// Price range for slider bounds

const priceRange: Template = {
  items: {
    "min=min:price": {},
    "max=max:price": {}
  }
};

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

// Total product count

const productCount: Template = {
  items: {
    "count=count:": {}
  }
};

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

Union Branches

For properties whose declared range is a union type, a Union declares per-branch retrieval by mapping opaque keys to the Placeholder to fetch for each variant of interest. The keys carry no positional or nominal meaning: the variant a placeholder retrieves is fixed by matching it against the property's declared variants, and an unmatched variant is skipped at runtime. Branch out only where the alternatives want different shapes; where one shape serves them all, a plain Placeholder addresses the property directly:

const template: Template = {
  id: {},
  creator: {
    "0": { id: {}, name: {} },       // a person-shaped branch
    "1": { id: {}, legalName: {} }   // an organisation-shaped branch
  }
};
Copy

Expressions

A Projection Binding key pairs a result name with a computed value: a pipeline of Transform and a property path (together an Expression). The result name and its = are mandatory; a bare identifier is not a binding:

binding     = name '=' expression
name        = identifier
expression  = transform* path?
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

vendorName=vendor.name       // named nested property path
total=sum:items.price        // named computed aggregate
result=round:avg:scores      // pipeline: inner transform applied first
count=count:                 // empty path (aggregate over the collection)
Copy

Value Ordering

Comparison (<, >, <=, >=) and sort (^) operators rely on a total ordering over values defined by the XPath 2.0 comparison operators, which are in turn based on XSD ordered value spaces. These operators, along with sort focus (+), target Literal values only; Reference values, nested Template resources, and Dictionary values are neither comparable nor sortable:

• null — undefined values sort before all defined values
• boolean — false < true
• number — standard numeric ordering; NaN is unordered
• string — Unicode codepoint collation

Result Typing

A template says what to retrieve, not what the retrieved values are: an Atomic leaf stands for whatever the property holds, so a template alone cannot tell a string property from a number one. Result types come from the declared model instead. The keys a client writes and the keys it reads back differ too: Criteria constraints carry nothing back, and a Binding lands under its result name, the part before the =.

Serialisation

Template Serialisation

Template objects are serialised as JSON via encodeTemplate / decodeTemplate, with IRI internalisation and resolution handled transparently. The encoder emits plain JSON by default and optionally URL-encoded JSON or URL-safe base64url-encoded JSON for transport; the decoder auto-detects the input encoding.

Criteria Serialisation

Criteria objects are serialised as application/x-www-form-urlencoded strings via encodeCriteria / decodeCriteria for transmission as URL query strings in GET requests.

The format encodes queries as label=value pairs where:

• Labels use the same prefixed operator syntax as Criteria 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)

Values use JSON primitive syntax, with a Dictionary entry inlined through a single postfix @tag suffix:

value       = null | literal | tagged
literal     = boolean | number | string
tagged      = string '@' tag
tag         = BCP 47 language tag
Copy

• References are serialised as strings
• A string may carry a single @tag suffix, lifting it into a one-entry Dictionary (for example, "text"@en decodes to { en: "text" })
• The encoder always produces double-quoted strings; the decoder accepts unquoted strings as a shorthand

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)