MyJackfruit

Help
Browse topics · For developers

For developers

← For developers

How can my app build its fields from the vocabulary?

Short answer

Show the record's own facts, label each from its term, list the field terms of its type, and offer relations from linkPlane=user.

Before you start

Your app holds the token of a person who may read the record; the vocabulary needs no sign-in.

Words used here (6)
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
field
A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
relation
A relation is a named link between two records, such as part-of or connected-to, that says how they are related.
record's type
A record's type says what kind of thing a record is, such as a note, a task or a person, taken from GilbVeda.
agent
An agent is your AI following one written procedure, its standing instructions, for one kind of work.
GilbPlatform
GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
Steps
  1. Make one field for each fact the record holds.

    Read the record as your app already does, with the person's token, and show one field for each fact name in the answer.

    More about this

    A record is one piece of data with its own address, such as a person, a place, a thing or a note. A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda. Take the set of fields from that read, never from a list kept in your app or in a record of its own: then a fact another app wrote shows too, and a fact the person may not read never comes, because the read gives only what they may read. A record of your own may set the order of the fields or the person's own names for them, but it never decides that a field is there. Fact names come back without a:, so a:title reads title.

  2. Label each field from its term.

    Fetch each fact name's term once, with no token, and show its a:label:
    GET https://veda.gilb.com/base/a/<name>

    More about this

    A term is the shared name GilbVeda keeps for a kind of thing, a detail of it, a link between two things, or a species. For a:title that is https://veda.gilb.com/base/a/title, with the label Title. a:encoding says how the value is written, and so which kind of box to show; a:cardinality other than single means one value or a list. The answer on writing values of each kind shows each shape. A term may be kept for an hour. A token field whose term has a:valueSet lists there the words it takes: offer them as the choice list. On 2026-11-11, 13 of the 104 token fields had one. Read an encoding you do not know as unknown, and write nothing under it until you know its shape.

  3. List the fields a record of its type can have.

    Fetch the terms that are fields of some type, with no token, and keep those whose a:fieldOf names the record's type or a type it is a kind of:
    GET https://veda.gilb.com/base/vocab?status=all&carries=a:fieldOf&limit=2000

    More about this

    a:fieldOf often names a broader type than yours: a:title names Definition, the type Note is a kind of. So read the type at https://veda.gilb.com/base/t/<Name>, follow its a:subTypeOf upwards, and collect the types as you go. Write each field under the fact name in its a:predicateAttribute, such as a:title. Leave out a Deprecated term. On 2026-11-11 the list was 655 terms in one page of about 3.4 MB; while complete is false, read the address in next. Offer these as fields the person may add; the record's own facts stay the fields you show, since a:fieldOf is not complete: on 2026-11-11 a:body did not name Note or a type Note is a kind of.

  4. Offer named links from the user plane.

    Fetch the relation terms meant for people, with no token, and offer those with a:isRelationPredicate true:
    GET https://veda.gilb.com/base/vocab?status=all&linkPlane=user

    More about this

    A relation is a named link between two records, such as part-of or connected-to, that says how they are related. Show a:label, and write the link with the term's a:typeAttribute, such as t:ParentOf, never with a value you build from the term's address; the answer on reading relations between records shows how to write a link. Leave out the other planes, process, grant and classification: those are links the system makes. From the other end, a term with a:inverseOf shows the paired term's a:label, child-of for parent-of; a term with a:symmetric true shows its own; any other shows a:inverseLabel. On 2026-11-11 the list held 68 terms: 2 had no a:isRelationPredicate and 12 had no a:typeAttribute.

  5. When no term fits, ask for one.

    Check whether a term already carries the meaning, with the person's token and a new DPoP proof:
    POST https://veda.gilb.com/base/term-requests

    More about this

    A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). The answer on listing, browsing and searching the vocabulary shows this check. On a MISS, Agent.Concept, the agent that finds and makes GilbVeda's terms, makes the term; the answer on minting a term shows how. Until then, do not invent a name and do not put the meaning into another field. In a person's or an organisation's vault a write under a name no term defines is stored today, so GilbPlatform will not catch the mistake for you.

Deeper

Also asked:

Can my app build its form fields from the vocabulary? Yes: show one field for each fact the record's read gives, label each from its term in GilbVeda, and offer the terms whose a:fieldOf names the record's type as fields the person may add.

Why: every app takes its names from GilbVeda, the shared list of terms, so a record one app writes reads the same in every other. GilbVeda grows: a list of field kinds, types, choices or link names kept in your code goes stale, and it hides what other apps wrote. GilbPlatform's own apps are held to the same rule.

Build the fields only from a read made with the person's token. A screen that shows every fact a read gives is safe because that read gives only what the person may read; a copy of the data kept somewhere without that check is not.

The two listings and the term reads need no account, token or proof, and change nothing. status=all lists terms of every status: Approved, Suggested, newer terms not yet approved, and Deprecated; read a Deprecated term's address to find the term that replaces it. carries works only with status=all: without it the answer is 400 CarriesRequiresStatusAll. A linkPlane other than user, process, grant or classification answers 400 UnknownLinkPlane; linkPlane does not go with type, nodeKind, limit or cursor, and carries does not go with type, nodeKind or linkPlane: together they answer 400 SelectorCombinationUnsupported. A term whose a:predicateAttribute holds two names joined by |, such as a:postalAddress|a:address, means one field under either name.

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

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/routes/vocab.ts:905-1085 (GET /base/vocab: status=all opt-in listing; ?carries=<CURIE> predicate-carrier selector, 400 CarriesRequiresStatusAll, CarriesEmpty, SelectorCombinationUnsupported "?carries= takes only limit and cursor beside status=all; it does not combine with type, nodeKind or linkPlane"; ?linkPlane= user|process|grant|classification, 400 UnknownLinkPlane, does not combine with type, nodeKind, limit or cursor; every | spelling of a:predicateAttribute read, RuleBaseattrReadEverySpelling), :823 (GET /base/a/:slug); src/vocab/reference-value.ts:1-40 (five live spellings of a reference encoding; do not key on a:encoding); src/baseconnect/org-card-master.ts:1-80 (the platform's own card reads its fields from the master's a:fieldOf, not from a code list). Public reads, no token, 2026-11-11: https://veda.gilb.com/base/vocab?status=all&linkPlane=user 200, 427,716 bytes, 68 terms (62 Suggested, 6 Approved), 66 with a:isRelationPredicate true (contact and works-for without), 56 with a:typeAttribute; parent-of a:typeAttribute t:ParentOf, a:inverseOf ChildOf, a:genderedLabel female=mother|male=father; ?linkPlane=people 400 UnknownLinkPlane; ?carries=a:fieldOf with no status 400 CarriesRequiresStatusAll; ?status=all&carries=a:fieldOf&limit=2000 200, one page, complete true, 655 terms, 3,416,881 bytes (632 Suggested, 19 Approved, 4 Deprecated); 104 inline-literal:token terms, 14 with a:valueSet; a:title a:fieldOf Definition, Intent, Knowledge, Information, Document, ...; t:Note a:subTypeOf Definition; Person: 18 fields. Reference_Code_gilb-app-relation-picker (A 06gm0seeb5xesfws27myf68kx0, pack GilbPlatform Frontend, 2026-11-11; licence: read and follow inside GilbPlatform, not copied) exhibits Offer (a:isRelationPredicate true and a:linkPlane user; other planes are links the system makes), Fields (a:typeAttribute: write it, do not build it from the address), OtherEnd, Missing; Rule_Code_gilb-vault-native-derivation (A 06gf2qq0vdtw329b71q7kxvd5w, same pack, 2026-11-11) RuleBasepodFieldsFromFacts (fields from the facts in the authorized read; decoration may re-order and re-label, never decide that a member exists), RuleBasepodGateShipsWithInversion (a generic renderer over an authorized read is not a leak), RuleBasepodNoNewEnumeration; Dev.Guide.Vocabulary (A 06gkzpwtj1wm58yf6zng0xdtbm, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Find, Encodings, Lists, Refusals (an undefined fact name is stored, 201, in a person or organisation vault), AskForTerm, Additive; Dev.Guide.Overview (A 06gkzpwebxv8ncqr4qd7egmt58, 2026-11-11) Vocabulary. Rows: Developer.DeriveFieldsFromVault, Developer.OfferRelationsFromVocabulary. Also: Agent.Concept.

For developers

TypeScript

fields-from-vocabulary.ts

// Build a record's fields and its link choices from GilbVeda, never from a list in your code.
// Every read here is public: no token, no proof.
const VEDA = "https://veda.gilb.com/base";
type Term = { "@id": string; [key: string]: unknown };
type Page = { complete?: boolean; next?: string; "@graph": Term[] };

const ids = (v: unknown): string[] =>
  (Array.isArray(v) ? v : v === undefined || v === null ? [] : [v]).map((x) =>
    typeof x === "object" && x !== null ? String((x as { "@id"?: unknown })["@id"]) : String(x));

async function json<T>(url: string): Promise<T> {
  const res = await fetch(url, { headers: { accept: "application/ld+json" } });
  if (!res.ok) throw new Error(`${url} answered ${res.status}`);
  return (await res.json()) as T;
}

// Every page of a listing, following next until complete is true.
async function allTerms(url: string): Promise<Term[]> {
  const out: Term[] = [];
  for (let next: string | undefined = url; next !== undefined; ) {
    const page: Page = await json<Page>(next);
    out.push(...page["@graph"]);
    next = page.complete === false ? page.next : undefined;
  }
  return out;
}

// The type and every type it is a kind of (a:subTypeOf, upwards).
async function typeAndParents(name: string): Promise<Set<string>> {
  const seen = new Set<string>();
  const queue = [`${VEDA}/t/${name}`];
  while (queue.length > 0 && seen.size < 50) {
    const iri = queue.shift()!;
    if (seen.has(iri)) continue;
    seen.add(iri);
    queue.push(...ids((await json<Term>(iri))["a:subTypeOf"]));
  }
  return seen;
}

export type FieldSpec = { fact: string; label: string; encoding: string; cardinality: string; choices?: string[] };

// The fields a record of this type can have, with how to show and write each one.
export async function fieldsOfType(typeName: string): Promise<FieldSpec[]> {
  const types = await typeAndParents(typeName);
  const terms = await allTerms(`${VEDA}/vocab?status=all&carries=a:fieldOf&limit=2000`);
  return terms
    .filter((t) => t["a:ontologyStatus"] !== "Deprecated")
    .filter((t) => ids(t["a:fieldOf"]).some((id) => types.has(id)))
    .map((t) => ({
      fact: String(t["a:predicateAttribute"]),
      label: String(t["a:label"]),
      encoding: String(t["a:encoding"] ?? "unknown"),
      cardinality: String(t["a:cardinality"] ?? "unknown"),
      ...(Array.isArray(t["a:valueSet"]) ? { choices: t["a:valueSet"] as string[] } : {}),
    }));
}

export type LinkChoice = { label: string; write: string | null; fromOtherEnd: string };

// The named links a person may choose, and how each reads from the other end.
export async function linkChoices(): Promise<LinkChoice[]> {
  const terms = (await json<Page>(`${VEDA}/vocab?status=all&linkPlane=user`))["@graph"];
  const byId = new Map(terms.map((t) => [t["@id"], t]));
  return terms
    .filter((t) => t["a:isRelationPredicate"] === true && t["a:ontologyStatus"] !== "Deprecated")
    .map((t) => {
      const label = String(t["a:label"]);
      const pair = byId.get(ids(t["a:inverseOf"])[0] ?? "");
      const fromOtherEnd =
        t["a:symmetric"] === true ? label
        : pair !== undefined ? String(pair["a:label"])
        : String(t["a:inverseLabel"] ?? label);
      return { label, write: typeof t["a:typeAttribute"] === "string" ? t["a:typeAttribute"] : null, fromOtherEnd };
    });
}

curl

vocabulary-lists.sh

# The terms that are fields of some type: keep those whose a:fieldOf names your type
# or a type it is a kind of. One page of up to 2000; follow next while complete is false.
curl -s "https://veda.gilb.com/base/vocab?status=all&carries=a:fieldOf&limit=2000"

# The named links meant for people: offer those with a:isRelationPredicate true.
curl -s "https://veda.gilb.com/base/vocab?status=all&linkPlane=user"

# One field's term: its label, encoding, cardinality and, for some, a:valueSet.
curl -s "https://veda.gilb.com/base/a/<name>"

Checked against GilbApp d529620.