Semantic source

Semantic source is what you author. One aggregate per file, one file per thing: an entity, a lifecycle, an action, an automation, a role, a screen. YAML being nicer to read than JSON isn’t really the reason for it. The reason is that one thing lives in one file. An entity you can open, read top to bottom and review in a diff is a very different object from the same entity buried three thousand lines into a single document.

The shape of a file

Every file opens by declaring what it is. The first key is the aggregate kind, and its value is the key of that aggregate.

entity: team

role: viewer

lifecycle: funding_lifecycle

automation: stamp_owner

screen: costs

That first line is how the compiler knows what it’s reading. The directory layout is for you.

An entity

The same entity three ways: what you write, what it compiles to, and what the dotnet-vue generator turns that into.

entity: team
kind: config
label: Team
plural: Teams
icon: account-group
display: name
description: A functional team hiring is grouped by.
fields:
  name:
    type: text
    label: Team Name
    required: true
    unique: true
  function:
    type: select
    label: Function
    required: true
    options:
      - value: engineering
        label: Engineering
        color: "#0f766e"
      - value: sales
        label: Sales
        color: "#f59e0b"
  default_salary:
    type: money
    label: Default Gross Salary / Year
    currency: EUR
    help: Prefilled onto new hiring lines.
  description:
    type: longtext
    label: Description

{
  "key": "team",
  "label": "Team",
  "labelPlural": "Teams",
  "description": "A functional team hiring is grouped by.",
  "icon": "account-group",
  "displayField": "name",
  "kind": "config",
  "fields": [
    {
      "key": "name",
      "label": "Team Name",
      "type": "text",
      "required": true,
      "unique": true
    },
    {
      "key": "function",
      "label": "Function",
      "type": "select",
      "required": true,
      "options": [
        { "value": "engineering", "label": "Engineering", "color": "#0f766e" },
        { "value": "sales", "label": "Sales", "color": "#f59e0b" }
      ]
    },
    {
      "key": "default_salary",
      "label": "Default Gross Salary / Year",
      "type": "money",
      "help": "Prefilled onto new hiring lines.",
      "currency": "EUR"
    },
    {
      "key": "description",
      "label": "Description",
      "type": "longtext"
    }
  ]
}

namespace Teams.Entities;

public sealed class Team : IRecord, IHasTrackingFields
{
    [JsonPropertyName("id")] public string Id { get; set; } = "";

    [JsonPropertyName("name")] public string Name { get; set; } = "";

    [JsonPropertyName("function")] public string Function { get; set; } = "";

    [JsonPropertyName("default_salary")] public decimal? DefaultSalary { get; set; }

    [JsonPropertyName("description")] public string? Description { get; set; }

    // created_at, created_by, updated_at, updated_by, deleted_at and
    // record_state follow. The runtime fills them in.
}

The C# tab is trimmed: the real file carries a doc comment on every property, and the tracking fields written out in full. fields is a map keyed by field key. The key is the identifier the rest of the app refers to, and everything under it describes what that field is.

kind says what sort of thing the entity is: collection for records people create all day, config for a small reference list, settings for a single row of app-wide values. It changes how the app presents the entity, not how it stores it.

Field types

text, longtext, integer, decimal, money, boolean, date, datetime, email, url, phone, select, multiselect, reference, json, attachment. A field says what it is, and the type-specific keys follow from that: options on a select, currency on money, precision and scale on decimal, targetEntity on a reference.

cordango vocabulary field

That prints every property a field accepts and every type it can be, from the build you have installed. It’s the authoritative answer, and it’s shorter than this page.

A role

Roles are grants, entity by entity.

role: viewer
name: Investor / Viewer
description: Read-only access to the plan, for investors and advisors.
grants:
  scenario:
    read: true
  period:
    read: true
  hiring_line:
    read: true

No inheritance, no wildcards. If you didn’t name an entity, this role can’t touch it. That’s what lets you read one file and know what the role can do without holding the rest of the app in your head.

A lifecycle

States and the transitions between them, over one field of one entity.

lifecycle: funding_lifecycle
entity: funding_round
stateField: round_stage
initial: planned
states:
  planned:
    label: Planned
    phase: not_started
    color: "#94a3b8"
  in_conversation:
    label: In Conversation
    phase: active
    color: "#38bdf8"
  abandoned:
    label: Not Happening
    phase: cancelled
    terminal: true
transitions:
  start_raise:
    label: Start Raising
    from: [planned]
    to: in_conversation
    action:
      icon: rocket-launch
      style: primary

phase is the generic reading of a state, so a board or a chart can group states it has never seen before. terminal says nothing leaves this state.

An automation

Trigger, entity, effects.

automation: stamp_scenario_owner
name: Stamp scenario owner on creation
trigger: record.created
entity: scenario
effects:
  - type: updateRecord
    setIfEmpty: true
    set:
      owner: "{{actor.id}}"

A trigger can also name another app, which is how one app reacts to what another announces. The app being listened to is not changed and does not know:

automation: commit_on_purchase_approved
name: Commit the money when a purchase is approved
trigger: state.entered
app: purchase_requests
event: purchase_request.approved
effects:
  - type: createRecord
    entity: spend_entry
    set:
      amount: "{{record.amount}}"

See Apps working together.

The app file

One per app, holding everything no single aggregate owns: identity, theme, relations between entities, and the order things appear in.

app: budget_planner
name: Budget Planner
version: 16.3.0
schemaVersion: "2.0"
description: Build and maintain an investor-ready financial budget plan.
theme:
  primaryColor: "#0f766e"
  radius: small
  density: compact
relations:
  scenario_periods:
    type: oneToMany
    label: Periods
    fromEntity: scenario
    toEntity: period
    inverseField: scenario

Two halves of a workspace

Worth knowing, because it changes how much vocabulary you need.

Semantic

entities/, workflows/, roles/. A small vocabulary, all of it listed by cordango vocabulary with no arguments. You will rarely need more.

Block trees

views/. Screens are not modelled semantically yet, so these are still App Definition block trees. This is where cordango vocabulary block <kind> earns its place.

Ask for one block kind at a time. Asking for all of them defeats the point of the layer.

Formatting

cordango fmt

Rewrites every .cordango.yaml file in canonical form: consistent key order, consistent quoting. Run it after hand-editing, so a diff shows a change in meaning instead of a change in whitespace.

What isn’t source

.cordango/, with the leading dot, is build output. It gets regenerated and it doesn’t belong in git. Anything you edit in there disappears on the next cordango build.

Get started

Quickstart with an AI agent

Concepts

Guides

Security

The shape of a file

An entity

Field types

A role

A lifecycle

An automation

The app file

Two halves of a workspace

Semantic

Block trees

Formatting

What isn’t source

​The shape of a file

​An entity

​Field types

​A role

​A lifecycle

​An automation

​The app file

​Two halves of a workspace

Semantic

Block trees

​Formatting

​What isn’t source

The shape of a file

An entity

Field types

A role

A lifecycle

An automation

The app file

Two halves of a workspace

Formatting

What isn’t source