Skip to content
Starlings

Starlings Subject Spec

Version 0.4.0

A subject is one thing a company works on: a project, a lead, an organization or an event. It holds its own history across time. Tools and agents that share the subject share the context. This spec defines the subject kinds, the doors that address things, and the records an agent reads and writes.

Starlings is the reference implementation. Any tool may implement this spec without permission. The licence is Apache-2.0.

Status

Version 0.4.0. This is a draft. It names the kinds, the doors and three records (the subject, the task and the decision) and has a conformance suite for them. Other records follow: the goal, the meeting record and the act record, a signed, append-only log of what each person and agent did.

Subject kinds

KindWhat it is
projectWork the company delivers, usually for a client
leadA possible piece of work, before it is won or lost
organizationAn organization the company works with: a client, a partner, a prospect. Those are relationships, read from its records, not kinds
eventA dated gathering the company runs or attends

A reader accepts partner, the kind 0.3.0 replaced, as organization for one version. A writer writes only organization.

What each kind can receive (tasks, documents, issues, meetings) is the implementation's decision. The spec does not require one kind to hold tasks and another not to.

Doors

A door is the stable address of a thing. An agent passes doors between tools instead of names.

  • A subject: subject:<kind>:<id>, for example subject:lead:7f3a….
  • Any other thing: <kind>:<id>, where the kind is one of person, agent, contact, thread, document, event, task or issue.

A person is someone in the workspace, named by an address. A contact is someone outside it the company works with, a client's or a partner's person, named by the implementation's id: a contact has several addresses, and one may change.

The id is opaque. It may contain :. Only the first colon (and, for a subject, the second) is part of the grammar. A person or an agent is named by an address, for example person:ada@example.com.

An implementation may define more doors for its own places and actions. Those doors are not part of the standard, and an agent must not expect another implementation to read them.

Records

An implementation may add fields to any record. It must keep every field the spec names, with the same type. A field the spec marks nullable is present with null, not left out. The fields are in the schema below.

Subject

One thing a company works on. A subject has a kind, an id that is unique within that kind, a title, and an optional line of context. Its door is subject:<kind>:<id>.

Task

Work someone must do. A task usually belongs to one subject, named by subject_kind and subject_id; both are null for a task that belongs to none. Its due date is a day, YYYY-MM-DD, with no time.

StatusMeaning
proposedAn agent suggested it. No person has accepted it yet
pendingAccepted, not started
in_progressSomeone is working on it
reviewDone, waiting for a check
blockedCannot move until something else happens
completedDone
cancelledDropped after it was accepted
declinedA person turned down a proposed task

An agent that is not sure a task is wanted files it as proposed and lets a person accept or decline it.

Decision

A settled choice on one subject. An implementation writes a decision once and does not edit it. To change a decision, it records a new decision whose body names the old one.

Conformance

An implementation conforms when it passes every case in the conformance suite for the spec version it claims. The cases are one JSON file, /spec/conformance/cases.json. The file is the contract: an implementation in any language reads it and runs the rules below.

SectionRule
subjectKindsThe implementation knows exactly these kinds
doors.validReading door gives parsed, and writing parsed gives door back
doors.aliasedReading door, which names a kind by a name it replaced, gives parsed; writing parsed gives written, the current name
doors.invalidReading the door gives nothing
doors.productOnlyThe door may be read by the product that defines it, but never as one of the doorKinds
subjects.valid, tasks.valid, decisions.validThe record is valid. An extra field does not make it invalid
subjects.invalid, tasks.invalid, decisions.invalidThe record is not valid. A decision case with bodyLength sets body to that many characters first

For a JavaScript or TypeScript implementation, /spec/conformance/run.mjs runs the cases with no dependencies. Write an adapter module that exports subjectKinds, parseDoor, doorString and, optionally, validateSubject, validateTask and validateDecision, then run node run.mjs ./adapter.mjs. The reference implementation's adapter is /spec/conformance/reference-adapter.mjs.

Versions

The version is MAJOR.MINOR.PATCH.

  • A patch changes wording only.
  • A minor version adds a record, a field, a kind or a door kind. A reader that does not know the addition ignores it.
  • A major version removes or changes something. One major version is current at a time, and the spec announces a major change before it ships.

Schema

The JSON Schema (draft 2020-12) is generated from the reference implementation's code, so it cannot disagree with it. Download it at /spec/schema.json.

SubjectKind

One of the subject kinds.

"project" | "lead" | "organization" | "event"

DoorKind

What a door names.

"subject" | "person" | "agent" | "contact" | "thread" | "document" | "event" | "task" | "issue"

Door

The stable address of a thing: `<kind>:<id>`, or `subject:<subject kind>:<id>` for a subject.

pattern ^(?:subject:(?:project|lead|organization|event|partner):.+|(?:person|agent|contact|thread|document|event|task|issue):.+)$

DecisionSource

Where the decision was made: a message, a meeting, by hand, or by an agent acting for a person.

"message" | "meeting" | "manual" | "agent"

Decision

A settled choice on one subject.

FieldTypeDescription
idstringStable id of the decision.
subject_kindSubjectKind
subject_idstringId of the subject the decision belongs to.
bodystring, at most 2000 charactersWhat was chosen, in one to a few sentences.
sourceDecisionSource
source_refstring or nullThe message id, the meeting id, or the agent, by `source`. Null for `manual`.
goal_idstring or nullThe goal the decision serves, if any.
decided_by_namestring or nullDisplay name of the person who decided.
decided_by_emailstring or nullAddress of the person who decided.
decided_atstringWhen it was decided, as an ISO 8601 timestamp.

Subject

One thing a company works on: a project, a lead, an organization or an event.

FieldTypeDescription
idstringStable id of the subject, unique within its kind.
kindSubjectKind
titlestringThe name people use for it.
subtitlestring or nullOne line of context: a client, a stage, a date. Null when there is none.
last_activity_at (optional)string or nullWhen something last happened on the subject, as an ISO 8601 timestamp. Null or absent when unknown.

TaskStatus

Where the task stands. `proposed`: suggested by an agent, not yet accepted by a person. `declined`: turned down by a person.

"pending" | "in_progress" | "review" | "blocked" | "completed" | "cancelled" | "proposed" | "declined"

Task

Work someone must do, usually on one subject.

FieldTypeDescription
idstringStable id of the task.
titlestringWhat must be done, in a few words.
notesstring or nullLonger detail. Null when there is none.
statusTaskStatus
subject_kindSubjectKind or nullThe kind of subject the task belongs to. Null, with `subject_id`, for a task that belongs to no subject.
subject_idstring or nullId of the subject the task belongs to. Null exactly when `subject_kind` is null.
assignee_namestring or nullDisplay name of the person who owns the task. Null when nobody does.
assignee_emailstring or nullAddress of the person who owns the task. Null when nobody does.
due_datestring or nullThe day it is due, as YYYY-MM-DD. Null when it has no date.
goal_idstring or nullThe goal the task serves, if any.
updated_atstring or nullWhen the task last changed, as an ISO 8601 timestamp. Null when unknown.

Conformance result

The reference implementation passes 64 of 64 checks in this version's suite. The build runs the suite and stops when a check fails.

Download: cases.json · run.mjs · reference-adapter.mjs

JSON Schema: /spec/schema.json · Markdown: /spec.md · Source: standard/SPEC.md, standard/src/schema.ts · Apache-2.0