Module model

Client-driven 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:

Model — Resource projection
Query — Collection query
ValuesModel — Property projection specs
ValueModel — Model value
LocalModel — Single-valued language-tagged model
LocalsModel — Multi-valued language-tagged model
Binding — Named computed expression
Expression — Computed expression
Options — Constraint option set
Option — Constraint option

Defines structures for programmatic query key handling:

Criterion — Query criterion
Operator — Constraint operator symbols

Defines value transformation infrastructure:

Transforms — Standard transformations registry
Transform — Value transform

Retrieval Patterns

Resource Retrieval

A Model 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 model: Model = {
  id: "",               // resource identifier
  name: "",             // string property
  price: 0,             // numeric property
  available: true,      // boolean property
  vendor: {             // nested resource
    id: "",
    name: ""
  }
};

Collection Retrieval

A Query extends Model with filtering, ordering, and pagination criteria for collections. 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 model: Model = {
  items: [{                                 // collection query
    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
  }]
};

Localized Content

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

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

Computed Properties

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

Plain transforms operate on individual values:

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

Aggregate transforms operate on collections:

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

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: Model = {
  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: Model = {
  items: [{
    "min=min:price": 0,
    "max=max:price": 0
  }]
};

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

// Total product count

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

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

Model 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 Model objects using operator key prefixes.

Form Serialization

Warning

Form serialization specifies only query constraints; servers are expected to convert to a model by wrapping inside the target endpoint's collection property and providing a default projection.

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

This query:

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

Model Grammar

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

Expressions

Criterion keys identify properties or computed values combining an optional result name (forming a Binding), a pipeline of Transforms, and a property path (Expression):

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

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)

Values

Values are serialized as JSON primitives:

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

IRIs are serialized as strings
Localized strings in Local or Locals maps 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

Warning

Numeric-looking values like 123 are parsed as numbers unless quoted.

Variables

Transforms: Standard value transformations for computed expressions.

Type Aliases

Model: Resource projection.
Query: Collection query.
ValuesModel: Property projection specs.
ValueModel: Model value.
LocalModel: Single-valued language-tagged model for internationalised text.
LocalsModel: Multi-valued language-tagged model for internationalised text.
Binding: Named computed expression.
Expression: Computed expression.
Options: Constraint option set.
Option: Constraint option.
Criterion: Query criterion.
Operator: Constraint operator symbols for Query keys.
Transform: Value transform.

Guards

Type guards for runtime validation of query and value types.

isModel: Checks if a value is a Model.
isQuery: Checks if a value is a Query.
isValuesModel: Checks if a value is a ValuesModel.
isValueModel: Checks if a value is a ValueModel.
isLocalModel: Checks if a value is a LocalModel.
isLocalsModel: Checks if a value is a LocalsModel.
isBinding: Checks if a value is a Binding.
isExpression: Checks if a value is an Expression.
isOptions: Checks if a value is an Options.
isOption: Checks if a value is an Option.
isCriterion: Checks if a value is a Criterion.
isOperator: Checks if a value is an Operator.
isTransform: Checks if a value is a Transform.

Codecs

Functions for converting between serialized and structured representations.

encodeQuery: Encodes a query as a URL-safe string.
decodeQuery: Decodes a query from a URL-safe string.
encodeCriterion: Encodes a criterion as a Query key string.
decodeCriterion: Decodes a Query key string into a criterion.