ModelProperty

A model property is the definition of one field on a model: its name, its data type and its options. You declare properties in seed.schema.json (or in Model.create), and the SDK represents each one as a ModelProperty instance. This page covers the definition format first, then the class.

import { ModelProperty, ModelPropertyDataTypes } from '@seedprotocol/sdk'

A model property is a definition. The value stored on one item is an ItemProperty.

Property definition reference

The same options appear in two shapes. The schema file uses type and, for a relation's target, model. Code (Model.create, ModelProperty.create) uses dataType and ref.

"author": { "type": "Relation", "model": "Author", "required": true }

author: { dataType: 'Relation', ref: 'Author', required: true }

A List with neither refValueType nor ref fails to import, with List property "…" in model "…" requires "refValueType".

Data types

Every type except List holds one value; saving an array to any other type fails validation with code array_not_allowed. The ModelPropertyDataTypes enum has a member for each type (ModelPropertyDataTypes.Text is 'Text').

Values passed to create() and values you assign later are both validated. See Item and ItemProperty for reading and writing values.

A Number publishes as its decimal string, so negative numbers, decimals and values above 255 publish. A stored value that isn't a finite number fails publishing with code publish_invalid_number.

What's published where

When you publish an item with @seedprotocol/publish, every property with a value gets its own EAS attestation. 0 and false are values; only null, undefined and '' are skipped. Html, Image and File content is uploaded to Arweave first, and the attestation holds a reference to it. Relation and List of Relation attestations reference the related items' Seed UIDs, so related items need to be published too. See Permanence.

Each attestation uses an EAS schema named after the field type and the property's EAS name. The SDK's easName function (also exported from the main entry) makes that name: it splits words at case changes and before the last capital of an acronym, turns spaces, hyphens and other characters into _, and lowercases the result:

A single Relation, Image, File or Html property is attested as a bytes32 reference under its own name: author: Relation is bytes32 author and cover: Image is bytes32 cover. Locally, its values are stored as authorId, whether you wrote them or they were synced from EAS, and are matched to the property by its row, so they follow a rename. A List of Relation is named from the singular property name, the target model and Ids: authors with ref: 'Identity' becomes author_identity_ids.

Any app whose model has a property with the same name and type reads the same attestations, which is why property names and types shouldn't change once you publish. When syncing, the SDK matches the names on EAS against your property names as loosely as the property's nameMatch allows. By default that ignores case and separators, a plural s and, for relations, a trailing _id, so published_at and PublishedAt both reach a local publishedAt, and older author_id attestations reach author. Sync also checks types: it skips an attestation whose EAS type doesn't fit the local property, with a warning. A Number accepts any uint* or int* type and a numeric string, so values published as uint8 by older versions still sync; every other type accepts only the type it publishes. Synced Number values, and Date values attested as integers, are stored decoded, as a decimal string and an ISO 8601 string.

Since 0.7.4, a few names publish under a different EAS name, and so under different EAS schemas, than earlier versions used: an acronym followed by a word (HTMLPage was htmlpage, now html_page), a digit before a capital (ID3Tag: id3tag, now id3_tag), and names with spaces or hyphens. Plain camelCase and PascalCase names (publishedAt, coverURL, BlogPost) are unchanged. See Migration.

Validation

Rules go under validation on a property:

"title": { "type": "Text", "validation": { "maxLength": 120 } },
"status": { "type": "Text", "validation": { "enum": ["draft", "live"] } }

pattern, minLength and maxLength on any other type (on a List, any element type but Text or Html) are an error with code rule_not_applicable. A schema file with one fails to load before anything is stored, with a message such as Post.wordCount: validation.maxLength only apply to Text and Html properties (this one is Number). Remove it or use enum.

Rules combine: pattern, minLength and maxLength all apply, and enum applies together with them. On a List, the rules apply to each element, and Text elements get the 255-character default.

A value that fails validation isn't saved. Assigning it doesn't throw; awaiting the property's save() throws an ItemPropertySaveValidationError whose validationErrors hold { field, message, code, severity } entries. The codes are type (a value of the wrong type, such as text given to a Number or an object given to a Relation), max_length_exceeded, min_length, pattern, enum_violation, format (a Date value that isn't a date) and array_not_allowed. A value outside the enum gets one enum_violation; one that also misses the pattern gets both. See ItemProperty.

Item.create checks the same rules before it writes a new item, and rejects with ItemCreateValidationError.

Storage

A Text property can keep its value in a file instead of the database:

"notes": {
  "type": "Text",
  "storage": { "type": "ItemStorage", "path": "notes", "extension": ".md" }
}

An ItemStorage value passed to Item.create is written to its file before create resolves.

Html, Image and File are always kept in files, so they don't need storage.

Reserved property names

These names are used for fields the SDK manages on every item. Don't use them as property names:

localId, uid, seedLocalId, seedUid, schemaUid, attestationCreatedAt, attestationRaw, createdAt, updatedAt, lastVersionPublishedAt, latestVersionLocalId, latestVersionUid, lastLocalUpdateAt, modelName, refSeedType, refValueType, refResolvedValue, refResolvedDisplayValue, type, src, alt, versionLocalId, versionsCount, versionUid, _markedForDeletion, publisher, revokedAt.

Also avoid names ending in Id or Ids: the SDK stores relation and file values under those suffixes.

Reserved Solidity words

EAS schemas can't use a word Solidity's ABI reserves, so neither a model nor a property can publish under one:

constructor, error, event, fallback, function, receive, struct, calldata, memory, storage, payable, indexed, tuple, returns, constant, external, internal, private, public, pure, view, override.

The check is on the EAS name, so Returns (which publishes as returns) and a model named Event are refused too. A List of Relation is exempt, because it publishes as <name><Model>Ids.

A schema file or config.schema with such a name doesn't load, and client.init rejects:

Could not load config.schema: Schema blog: Post.view: Property "view" publishes as "view", which EAS schemas can't use (a reserved Solidity ABI word). Rename it.

For a model, the message reads Schema blog: Event: Model "Event" publishes as "event", …. ModelProperty.create with such a name rejects with Failed to write property "view": Property "view" publishes as "view", …, and Model.create rejects with Model "Event" publishes as "event", … or Property "view" publishes as "view", …, whether the name is the model's or one in properties.

Don't rename a property to one of these words either. Assigning name doesn't throw, but the rename isn't saved to the local database and validate() returns isValid: false with an error of code reserved_name. While the bad name stands, saveNewVersion() rejects with the reserved-word message if the schema has other changes, and otherwise resolves with an empty string and saves nothing.

Getting ModelProperty instances

You rarely construct a ModelProperty yourself. A loaded model's properties array holds one for each property:

import { Model, ModelProperty } from '@seedprotocol/sdk'

const Post = await Model.find({ modelName: 'Post', schemaName: 'blog' })
const title: ModelProperty | undefined = Post?.properties.find(
  (property: ModelProperty) => property.name === 'title',
)

Model.properties is typed as any[], so annotate the instances as above. In React, use useModelProperties and useModelProperty; see React model property hooks.

Instance properties

waitForReady({ timeout }) resolves once status is 'ready'. It rejects with the load's error, or after timeout milliseconds (default 15000). While status is 'error', entityLoadError(property) returns that error.

required and validation aren't exposed as fields.

Editing a property

Assigning to name, dataType, ref, refValueType, storageType, localStorageDir or filenameSuffix changes the definition. The SDK validates the new definition and, if it's valid and differs from what was loaded, saves it to the local database and marks the schema as edited. This happens in the background; nothing is thrown, except on a property that was destroyed or evicted, where the assignment throws EntityUnloadedError.

A name that fails validation stays on the instance only: the row keeps the old name, and the instance shows the new one with isEdited: true and the reason in validationErrors. Assigning a valid name clears the errors and saves it.

Item properties that were already loaded don't take an edit made this way: on Node they keep checking new values against the definition they loaded with. A schema change that rewrites the property's row (a new version of the schema file applied, or updateModelProperties) does reach them, so the next value assigned is checked against the new rules.

if (title) {
  title.name = 'headline'
}

ModelProperty.create

Adds a property to a loaded model, or returns the cached instance if that model already has a property with this name.

static create(
  property: {
    name?: string
    dataType: PropertyDataType // 'Text', 'Number', … or a ModelPropertyDataTypes member
    modelName?: string
    ref?: string
    refValueType?: PropertyDataType
    required?: boolean
    storageType?: 'ItemStorage' | 'PropertyStorage'
    localStorageDir?: string
    filenameSuffix?: string
    // …and the other fields of the SDK's TProperty type
  },
  options?: { waitForReady?: true; readyTimeout?: number; schemaName?: string; hold?: boolean },
): Promise<ModelProperty>

The parameter type is simplified; the real type is TypeBox's Static<typeof TProperty>, which isn't exported. Passing { waitForReady: false } returns the instance instead of a Promise; every other call returns a Promise, and is typed that way.

Parameters

Example

import { ModelProperty } from '@seedprotocol/sdk'

const summary = await ModelProperty.create(
  { name: 'summary', dataType: 'Text', modelName: 'Post' },
  { schemaName: 'blog' },
)

When it waits for ready (the default), the Promise resolves once the property's row is written to the local database. It rejects if the write fails, for example with Cannot write property "summary": model Post has no database row when the model isn't in the database, or if the write doesn't finish within readyTimeout. With { waitForReady: false }, write failures are only logged. To define a new model's properties, pass them to Model.create.

Other methods

hold defaults to false on each lookup. A property stays cached and running until it, its model or its schema is destroyed or evicted, whether or not anything holds it; client.stop() evicts every cached property. A hold only counts your use of the instance. Once a property is destroyed or evicted, save() and assignments to its fields throw EntityUnloadedError, whose message names the property and says to look it up again with ModelProperty.find. EntityUnloadedError is exported from the main entry.

The class also exposes bookkeeping helpers used by the SDK (createById, refreshFromDb, holdForModel, evictForModels, evictForModel, trackPendingWrite, clearPendingWrite, getPendingPropertyIds, getPendingModelId). You don't need them in app code.

Data type helpers

Also exported from @seedprotocol/sdk:

Related

• Your first schema: property types in a walkthrough
• File and image properties
• Modeling relations
• Model, Schema and ItemProperty
• React model property hooks