MyJackfruit

Help
Browse topics · Reading and writing records

Reading and writing records

← Back to How can my app build its fields from the vocabulary?

How do I write values of each kind (encodings)?

Short answer

Read the term's a:encoding and a:cardinality in GilbVeda, write each value in that shape, and read many-valued terms as lists.

Before you start

Your app can create and change records in a vault; the answer on writing a record and reading it back shows how.

Words used here (1)
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
Steps
  1. Read the term in GilbVeda.

    Send GET https://veda.gilb.com/base/a/<name>, such as https://veda.gilb.com/base/a/title for a:title, with no token, and read a:encoding and a:cardinality.

    More about this

    GilbVeda is the shared list of terms every app uses. a:encoding says how a value is written; a:cardinality says whether a record may hold one value, single, or several, such as multi. A name GilbVeda does not have answers 404. Read the term rather than keep your own list: the term is the one authority, and it can change.

  2. Write each value in the shape a:encoding names.

    Put the value in facts, in the shape below, in a create, a PUT or a PATCH.

    More about this

    inline-literal:integer: a bare whole number, such as 7. inline-literal:decimal: a bare number that may have a fraction, such as 0.18. inline-literal:boolean: true or false. These three are never text and never a list. inline-literal:text: a JSON string. inline-literal:token: a string from the term's a:valueSet, its list of allowed values. inline-literal:date: an ISO 8601 date, or a UTC time ending in Z. inline-literal:uri: a string holding one address. inline-literal:json: a JSON list or a JSON object. inline-literal:uri-or-uri-array: one address as a string, or two or more as a list of strings. reference: a link, {@id: <address>}.

  3. Read a many-valued term as a list.

    For a term whose a:cardinality is multi, or multi-parent (a term, such as a:partOf, that may link to several records), make a list yourself: no value is the empty list, one bare value becomes a list of one, and a list stays as it is.

    More about this

    GilbPlatform keeps such a term as a list, but when it holds one value the answer can show that value alone, as in jobTitle:Consultant, and a record with none can leave the term out. A loop over the values then runs over the letters of a text, or fails on an object. For a single term, use the value as it comes. A term that names no a:cardinality, such as a:title, can come either way: accept one value or a list. If you cannot read the term, treat it as unknown; do not guess.

Deeper

Also asked:

How do I write dates, numbers, links and lists in the right shape? Read the term's a:encoding in GilbVeda. A date is an ISO 8601 date, such as 1961-03-14; a number is bare, such as 7 or 0.18, never text; a link is {@id: <address>}; a list is a JSON list. Step 2 lists the main shapes.

GilbPlatform does not check a value against its term's encoding: it stores it as you send it, so a number sent as text is stored as text, and other apps then read it wrong. The one exception is a:partOf: an address sent there as a bare string is stored as a link, {@id: …}, and a misspelt address of a record you may read is corrected. A null value is refused with 400 InvalidDatomError; to remove a fact, send it as null in a PATCH, or leave it out of a PUT.

GilbVeda has more encodings than the list in step 2, and the list grows. On 2026-11-11 the term a:encoding also named inline-literal:date-or-month-day, used by a:birthday: 1961-03-14 when the year is known, --03-14 when it is not. a:partOf, with a:cardinality multi-parent, has the encoding reference:node-or-node-array: one link, or a list of links. Read an encoding you do not know as unknown, and write nothing under it until you know its shape. Changes to GilbVeda only add: a new value in a set, a new example; a change that would make apps read their data differently is not made this way.

The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.Vocabulary, https://appbuilder.gilb.com/base/e/06gkzpwtj1wm58yf6zng0xdtbm, and Dev.Guide.Sync, https://appbuilder.gilb.com/base/e/06gkzpwqkxz1h5002g87j1p3x0. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/write/canonical.ts:18-31 (DatomValue: string, number, boolean, object, list; JSON null is not one); src/write/ingest.ts:307-328 (assertNoNullFacts: 400 "Attribute '<a>' has a null value; datoms cannot assert null — omit the attribute or retract it"), :1438-1443 (where it is called); src/lws/crud.ts:459-528 (lwsMergePatch), :530-551 (applyMergePatch: a null member removes the fact); the code at 498d29a0 in src/write and src/lws shows only src/write/full-carry.ts:51 (a comment) and src/write/type-capability.ts:17 (checks values only on the importer's a:capableOf path, :57-130), neither a check of a value against its encoding; src/write/part-of-door.ts:1-30 (a:partOf: a bare http(s) address becomes {@id}, a misspelt address of a stored record the writer may read is corrected; called from src/lws/crud.ts:60, :353, :505 and src/routes/write.ts:87-89). Public GilbVeda reads, no token, 2026-11-11: https://veda.gilb.com/base/a/encoding 200 (keys a:encoding, a:cardinality on term answers; a:valueSet holds 11 values: the 10 of the Guide plus inline-literal:date-or-month-day; example on t/Birthday: '1961-03-14' when the year is stated, '--03-14' when it is not). Dev.Guide.Vocabulary (A 06gkzpwtj1wm58yf6zng0xdtbm, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied); Dev.Guide.Sync (A 06gkzpwqkxz1h5002g87j1p3x0, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied) Vocabulary.Find (https://veda.gilb.com/base/a/<name>; 404 for an unknown name), .Encodings (the ten encodings and their shapes; integer, decimal and boolean are never a string and never a list, verified 2026-10-15), .Lists (Accept both), .Additive; Sync.ManyValues (jobTitle:Consultant verified 2026-10-21; multi -> list, single -> as sent; Ask the term ... it can change; do not guess). The code examples are written here, placeholders only. Rows: Developer.ValueEncodings, HandleManyValuedTerms.

For developers

TypeScript

term-shape.ts

// Ask GilbVeda how a term's value is written and how many values a record may hold. No token is needed.
// name is the term without "a:", such as "title" for a:title.
export async function termShape(name: string): Promise<{ encoding?: string; cardinality?: string }> {
  const res = await fetch(`https://veda.gilb.com/base/a/${encodeURIComponent(name)}`);
  if (res.status !== 200) throw new Error(`term ${name} answered ${res.status}`);
  const term = (await res.json()) as Record<string, unknown>;
  const text = (key: string) => (typeof term[key] === "string" ? (term[key] as string) : undefined);
  return { encoding: text("a:encoding"), cardinality: text("a:cardinality") };
}

// Read a many-valued fact as a list, whether the record holds none, one or several values.
export function asList<T>(value: T | T[] | undefined): T[] {
  if (value === undefined) return [];
  return Array.isArray(value) ? value : [value];
}

curl

values.sh

# A text value and a link, each in the shape its term names.
curl -i -X POST "https://<name>.gilb.com/lws/vault/<encoded vault id>/c" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this POST and this address>" \
  -H "content-type: application/json" \
  -d '{"type":"t:Note","facts":{"a:title":"<a title>","a:partOf":{"@id":"https://<name>.gilb.com/vault/e/<record id>"}}}'

Checked against GilbApp d529620.