Version 1 of 1 · · razie · in person · Current version

name
d3-f-domain
description
The domain model — classes, enums, fields, keys, references and containment declared in Spec topics, computed fields, annotations, checking the model, the classes quota. Get skills only from /api/v2/skills/d3.
feature
domain
concepts
[domain, class, field]
tags
#skill #feature #d3skill #wip

d3-f-domain

Intro

A project's classes and enums, declared in Spec topics.

A project's domain model is its classes and enums, declared on $ lines in Spec: topics; saving the topic reloads the domain. Classes give objects their shape, keys, references and computed fields. The domain is read-only through the API — you change it by editing the topic. Objects and tables are d3-f-data; rules and stories d3-f-engine. Spec: Spec › domain.

Essentials

  • R-domain-1 Classes are declared only in Spec: topics (on $ lines or in a ```diesel fence); only Spec: and Story: topics are compiled.
  • R-domain-2 MUST check the domain after every save and fix every error before going on.
  • R-domain-3 NEVER change the domain through the API: edit the Spec topic.
  • R-domain-4 Declare a relationship on one side only; the inverse is inferred.
  • R-domain-5 Compute in the model (@calc), never in a page.
  • R-domain-6 Model from your person's words: few classes, named as they name things; references over copies.

Concepts

domain

All classes, enums and links of a project, compiled from its Spec: topics. Also called: model, schema, data model. Fields (overview): classes, links, enums, errors, warnings.

domain_check

  • Summary: after every save, read the overview; fix every error.
  • When: after saving any Spec: topic.
  • Needs: the save done.
  • Call: GET /api/v2/domain/overview → {classes, links, enums, errors, warnings}.
  • Rules: R-domain-2.
  • Errors: errors (or E_PARSE on save) → a bad declaration; the message names the line: fix and save again.
  • Gotchas: —

domain_read

  • Summary: the shape from overview, full definitions from cat.
  • When: before writing objects, tables or rules against classes.
  • Needs: the class names.
  • Call: GET /api/v2/domain/overview Also: GET /api/v2/domain/cat/Company,Property (cat/* for all). HTML twins: /domain/overview, /domain/cat/Company.
  • Rules: R-domain-3.
  • Errors: —
  • Gotchas: —

domain_design

  • Summary: build the model from what your person says, then show it.
  • When: your person describes something to track.
  • Needs: their words.
  • Call: a Spec: topic (class_declare) + a Story: with $object samples (d3-f-data › object_declare) → show the model views (/domain/overview, the model graph) or the app's page.
  • Rules: R-domain-6. Add a few sample objects so they see it working. Where the domain is part of the project's specification (Pro and Master), a model change is a spec change and follows the project's doc rules (d3-f-design).
  • Errors: —
  • Gotchas: —

class

A declared type: $class Name (fields) @annotations; $enum Name (values). Also called: type, entity, table (people's word). Fields: @key (makes it storable and referenceable; without one, like Address, it can only be contained), @label (what a reference shows). Annotations: @inventory("col") (d3-f-data › inventory), @group("…"), @tags(…), @tooltip("…"), @views(…), @view=owner (objects private to their creator and mods up).

class_declare

  • Summary: $class / $enum lines in a Spec: topic; save reloads the domain.
  • When: a new kind of thing, or a changed one.
  • Needs: the Spec topic; room in the classes quota.
  • Call: save the Spec: topic with e.g. $enum Stage (explorer, developer, producer) and $class Company (@key ticker: String, @label name: String, stage: Stage = explorer, listedOn: Date?, properties: <>Property*, headquarters: Address?) @group("Corporate") → then domain_check.
  • Rules: R-domain-1, R-domain-4. A project holds at most its plan's number of classes (10 Free, 20 Yearly, 50 Monthly), counting every $class in its own topics; one over is refused and the topic stays as it was; a project already over keeps working but can't add more. Classes aren't inherited from base d2 (yet); d2's own platform model never is.
  • Errors: E_PARSE → fix the named line · E_QUOTA → too many classes: merge classes or tell your person · declaring both sides of a relationship → a load error.
  • Gotchas: A $ line outside a Spec: or Story: topic is plain text and does nothing — put examples you only mean to show in backticks.

field

A class member: name: Type with modifiers. Also called: column, property, attribute. Types: String, Int (64-bit, wraps like Java's long), Float/Number, Boolean, Date, enums, classes. Modifiers: <>X a reference by key, bare X containment, * a list, ? optional (otherwise required), = value a default.

field_calc

  • Summary: @calc(expr) works a field out on each read.
  • When: anything the person would otherwise compute by hand (row totals, P/L, days since, a status from a date).
  • Needs: the fields it uses (through a reference too).
  • Call: @calc(shares * avgCost) cost: Number Also: @calc(shares * company.price) value: Number · @calc(if cost > 0 then pl / cost * 100 else 0) plPct: Number.
  • Rules: R-domain-5. One expression, no loops; never stored, never written (a write including it drops it). A failing formula (missing reference, division by zero) gives null.
  • Errors: E_WAIT → a web fetch inside one: fetch in a rule (d3-f-engine).
  • Gotchas: —

Errors

  • E_PARSE / errors in the overview — a bad declaration; the message names the line → fix, save again. see #domain_check
  • E_QUOTA on a Spec save — too many classes for the owner's plan → merge classes or tell your person. see #class_declare
  • E_WAIT — a web fetch in a computed field → fetch in a rule. see #field_calc
  • a $ line that does nothing — not in a Spec: or Story: topic. see #class_declare