Docs

Package format

The dotjob.yaml specification, field by field.

A DotJob is one declarative file, dotjob.yaml. It is the single source of truth for the listing page, the install form and the runtime. This page documents spec v0.1 (draft).

Top-level fields

Field	Type	Required	Notes
`name`	slug	yes	Lowercase, hyphenated, unique within your publisher namespace.
`version`	semver	yes	See publishing & versioning.
`title`	string	yes	Shown in the catalogue. 2–5 words.
`tagline`	string	yes	One sentence, ≤ 110 characters.
`description`	string	yes	One or two paragraphs for the listing page.
`category`	enum	yes	research · monitoring · reporting · operations · web · sales · productivity · finance · crypto
`price`	object	yes	{ amount: number, unit: run \| month }
`schedule`	cron \| preset	yes	on-demand, a cron string, or a preset such as weekly-monday-07:00.
`connects`	list<app>	yes	Apps the job may touch. Anything not listed is unavailable at runtime.
`inputs`	map	yes	Named, typed inputs. See below.
`steps`	list	yes	Ordered steps. See steps & guarantees.
`outputs`	list	yes	What the user gets and where it lands.
`guarantees`	list	no	Runtime-enforced promises. Strongly recommended.
`tags`	list<string>	no	Search keywords.

Inputs

Each input is a named entry with a type. Types can carry a parameter in angle brackets.

inputs

inputs:
  companies:
    type: list<string>        # text | list<T> | url | file<csv|pdf> | connection<app> | schedule
    min: 1
    max: 50
    description: Names or domains, one per line
  focus_areas:
    type: text
    optional: true            # inputs are required unless optional: true
    default: "funding, hiring"
  destination:
    type: connection<google-sheets>
    description: Sheet to write results to

Property	Applies to	Meaning
`optional`	all	Defaults to false.
`default`	text, list, url, schedule	Pre-filled value the user can change.
`min / max`	list	Item count bounds.
`pattern`	text, list<string>	Regex each value must match.
`accept`	file	Allowed extensions, e.g. file<csv\|xlsx>.
`scope`	connection	Narrows a grant: read, write, or a resource type such as channel.

Price and schedule

price: { amount: 39, unit: month }   # or { amount: 29, unit: run }
schedule: "0 7 * * MON"               # cron, or: on-demand | daily-06:00 | weekly-monday-07:00 | every-15m

Monthly jobs must have a schedule other than on-demand. Per-run jobs may be on-demand or trigger-based (for example on: sheets.new_row).

Outputs

outputs:
  - sheet: inputs.destination          # a declared connection input
  - note: summarise                    # a step id — delivered as a note in the run
  - file: diffs/                       # an artefact folder attached to the run

Every output must reference either a connection input or a step id. Outputs are the only places a job may write; this is what no_writes_outside_destination checks.

Full example

dotjob.yaml

name: company-research-sprint
version: 1.4.0
title: Company Research Sprint
tagline: Research up to 50 companies and return a clean, sourced spreadsheet.
category: research
price: { amount: 29, unit: run }
schedule: on-demand
tags: [prospecting, market map, due diligence]

connects: [google-sheets, web, linkedin, crunchbase]

inputs:
  companies:
    type: list<string>
    max: 50
    description: Names or domains, one per line
  focus_areas:
    type: text
    optional: true
  destination:
    type: connection<google-sheets>
    scope: write

steps:
  - id: resolve
    do: resolve_companies(inputs.companies)
  - id: research
    do: gather_public_data(resolve, fields: [desc, hq, size, funding, people, news])
    parallel: true
  - id: score
    do: score_against(inputs.focus_areas)
  - id: write
    do: sheets.write(inputs.destination, rows: research + score, with_sources: true)
    safe: false
  - id: summarise
    do: summarise(highlights: 5)

outputs:
  - sheet: inputs.destination
  - note: summarise

guarantees:
  - every_field_has_source
  - no_writes_outside_destination

Continue with steps & guarantees.