Module index

Linked data validation.

Provides shape-based validation for the values, retrieval templates and retrieved data crossing a service boundary. The schema function describes the payloads a shape admits as a JSON Schema, and the validate function returns either the value, typed as the shape describes it, or a trace of every violation found. A shape states once what a service accepts, so the description and the checks stay in one place instead of being restated across the interfaces and entry points that exchange data with clients.

Shapes are stated with the per-kind modules value gathers:

import { boolean } from '@metreeca/blue/boolean';
import { integer } from '@metreeca/blue/number';
import { id, multiple, optional, required, resource } from '@metreeca/blue/resource';
import { date, string } from '@metreeca/blue/string';

const Product = resource({
  id: id(),
  name: required(string({ minLength: 1, maxLength: 100 })),
  price: required(integer({ minInclusive: 0 })),
  available: optional(boolean()),
  tags: multiple(string()),
  released: optional(date())
});
Copy

Describing a shape as JSON Schema

A shape also declares schema-driven consumers, such as API descriptions, language model tool interfaces and structured output formats, without a hand-written schema restating it. The schema function describes the payloads a resource shape admits as a JSON Schema (draft 2020-12). Its strict variant keeps to the subset of JSON Schema accepted by structured output generators, which reject the keywords and formats outside it:

import { schema } from '@metreeca/blue';

schema(Product);                    // the payloads Product admits
schema(Product, { strict: true });  // the same, for strict structured output generators
Copy

Collecting entry shapes and their dependencies

Model-wide encodings, such as vocabularies, schemas and documentation, cover every shape a set of entry shapes depends on rather than only the entry shapes themselves. The model function collects the entry shapes and the shapes they extend, link to or embed, each once and in a stable order, ready to be encoded as a whole:

import { model } from '@metreeca/blue';
import { id, optional, resource } from '@metreeca/blue/resource';
import { reference } from '@metreeca/blue/reference';

const Vendor = resource({
  id: id()
});

const Offer = resource({
  id: id(),
  vendor: optional(reference(Vendor))
});

model(Offer); // [Offer, Vendor]
Copy

Matching a value against a shape

The same shape answers three questions; the model option settles which is being asked:

import { validate } from '@metreeca/blue';

validate(product, { shape: Product })({                    // a resource in its own right
  value: product => console.log(product.name),
  trace: trace => console.error(trace)
});

validate(response, { shape: Product, model: { name: {} } });  // a retrieval, narrowed by what was asked for
validate(request, { shape: Product, model: true });           // a retrieval template, before it is issued
Copy

• omitted, or false, matches value against the shape as a resource in its own right
• a template matches value against the members that template asked for, and types what comes back accordingly
• true matches value against the shape as a template, asking whether the shape can serve what it requests