Models

Defining your model

To define a model, start with buildModel(), then define your model’s Properties by repeated calls to .addProperty() on the return value:

profile-model.ts

import { buildModel, type ModelValue } from "benno";

export type ProfileThing = ModelValue<typeof profileModel>;
export const profileModel = buildModel()
  .addProperty({
    alias: "podRoot",
    property: "http://www.w3.org/ns/pim/space#storage",
    type: "url",
    required: true,
  })
  .addProperty({
    alias: "name",
    property: "http://xmlns.com/foaf/0.1/name",
    type: "string",
    required: false,
  });

addProperty takes one argument, an object with the following possible keys:

property

Required	Type
Yes	String

The URL of the Property you’re defining.

Tip

Having to type the full Property URLs can be tedious. Helpfully, the rdf-namespaces package exports a set of common Property URL strings. For example:

import { space, foaf } from "rdf-namespaces";

// http://www.w3.org/ns/pim/space#storage
console.log(space.storage);
// http://xmlns.com/foaf/0.1/name
console.log(foaf.name);

type

Required	Type
Yes	Any of the following literal strings: "string", "stringWithLocale", "url", "integer", "decimal", "boolean", "date", "time", "datetime"

The expected data type of the Property’s values. Values of different types will be ignored.

alias

Required	Type
No	String

The key you want to use to access the Property’s value on the validated JavaScript object.

If left out, will be derived from property by taking either the fragment identifier (the bit after #) or, if there is no fragment identifier, the last path part. For example, "http://www.w3.org/ns/pim/space#storage" would default to "storage", and "http://xmlns.com/foaf/0.1/name" would default to "name".

required

Required	Type
No	Boolean

Whether only Things with this Property set will be considered valid.

multipleValues

Required	Type
No	Boolean

Whether to expect multiple values for this Property. If true, the resulting JavaScript object will have an array for this Property.

Caution

While Properties can have multiple values, the order of these values is not guaranteed! Likewise, if your model specifies that a Property should only have a single value, but the actual data lists multiple values, any of those values can be selected as the value that gets returned.

Fetching and storing data

When your model is defined, it offers several methods to interact with data on an actual Solid Pod.

.fetchOneFrom(url, options)

Fetches a Thing that matches the model definition.

Parameters

url

Required	Type
Yes	String

URL of the Thing to fetch.

options

Required	Type
No	{ fetch?: typeof fetch }

Optionally allows passing a custom fetch function. Primarily used to send authenticated requests.

Return value

A Promise resolving to a Thing that matches the model definition, or null if no such Thing was found at the given URL.

.fetchAllFrom(url, options)

Fetches all Things in a given Dataset that match the model definition.

Parameters

url

Required	Type
Yes	String

URL of the Dataset containing the Things you want to fetch.

options

Required	Type
No	{ fetch?: typeof fetch }

Optionally allows passing a custom fetch function. Primarily used to send authenticated requests.

Return value

A Promise resolving to the Things in the Dataset at the given URL that match the model definition, if any.

.saveAllTo(things, url, options)

Given Things that match the model definition, stores them at the given URL, replacing existing data.

Parameters

things

Required	Type
Yes	Array of Things matching the given model definition

The Things you want to store in the user’s Pod.

url

Required	Type
Yes	String

URL you want to save the things to.

Caution

All existing data at the given URL will be overwritten.

options

Required	Type
No	{ fetch?: typeof fetch }

Optionally allows passing a custom fetch function. Primarily used to send authenticated requests.

Return value

A Promise resolve to the Things as saved to the Dataset at the given URL.

Compatibility with @inrupt/solid-client

Benno is built on top of @inrupt/solid-client, and can seamlessly interoperate with it. This makes it easy to adopt Benno in applications that already use solid-client.

To do so, models offer a number of methods that let you extra Things from Datasets, or convert solid-client Things into the plain JavaScript objects that are validated by Benno.

.getOneFromDataset(dataset, url)

Given a SolidDataset from solid-client, find a Thing with the given URL that matches the model definition, and return it.

Parameters

dataset

Required	Type
Yes	SolidDataset (from @inrupt/solid-client)

A SolidDataset as provided by @inrupt/solid-client.

url

Required	Type
Yes	String

URL of the Thing to fetch from the given Dataset.

Return value

A Thing matching the model definition, or null if no such Thing was present with the given URL in the given Dataset.

.getAllFromDataset(dataset)

Given a SolidDataset from solid-client, find all Things that match the model definition, and return them.

Parameters

dataset

Required	Type
Yes	SolidDataset (from @inrupt/solid-client)

A SolidDataset as provided by @inrupt/solid-client.

Return value

An array of Things matching the model definition.

.insertIntoDataset(dataset, things)

Given a SolidDataset from solid-client and one or more Things that match the model definition, return a new Dataset that includes the given Things.

Parameters

dataset

Required	Type
Yes	SolidDataset (from @inrupt/solid-client)

A SolidDataset as provided by @inrupt/solid-client.

things

Required	Type
Yes	Thing (from @inrupt/solid-client), or an array of Things

A Thing matching the model definition, or an array of such Things.

Return value

A new SolidDataset that includes the given things.

.removeFromDataset(dataset, things)

Given a SolidDataset from solid-client and one or more Things that match the model definition, return a new Dataset that does not include Things identified by the given Things’ URLs.

Parameters

dataset

Required	Type
Yes	SolidDataset (from @inrupt/solid-client)

A SolidDataset as provided by @inrupt/solid-client.

things

Required	Type
Yes	Thing (from @inrupt/solid-client), or an array of Things

A Thing matching the model definition, or an array of such Things.

Return value

A new SolidDataset that does not include Things with the URLs of the given things.

.toThing(thing, options)

Given an object that matches the model definition, return a new Thing as used by @inrupt/solid-client that represents the same data.

Parameters

thing

Required	Type
Yes	An object matching the model definition.

A Thing matching the model definition.

options

Required	Type
No	{ name: string } or { url: string }

An object with either the property name or the property url. If a name is given, the Thing’s URL will be based on the URL it gets saved on, with name forming the fragment identifier. If a url if given, that URL will be used. If neither is given, either the URL of the given Thing will be used (if known), or a random fragment identifier will be assigned.

Return value

A Thing as used by @inrupt/solid-client.

.fromThing(thing)

Given a Thing as provided by @inrupt/solid-client, return an object matching the model definition.

Parameters

thing

Required	Type
Yes	Thing (from @inrupt/solid-client)

A Thing as provided by @inrupt/solid-client.

Return value

An object matching the model definition, with the data contained in the given thing, or null if the data does not conform to the model definition.