Farmos data model
Use whenever you need to read or reason about how the homestead maps onto farmOS — which asset/log/quantity/term a real thing is, where an animal or plant currently *is* (location is computed from movement, not stored), how herds/flocks (groups) and pedigree (lineage) work, and which read tool answers a given question.From its SKILL.md
npx -y skills add barkerd427/farmhand --skill farmos-data-modelAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.0 KB, as published. Nobody here has run it
farmOS data model — the mental model the plugin speaks
farmOS is a generic Drupal app exposed over a JSON:API at {FARMOS_URL}/api.
It does not know "Honeycrisp" or "Saanen" — it knows four primitives plus a
taxonomy. This skill teaches that model so reads resolve to the right tool and
nothing is guessed. Never hard-code field names or bundle lists — the enabled
set varies per install; enumerate the live instance with introspect_schema (and
list_terms for vocabularies).
Target instance: farmOS 4.0.2 (Drupal 11), JSON:API, US units (lb, gal, °F, acres, inches).
The four primitives
| Primitive | JSON:API type | What it is |
|---|---|---|
| Asset | asset--{bundle} | A thing that persists |
| Log | log--{bundle} | A timestamped event |
| Quantity | quantity--{bundle} | A measurement attached to a log |
| Taxonomy term | taxonomy_term--{vocab} | Controlled vocabulary (breeds, cultivars, seasons, units, categories) |
Assets — asset--{bundle}
Things that persist. Bundles include land, plant, animal, equipment,
structure, water, sensor, group, material, product. Common fields:
name, archived (the native live/archived boolean — assets have no
status field; that's a log field), notes, flag, geometry (WKT),
is_location, is_fixed, parent (hierarchy / lineage), location
(current — computed, not set directly), image, data.
Logs — log--{bundle}
Timestamped events. Bundles include activity, observation, input,
harvest, seeding, transplanting, maintenance, medical, birth,
lab_test, purchase, sale. Common fields: name, timestamp, status
(pending/done), asset (→ assets), location (→ location assets),
geometry, is_movement, category (→ log_category terms), quantity
(→ quantities), notes, flag, owner.
Quantities — quantity--{bundle}
Measurements that hang off a log: measure (count, weight, volume,
length, area, temperature, value, rate, ratio, …), value,
unit (→ unit term), label.
This instance's enabled quantity bundles are
material,standard,testonly — there is NOquantity--timehere. (farmOS 4.x can enablequantity--time, but this install does not.) Day-to-day measurements (weight, volume, count, pH) usequantity--standard. Always confirm the live set withintrospect_schemarather than assuming a bundle exists — the write layer reads the enabled bundles from the schema, never a hard-coded list.
API constraint to remember (see the
recording-logsskill): a quantity is a standalone entity that must be created in its own request before a log can reference it. "Log a harvest with a weight" is ≥2 API calls. The convenience tools hide this.
Taxonomy terms — taxonomy_term--{vocab}
Breeds, cultivars, seasons, and units are terms, not free text. Key vocabs:
| Vocab | Holds | Example terms |
|---|---|---|
animal_type | breeds | "Saanen", "Border Cheviot" |
plant_type | cultivars/varieties | "Honeycrisp Apple", "Duke", "Legacy" |
season | growing season / period a planting belongs to | "2025", "Spring 2026" |
unit | measurement units | "lb", "gal", "pH" |
log_category | log tags | "withdrawal", "pre-harvest-interval" |
A cultivar's ripening window is not a
seasonterm — it lives on theplant_typeterm's profile asripening_season(seecrop-and-breed-profiles). |crop_family,material_type| grouping / inputs | |
The term itself is where the canonical care/breed profile lives
(get_term_profile). Resolve a name to its term id with resolve_term(vocab, name); enumerate a vocab with list_terms(vocab). Never invent a term id.
Movement IS location
An asset has no static location field you set. You record a log with
is_movement: true and a location, and farmOS computes the current
location from the latest movement log. Consequences:
- "Where is X right now?" →
current_location(asset)(computed from movement logs, not read off the asset). - "Where has X been?" →
movement_history(asset). - "What has grazed this pasture?" →
grazing_history(pasture). - To move something, you do not patch a location field — you create a
movement:
record_movement(any asset/group) ormove_herd(a herd/flock group, compliance-aware). Both write anis_movementlog--activitywith the destinationlocation. - Grazing rotation is just movement logs moving an animal or a herd/flock
grouponto a pasturelandasset.
Groups & lineage
- Group = herd/flock. An
asset--groupholds member animals. You move the group in one movement log and it fans out to every member — move the flock, not each ewe. Pass the group's id (with thegroupbundle) tomove_herd/record_movement/ harvest tools for a whole-group event. - Lineage = the
parentrelationship betweenanimalassets —parent = [dam, sire]. It is native, applies to goats and sheep, and is queryable both directions withget_lineage(animal, depth?)(ancestors and descendants).get_animal(tag_or_id)returns an animal including its immediate lineage. - Off-farm ancestors (a dam/sire not on the property) are stored as
animalassets witharchived: true+ a "reference" flag, so pedigree resolves without inflating herd counts.count_assetsexcludes archived/exited records, including these ancestors.
Which read tool answers which question
| Question | Tool |
|---|---|
| List things of a type (active by default) | list_assets(type, status?, filters?) |
| One asset by id | get_asset(id) |
| Events for an asset / type / date range | list_logs(asset?, type?, from?, to?, status?) |
| One log by id | get_log(id) |
| Free-text "find anything" (assets + logs) | search(term) |
| List a vocabulary | list_terms(vocab) |
| Name → term id | resolve_term(vocab, name) |
| Care/breed profile on a term | get_term_profile(vocab, name) |
| An animal (incl. lineage) | get_animal(tag_or_id) |
| Pedigree both directions | get_lineage(animal, depth?) |
| Where is it now / where has it been | current_location(asset) / movement_history(asset) |
| What grazed this pasture | grazing_history(pasture) |
| Inventory of a material/product | inventory(item?) |
| Live counts (excludes archived/ancestors) | count_assets(...) |
| Real field names / enabled bundles | introspect_schema(type?) |
| Open withdrawal/PHI windows | expiring_windows(...) |
These are all reads — free, no confirmation. Writes live in the
recording-logs skill.
Worked example — "the Honeycrisp apple in the lower orchard"
Goal: find the specific tree and answer "what's been done to it lately?"
- Resolve the cultivar term (optional sanity check).
resolve_term("plant_type", "Honeycrisp Apple")→ theplant_typeterm id. - Find the asset, not the term.
search("Honeycrisp")(fans out across assets + logs), orlist_assets("plant", filters=…)filtered to plants whoseplant_typeis Honeycrisp. Multiple Honeycrisps? Disambiguate by current location, not a stored field:- For each candidate,
current_location(<plant id>); keep the one whose computed location is the lower-orchardlandasset.
- For each candidate,
- Read its recent activity.
list_logs(asset=<plant id>, type="log--input")(sprays),list_logs(asset=<plant id>, type="log--harvest"), etc. - Check compliance before advising a harvest.
expiring_windows(kind="pre-harvest-interval")(or filtered to this asset) — any openharvest_ok_afterwindow means harvest is not yet allowed.
Note the discipline: location is derived (current_location), and the
cultivar is a resolved term, never a guessed string.
Worked example — "the Saanen doe Clover"
Goal: pull up the doe and her pedigree.
- Get the animal.
get_animal("Clover")(resolves a tag or name/id to theasset--animal, returning immediateparentlineage). - Confirm the breed term. Her
animal_typeshould resolve to the "Saanen" term —resolve_term("animal_type", "Saanen")to verify the id matches. - Full pedigree, both directions.
get_lineage(<Clover's id>, depth=3)— ancestors (dam/sire, off-farm references included) and descendants (her kids). - Where is she now?
current_location(<Clover's id>)— computed from her latest movement log, e.g. the doe barn or a paddocklandasset.
To record anything about Clover (a milk yield, a treatment, a move), switch to
the recording-logs skill — that covers the quantity-before-log sequence and
the compliance guardrails.