clean install

web/profiles/farm/docs/model/convention/index.md

@@ -0,0 +1,44 @@
+# Conventions
+
+## In theory
+
+The farmOS data model describes basic record types that can be used to
+represent a farming system, but *how* those record types are used is left up to
+the user in large part.
+
+It is not the data model's responsibility to enforce an opinionated standard
+for all data that it stores. Instead, it aims to provide the flexibility for
+these standards to be developed through a collaborative community effort on top
+of the data model over time. These standards are collectively referred to as
+"conventions".
+
+Conventions are not part of the data model itself, but understanding how they
+relate to and are built on top of the model helps develop good record keeping
+habits, which result in more consistent and comparable data.
+
+One of the longer term goals of farmOS is to be a platform that supports the
+collaborative development of these conventions over time. As new standards
+are developed and adopted in the community, they can be written into modules
+that provide different levels of "enforcement of" or "compliance to" these
+conventions.
+
+The data model, combined with established conventions, and tools like the
+[farmOS Aggregator](https://github.com/farmOS/farmOS-aggregator) can enable a
+wide variety of data sharing, aggregating, and reporting use-cases.
+
+## In practice
+
+Within an individual farmOS instance, you may develop your own conventions
+around naming your Assets. Or you may develop a standard operating procedure
+for certain types of common data entry, to ensure that it always goes into
+farmOS in the same manner and format.
+
+Across separate farmOS instances, developing shared conventions enables data to
+be more easily aggregated and compared at larger scales.
+
+Some ways in which conventions are already being developed include:
+
+- Quick forms, surveys, and other data entry tools that collect specific
+  information and store it consistently in Logs.
+- Reports that query the database for Logs that match a certain convention
+  and summarize them in different ways.

web/profiles/farm/docs/model/index.md

@@ -0,0 +1,39 @@
+# farmOS Data Model
+
+## Goals
+
+The goal of the farmOS data model is to represent and organize a wide variety
+of agricultural and ecological systems to allow for easy access, analysis, and
+interoperability. This ranges from small-scale garden records to industrial
+agriculture to national forestry management.
+
+farmOS can model data that was recorded via manual data entry, as well as data
+streams from sensors or other applications.
+
+## Record types
+
+Data is organized into a set of high-level record types. The two primary record
+keeping data types are **Assets** and **Logs**. Other types include
+**Quantities**, **Terms**, **Plans**, and **Users**.
+
+- [Assets](/model/type/asset)
+- [Logs](/model/type/log)
+- [Quantities](/model/type/quantity)
+- [Data streams](/model/type/data_stream)
+- [Files](/model/type/file)
+- [Terms](/model/type/term)
+- [Plans](/model/type/plan)
+- [Users](/model/type/user)
+
+## Logic
+
+- [Location](/model/logic/location)
+- [Group membership](/model/logic/group)
+- [Inventory](/model/logic/inventory)
+
+## Conventions
+
+Beyond the record types that farmOS provides, it is helpful to develop
+conventions around how they are used.
+
+[farmOS Data Conventions](/model/convention)

web/profiles/farm/docs/model/logic/group.md

@@ -0,0 +1,33 @@
+# Group membership
+
+farmOS includes an optional "Group asset" module, which adds a new Asset type
+called Group, as well as some organizational features that are unique to Group
+Assets.
+
+A Group can have "members", which are other individual Assets. Group membership
+is tracked via "group assignment" Logs. This is very similar to the way that
+[Location](/model/logic/location) works for "movable" Assets. This means that
+an Asset's group membership can change, and the full history of its previous
+memberships is maintained in Logs.
+
+A useful feature of Groups is that any Logs associated with the Group will also
+be associated with its member Assets.
+
+A common use case for this is tracking "herds" of Animal assets. Each herd can
+be represented as a Group Asset, with Animal Assets assigned to it. Logs can be
+used to move the whole group, instead of referencing Animal Assets individually.
+
+Notably, when the Group module is enabled, it overrides the Asset location
+logic to consider group membership. If the Asset is a member of a group, and
+the group has a movement Log that is more recent than any of the Asset's own
+movement Logs, then the Asset's location will be based on the group's Log.
+
+## Group membership logic
+
+The logic for determining an Asset's group membership is as follows:
+
+- *Does the asset have a group assignment Log?*
+    - Yes: *Does the group assignment Log reference groups?*
+        - Yes: **groups referenced by the group assignment Log**
+        - No: **no group**
+    - No: **no group**

web/profiles/farm/docs/model/logic/inventory.md

@@ -0,0 +1,20 @@
+# Inventory
+
+farmOS can track the inventory of Assets over time.
+
+Inventory is tracked via [Logs](/model/type/log) with *inventory adjustment*
+[Quantities](/model/type/quantity). The Inventory module adds two fields to
+Quantity records: "inventory asset" and "inventory adjustment". Each Quantity
+can reference a single Asset, and either "reset", "increment", or "decrement"
+that Asset's inventory. The Quantity's "measure", "value", and "units" fields
+are used in the inventory calculations.
+
+Asset inventory is determined by querying all Quantities that reference the
+Asset and define an adjustment type of "reset", "increment", or "decrement".
+Inventory is calculated by adding all "increment" adjustments and subtracting
+all "decrement" adjustments, starting from the most recent "reset" adjustment
+(or zero if no "reset" adjustment exists).
+
+A separate inventory is tracked for each measure+unit pair, so Assets can have
+a single simple inventory (without a specified measure or unit), or they can
+have multiple inventories of different measures and units.

web/profiles/farm/docs/model/logic/location.md

@@ -0,0 +1,80 @@
+# Location
+
+farmOS can track the physical location of Assets over time. This includes map
+geometry as well as relation to other Assets.
+
+## Fixed Assets
+
+Some Assets are *fixed* in location. The geometry of these Assets is
+*intrinsic* to the Asset itself.
+
+Land is an example of an Asset with a fixed location. Although geography
+changes over time, land assets in farmOS should be considered a snapshot of the
+physical land they represent at the current time. This is useful because it
+provides a simplified model for referring to a logical piece of land and its
+geometry.
+
+Changes to a fixed Asset's intrinsic geometry should be limited to minor
+updates or corrections. If the changes are more substantial, a new Asset should
+be created, and the old Asset archived, to demarcate it as a new phase of the
+place in question.
+
+## Movable Assets
+
+If an Asset is not fixed, then it is considered *movable*, and its location and
+geometry will be determined by *movement* Logs that reference it.
+
+In order to set or change a movable Asset's location, a movement Log must be
+created that defines its new location at that point in time.
+
+Any Log can be a movement. It just needs to reference the Assets that are
+moving, along with their new location. The new location can be in the form of a
+geometry and/or a reference to one or more location Assets.
+
+It is possible to find an Asset's location at any point in time by querying its
+movement Logs.
+
+Generally a movement Log is only included if it is "done", although it is also
+possible to find "pending" movement Logs in the future to find an Asset's
+projected future location.
+
+## Locations
+
+Assets can be designated as *locations*. This allows other Assets to be moved
+to them.
+
+Typically, fixed Assets will also be designated as locations. However, movable
+Assets can also be locations. Consider a tractor (Equipment Asset) with
+multiple attachments (more Equipment Assets). It is possible to record that an
+attachment is connected to the tractor, and therefore its location is derived
+from the tractor's location.
+
+Fixed location Assets can designate *parent* Assets to create a hierarchical
+organization.
+
+## Logic
+
+The logic for determining an Asset's geometry is as follows:
+
+- *Is the Asset fixed?*
+    - Yes: *Does it have an intrinsic geometry?*
+        - Yes: **intrinsic geometry**
+        - No: **no geometry**
+    - No: *Does it have a movement Log?*
+        - Yes: *Does the movement Log have geometry?*
+            - Yes: **movement Log geometry**
+            - No: *Does the movement Log reference a location Asset?*
+                - Yes: **(recurse to determine location Asset's geometry)**
+                - No: **no geometry**
+        - No: **no geometry**
+
+## Geometry
+
+When a Log is saved without a geometry, and it references locations that have
+geometries, the combined geometries of the referenced locations will be copied
+to the Log. Assets referenced in the Location relationship are given first
+priority. If none are found, then Assets referenced in the Log's Asset
+relationship will be used. In the latter case, only Assets that are explicitly
+designated as locations will be included, and geometry will not be copied if
+the Log is a movement (otherwise it would be impossible to clear the geometry
+of a non-fixed location Asset via movement Logs).

web/profiles/farm/docs/model/type/asset.md

@@ -0,0 +1,291 @@
+# Assets
+
+Assets represent the things that are being tracked or managed. Land, plants,
+animals, and equipment are all types of Assets. Modules can provide additional
+Asset types.
+
+Assets are generally limited in the information they contain. Most of the
+valuable historical information about an Asset will be stored in **Logs** that
+reference it.
+
+## Type
+
+Each Asset must have a type. All Asset types have a common set of attributes
+and relationships. Specific Asset types may also add additional attributes and
+relationships (collectively referred to as "fields"). Asset types are defined
+by modules, and are only available if their module is enabled. The modules
+included with farmOS define the following Asset types:
+
+- Land
+- Plant
+- Animal
+- Equipment
+- Compost
+- Structure
+- Sensor
+- Water
+- Material
+- Product
+- Group*
+
+*Group Assets are unique in that they can "contain" other Assets as "group
+members". This is a flexible feature that can be used for many purposes. One
+typical use case is representing "herds" of Animal Assets. Group membership
+changes are recorded via Logs (similar to location changes), so it is possible
+to see all the Groups that an Asset was a member of in the past, when/why they
+were moved, etc. See [farmOS Group Membership Logic](/model/logic/group) for
+more information.
+
+## ID
+
+Each Asset will be assigned two unique IDs in the database: a universally unique
+identifier (UUID), and an internal numeric ID.
+
+The UUID will be unique **across** farmOS databases. The internal ID will only
+be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs
+to ensure that IDs pulled from multiple farmOS databases do not conflict.
+Internally, farmOS modules use the internal IDs to perform CRUD operations.
+
+## Attributes
+
+Assets have a number of attributes that serve to describe their meta information.
+All Assets have the same standard set of attributes. Modules can add additional
+attributes.
+
+### Standard attributes
+
+Attributes that are common to all Asset types include:
+
+- Name
+- Status
+- Flags
+- Geometry
+- Intrinsic geometry
+- Is location
+- Is fixed
+- Notes
+- ID Tags
+- Data
+
+#### Name
+
+Assets must have a name that describes them. The name is used in lists of Assets
+to easily identify them at quick glance.
+
+#### Status
+
+Assets can be marked as "active" or "archived" to indicate their status.
+Archived Assets will be hidden from most lists in farmOS unless they are
+explicitly requested.
+
+#### Flags
+
+Flags can be added to Assets to help with sorting and filtering. farmOS
+provides a set of default flags, including "Priority", "Needs review", and
+"Monitor". Modules can provide additional flags, such as "Organic".
+
+#### Geometry
+
+The geometry of an Asset describes where it exists at a given point in time.
+An Asset can either be "fixed", or it can be moved around via movement Logs.
+This geometry field is not editable itself, but is rather computed based on the
+[farmOS Location Logic](/model/logic/location).
+
+See related fields "Intrinsic geometry" and "Is fixed" below.
+
+#### Intrinsic geometry
+
+If an Asset is "fixed" in location (see "Is fixed" below), then it can have an
+"intrinsic geometry" to describe where it exists. This is only used if the
+Asset is designated as "fixed". Otherwise, its geometry and location are
+determined by movement Logs.
+
+For more information, see [farmOS Location Logic](/model/logic/location).
+
+#### Is location
+
+An Asset can be designated as a "location" to indicate that other Assets may be
+moved to it using movement Logs.
+
+For more information, see [farmOS Location Logic](/model/logic/location).
+
+#### Is fixed
+
+Assets can be designated as "fixed" to indicate that they do not move around
+in space and time. Examples of fixed Assets include land, buildings, water
+sources, fixed infrastructure such as pivot irrigation systems, etc. If an
+Asset is fixed, then it can have "intrinsic geometry" (see "Intrinsic geometry"
+above). Otherwise, its geometry and location can change over time, as
+determined by movement Logs.
+
+For more information, see [farmOS Location Logic](/model/logic/location).
+
+#### Notes
+
+Notes can be added to an Asset to describe it in more detail. This is a
+freeform text field that allows a limited set of HTML tags, including links,
+lists, blockquotes, emphasis, etc.
+
+#### ID Tags
+
+Often an Asset will have ID tags associated with it. For example, an animal may
+have an RFID collar or an ear tag with a unique ID. ID tags in farmOS can
+store this ID, as well as its type and location.
+
+#### Data
+
+Assets have a hidden "data" field on them that is only accessible via the API.
+This provides a freeform plain text field that can be used to store additional
+data in any format (eg: JSON, YAML, XML). One use case for this field is to
+store remote system IDs that correspond to the Asset. So if the Asset is
+created or managed by software outside of farmOS, it can be identified easily.
+It can also be used to store additional structured metadata that does not fit
+into the standard Asset attributes.
+
+### Additional attributes
+
+Assets *may* contain additional attributes:
+
+- Inventory
+
+#### Inventory
+
+The inventory attribute summarizes current Asset inventory levels. This field
+is not editable itself, but is rather computed based on "inventory adjustment"
+logs. Each inventory can have a "measure", "value", and "units".
+
+For more information, see [farmOS Inventory Logic](/model/logic/inventory).
+
+This field is added to all Asset types by default only if the Inventory module
+is enabled.
+
+## Relationships
+
+Assets can be related to other records in farmOS These relationships are
+stored as reference fields on Asset records.
+
+All Assets have the same standard set of relationships. Modules can add
+additional relationships.
+
+Relationships that are common to all Asset types include:
+
+- Location
+- Parents
+- Owners
+- Images
+- Files
+
+#### Location
+
+Similar to the Asset "Geometry" field described above, an Asset's location
+describes where it is. Whereas the "Geometry" field contains raw geometry
+data (points, lines, and polygons), this field is a reference to one or more
+other Assets, which themselves are designated as "locations" (see "Is location"
+attribute above). If an Asset is designated as "fixed" then it can have an
+"intrinsic geometry" (see "Intrinsic geometry" above), but it will not have a
+location.
+
+For more information, see [farmOS Location Logic](/model/logic/location).
+
+#### Parents
+
+Assets can specify "Parent" Assets that they descend from. This creates a
+lineage relationship that can be used to track breeding of Plant and Animal
+Assets. It can also be used to create more general hierarchical relationships
+between Assets such as representing a "bed" inside a "field" (represented by
+two Land Assets related through the Parents field).
+
+Multiple parents are allowed, but circular relationships are not.
+
+#### Owners
+
+Assets can be assigned to one or more Users in farmOS.
+
+#### Images
+
+Images can be attached to Assets. This provides a place to store photos of the
+Asset.
+
+#### Files
+
+Files can be attached to Assets. This provides a place to put documents such as
+Shapefiles, PDFs, CSVs, or other files associated with the Asset.
+
+### Additional relationships
+
+Assets *may* contain additional relationships:
+
+- Group membership
+
+#### Group membership
+
+The group membership of an Asset references Group Assets which the Asset is a
+member of. This field is not editable itself, but is rather computed based on
+"group assignment" logs.
+
+For more information, see [farmOS Group Membership Logic](/model/logic/group).
+
+This field is added to all Log types by default only if the Group module is
+enabled.
+
+## Type-specific fields
+
+In addition to the fields that are common to all Asset types described
+above, some types add additional type-specific fields. These include:
+
+#### Animal Assets
+
+Animal Assets have the following additional attributes:
+
+- Birthdate (timestamp)
+- Is castrated (boolean)
+- Nicknames (multiple strings)
+- Sex ("F" or "M" string)
+
+And the following additional relationships:
+
+- Animal type (References a Term in the "Animal type" vocabulary)
+
+#### Equipment Assets
+
+Equipment Assets have the following additional attributes:
+
+- Manufacturer (string)
+- Model (string)
+- Serial number (string)
+
+#### Land Assets
+
+Land Assets have the following additional attributes:
+
+- Land type (string)
+
+#### Material Assets
+
+Material Assets have the following additional relationships:
+
+- Material type (references a Term in the "Material type" vocabulary)
+
+#### Plant Assets
+
+Plant Assets have the following additional relationships:
+
+- Plant type (references a Term in the "Plant type" vocabulary)
+- Season (references a Term in the "Season" vocabulary)
+
+#### Product Assets
+
+Product Assets have the following additional relationships:
+
+- Product type (references a Term in the "Product type" vocabulary)
+
+#### Sensor Assets
+
+Sensor Assets have an additional "Data streams" relationship, which is used to
+reference [Data Streams](/model/type/data_stream) associated with the sensor.
+
+#### Structure Assets
+
+Structure Assets have the following additional attributes:
+
+- Structure type (string)

web/profiles/farm/docs/model/type/data_stream.md

@@ -0,0 +1,101 @@
+# Data Streams
+
+Data Streams are records that represent sets of data streamed from sensors or
+other real-world devices.
+
+## Type
+
+Each Data Stream must have a type. All Asset types have a common set of
+attributes and relationships. Specific Data Stream types may also add
+additional attributes and relationships (collectively referred to as "fields").
+Data Stream types are defined by modules, and are only available if their
+module is enabled. The modules included with farmOS define the following Data
+Stream types:
+
+- Basic
+- Listener (Legacy)
+
+## ID
+
+Each Data Stream will be assigned two unique IDs in the database: a universally
+unique identifier (UUID), and an internal numeric ID.
+
+The UUID will be unique **across** farmOS databases. The internal ID will only
+be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs
+to ensure that IDs pulled from multiple farmOS databases do not conflict.
+Internally, farmOS modules use the internal IDs to perform CRUD operations.
+
+## Attributes
+
+Data Streams have a number of attributes that serve to describe their meta
+information. All Data Stream have the same standard set of attributes. Modules
+can add additional attributes.
+
+### Standard attributes
+
+Attributes that are common to all Data Stream types include:
+
+- Name
+- Private key
+- Public
+
+#### Name
+
+Data Streams must have a name that describes them. The name is used in lists of
+Data Streams to easily identify them at quick glance.
+
+#### Private key
+
+A Data Stream's private key is the password used to post data to (and get data
+from) its API endpoint.
+
+#### Public
+
+A Data Stream may be marked as "public" to allow read-access from the API
+without a private key. This is useful for loading data into public
+third-party apps or scripts, for graphing or other purposes. Data Streams
+are not public by default.
+
+## Relationships
+
+Data Streams can be related to other records in farmOS These relationships are
+stored as reference fields on Data Stream records.
+
+All Data Streams have the same standard set of relationships. Modules can add
+additional relationships.
+
+Relationships that are common to all Data Streams types include:
+
+- Assets
+
+#### Assets
+
+Data Streams can reference one or more Assets to indicate that the data they
+collect is directly relevant to them.
+
+For example, if a soil moisture sensor that is installed in a field can be
+represented with a Sensor Asset (for the soil moisture sensor device itself),
+with a Data Stream (soil moisture data readings), that reference a Land Asset
+(the field it is installed in). This makes it possible for a single device to
+be moved/reused for monitoring multiple Assets, by moving the Sensor Asset
+and creating new Data Streams.
+
+## Type-specific fields
+
+In addition to the fields that are common to all Data Stream types described
+above, some types add additional type-specific fields. These include:
+
+#### Basic Data Streams
+
+Basic Data Streams do not define any type-specific fields.
+
+#### Listener (Legacy) Data Streams
+
+Listener (Legacy) Data Streams have an additional "public key" attribute,
+which is used in the Data Stream's API endpoint for posting/getting data. This
+was used in farmOS v1 to provide a unique ID for the sensor, separate from the
+Sensor Asset ID that housed the data. This is no longer needed in farmOS v2+,
+because each Data Stream has its own UUID, which is used in the API endpoints
+instead. The public key is retained for Legacy (Listener) Data Streams to
+ensure that existing sensors can continue to push data without needing to be
+reconfigured.

web/profiles/farm/docs/model/type/file.md

@@ -0,0 +1,5 @@
+# Files
+
+Files can be uploaded to farmOS and associated with
+[Assets](/model/type/asset), [Logs](/model/type/log), and
+[Plans](/model/type/plan).

web/profiles/farm/docs/model/type/log.md

@@ -0,0 +1,308 @@
+# Logs
+
+Logs represent events, both active and passive. Observations, harvests, and
+inputs are all types of Logs. Modules can provide additional Log types.
+
+## Type
+
+Each Log must have a type. All Log types have a common set of attributes and
+relationships. Specific Log types may also add additional attributes and
+relationships (collectively referred to as "fields"). Log types are defined by
+modules, and are only available if their module is enabled. The modules
+included with farmOS define the following Log types:
+
+- Activity
+- Observation
+- Input
+- Harvest
+- Lab test
+- Maintenance
+- Medical
+- Seeding
+- Transplanting
+
+## ID
+
+Each Log will be assigned two unique IDs in the database: a universally unique
+identifier (UUID), and an internal numeric ID.
+
+The UUID will be unique **across** farmOS databases. The internal ID will only
+be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs
+to ensure that IDs pulled from multiple farmOS databases do not conflict.
+Internally, farmOS modules use the internal IDs to perform CRUD operations.
+
+## Attributes
+
+Logs have a number of attributes that serve to describe their meta information.
+All Logs have the same standard set of attributes. Modules can add additional
+attributes.
+
+### Standard attributes
+
+Attributes that are common to all Log types include:
+
+- Name
+- Timestamp
+- Status
+- Flags
+- Geometry
+- Is movement
+- Notes
+- Data
+
+#### Name
+
+Logs must have a name that describes them. This will be automatically generated
+using a type-specific naming pattern if the Log is saved with an empty name.
+The name is used in lists of Logs to easily identify them at quick glance.
+
+#### Timestamp
+
+Logs always have a timestamp which indicates when they took place.
+
+#### Status
+
+Logs can be marked as "pending" or "done", to indicate whether they are
+"planned" or "actual" events. Every change that is made to a Log is stored as
+a revision, so that it's possible to see how a plan evolves over time until it
+eventually becomes a canonical record of the event that took place.
+
+#### Flags
+
+Flags can be added to Logs to help with sorting and filtering. farmOS provides
+a set of default flags, including "Priority", "Needs review", and "Monitor".
+Modules can provide additional flags, such as "Organic".
+
+#### Geometry
+
+Geometry data can be added to a Log to describe where it took place using
+points, lines, and polygons.
+
+When combined with the "Is movement" attribute (below), this will update the
+computed geometry of all Assets referenced on the Log.
+
+See the "Geometry" attribute of [Assets](/model/type/asset#geometry).
+For more information, see [farmOS Location Logic](/model/logic/location).
+
+#### Is movement
+
+A Log can be designated as a "movement" to indicate that any Assets referenced
+by it are being moved to the specified locations and/or geometry (see
+"Geometry" above and "Locations" below).
+
+If a Log is designated as a movement, and no location or geometry are defined,
+then the referenced Assets will no longer have a location or geometry.
+
+For more information, see [farmOS Location Logic](/model/logic/location).
+
+#### Notes
+
+Notes can be added to a Log to describe it in more detail. This is a freeform
+text field that allows a limited set of HTML tags, including links, lists,
+blockquotes, emphasis, etc.
+
+#### Data
+
+Logs have a hidden "data" field on them that is only accessible via the API.
+This provides a freeform plain text field that can be used to store additional
+data in any format (eg: JSON, YAML, XML). One use case for this field is to
+store remote system IDs that correspond to the Log. So if the Log is created
+or managed by software outside of farmOS, it can be identified easily. It can
+also be used to store additional structured metadata that does not fit into
+the standard Log attributes.
+
+### Additional attributes
+
+Logs *may* contain additional attributes:
+
+- Is group assignment
+
+#### Is group assignment
+
+A log can be designated as a "group assignment" to indicate that any Assets
+referenced by it are being assigned to the referenced Group Assets (see
+"Groups" below).
+
+If a Log is designated as a group assignment, and no Group Assets are referenced,
+then the referenced Assets will no longer be members of a group.
+
+For more information, see [farmOS Group Membership Logic](/model/logic/group).
+
+## Relationships
+
+Logs can be related to the **Assets** and location(s) they pertain to. They can
+have quantitative data via related **Quantities**. They can be assigned to the
+**Users** who are responsible for them. And they can be organized using
+**Terms** and other metadata.
+
+These relationships are stored as reference fields on Logs. References are
+uni-directional, meaning that Logs reference Assets, but Assets do not
+reference Logs. It is possible to retrieve all Logs that reference a particular
+Asset, as well as retrieve all Assets referenced by a Log.
+
+All Logs have the same standard set of relationships. Modules can add
+additional relationships.
+
+### Standard relationships
+
+Relationships that are common to all Log types include:
+
+- Assets
+- Locations
+- Quantities
+- Owners
+- Categories
+- Images
+- Files
+
+#### Assets
+
+Logs can specify which Assets they pertain to. Over time, this builds a rich
+historical record of everything that has happened to a particular Asset.
+
+#### Locations
+
+Logs can reference Assets that are designated as "locations" to indicate where
+they took place.
+
+This differs from the Assets relationship described above. The distinction is:
+
+- The "Asset" relationship means "this happened *TO* this Asset".
+- The "Location" relationship means "this happened *IN* this Asset".
+
+This distinction is important, and it makes intuitive sense for many use-cases.
+For example, if you are creating a Maintenance Log, you can say that it was
+maintenance applied to a tractor Asset (referenced in the "Asset" field), and
+it was performed in a barn Asset (referenced in the "Location" field).
+
+However, some cases are less intuitive - specifically when you want to represent
+an action that is being performed directly to Assets that are designated as
+locations.
+
+For example: if you are applying an input to a pasture (represented as an Asset
+of type "Land"), then the action is happening both *TO* the pasture and *IN*
+the pasture. In this case, the pasture Asset can be referenced in either or both
+the "Asset" and "Location" fields. This decision is left up to the
+[convention](/model/convention) of the end-user or module that implements it.
+
+When combined with the "Is movement" attribute (above), this will move all Assets
+referenced on the Log to the locations specified. For more information, see
+[farmOS Location Logic](/model/logic/location).
+
+See also: the "Is location" attribute of [Assets](/model/type/asset#is_location).
+
+#### Quantities
+
+Quantities are records that contain quantitative data. These are used to
+represent things like input amounts, harvest totals, time tracking, etc. For
+more information, see: [Quantities](/model/type/quantity).
+
+#### Owners
+
+Logs can be assigned to one or more Users in farmOS.
+
+#### Categories
+
+Logs can be assigned to one or more categories to help with sorting and
+filtering.
+
+Categories differ from the "Log Type" in a few ways:
+
+- A Log can be in multiple categories.
+- Categories of a Log can change.
+- The same set of Categories is available across all Log types.
+- Categories are optional, type is required.
+
+Categories are therefore a more flexible and dynamic method of organizing
+sets of Logs, regardless of type.
+
+Categories differ from "Flags" in that categories only apply to Logs. Flags can
+be applied to Assets, Plans, and Logs. Flags are intended to bring attention to
+a Log, and are often highlighted in the UI. Flags may also be added and removed
+from a Log (eg: adding/removing the "Needs review" flag), whereas categories
+will tend to be fixed.
+
+Flags are also more strictly defined and controlled than categories. Categories
+are Terms in the "Log categories" vocabulary, so they can be added, edited,
+deleted, and rearranged through the UI. Flags must be defined in code by a
+module.
+
+#### Images
+
+Images can be attached to Logs. This provides a place to store photos associated
+with the task.
+
+#### Files
+
+Files can be attached to Logs. This provides a place to put documents such as
+Shapefiles, PDFs, CSVs, or other files associated with the task.
+
+### Additional relationships
+
+Logs *may* contain additional relationships:
+
+- Equipment used
+- Groups
+
+#### Equipment used
+
+Logs can specify which Equipment Assets were used to perform a task.
+
+This differs from the Assets field (described above), which is for referencing
+the Assets that were the focus of the task. For example, if a Tractor is used
+to cultivate a field, the "Equipment used" field would reference the Tractor,
+and the "Assets" field would reference a Land Asset representing the field.
+
+This field is added to all Log types by default only if the Equipment module is
+enabled.
+
+#### Groups
+
+Logs can reference Group Assets, along with the "Is group assignment" attribute
+(above) to indicate which group(s) the Assets will be members of.
+
+This field is added to all Log types by default only if the Group module is
+enabled.
+
+For more information, see [farmOS Membership Logic](/model/logic/group).
+
+## Type-specific fields
+
+In addition to the fields that are common to all Log types described
+above, some types add additional type-specific fields. These include:
+
+#### Harvest Logs
+
+Harvest Logs have the following additional attributes:
+
+- Lot number (string)
+
+#### Input Logs
+
+Input Logs have the following additional attributes:
+
+- Lot number (string)
+- Method (string)
+- Purchase date (timestamp)
+- Source (string)
+
+#### Lab Test Logs
+
+Lab Test Logs have the following additional attributes:
+
+- Laboratory (string)
+- Test type (string)
+
+#### Medical Logs
+
+Medical Logs have the following additional attributes:
+
+- Veterinarian (string)
+
+#### Seeding Logs
+
+Seeding Logs have the following additional attributes:
+
+- Lot number (string)
+- Purchase date (timestamp)
+- Source (string)

web/profiles/farm/docs/model/type/plan.md

@@ -0,0 +1,148 @@
+# Plans
+
+Plans are higher-level records that organize Assets and Logs around a
+particular goal. Modules can provide Plan types, along with additional UI and
+logic for Assets and Logs that are managed by them.
+
+## Type
+
+Each Plan must have a type. All Plan types have a common set of attributes and
+relationships. Specific Plan types may also add additional attributes and
+relationships (collectively referred to as "fields"). Plan types are defined by
+modules, and are only available if their module is enabled.
+
+*farmOS core does not currently provide any Plan types.*
+
+## ID
+
+Each Plan will be assigned two unique IDs in the database: a universally unique
+identifier (UUID), and an internal numeric ID.
+
+The UUID will be unique **across** farmOS databases. The internal ID will only
+be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs
+to ensure that IDs pulled from multiple farmOS databases do not conflict.
+Internally, farmOS modules use the internal IDs to perform CRUD operations.
+
+## Attributes
+
+Plans have a number of attributes that serve to describe their meta information.
+All Plans have the same standard set of attributes. Modules can add additional
+attributes.
+
+### Standard attributes
+
+Attributes that are common to all Plan types include:
+
+- Name
+- Status
+- Flags
+- Notes
+- Data
+
+#### Name
+
+Plans must have a name that describes them. The name is used in lists of Plans
+to easily identify them at quick glance.
+
+#### Status
+
+Plans can be marked as "active" or "archived" to indicate their status.
+Archived Plans will be hidden from most lists in farmOS unless they are
+explicitly requested.
+
+#### Flags
+
+Flags can be added to Plans to help with sorting and filtering. farmOS
+provides a set of default flags, including "Priority", "Needs review", and
+"Monitor". Modules can provide additional flags, such as "Organic".
+
+#### Notes
+
+Notes can be added to a Plan to describe it in more detail. This is a freeform
+text field that allows a limited set of HTML tags, including links, lists,
+blockquotes, emphasis, etc.
+
+#### Data
+
+Plans have a hidden "data" field on them that is only accessible via the API.
+This provides a freeform plain text field that can be used to store additional
+data in any format (eg: JSON, YAML, XML). One use case for this field is to
+store remote system IDs that correspond to the Plan. So if the Plan is
+created or managed by software outside of farmOS, it can be identified easily.
+It can also be used to store additional structured metadata that does not fit
+into the standard Plan attributes.
+
+## Relationships
+
+Plans can reference other record types (like Assets and Logs) that are "part of
+the Plan". These relationships can be simple (referencing the Asset/Log ID), or
+a Plan-type providing module can define more complex relationships by including
+other metadata alongside it.
+
+For example, a Crop Plan might reference a set of Plant Assets that represent
+the crops being grown in a particular season. Apart from just referencing the
+Plant Asset IDs, a Crop Plan may also reference specific Seeding and/or
+Transplanting Log IDs alongside those Plantings. It may also include attributes
+that are specific to the particular planning process that is being modelled. In
+addition to the Asset and Log IDs, perhaps a Crop Plan wants to store pieces of
+information like "days to harvest" or "harvest window" for each Plant Asset.
+These pieces of information do not belong on the Asset level itself, because
+they are specific to the Plan*. Therefore, they should be thought of as
+metadata of the relationship itself.
+
+Another example might be an Input Plan, that allows users to enter "Target" and
+"Actual" values for the amounts of a material that was applied. This Plan could
+create relationships to the Input Logs that it manages. The "Actual" quantity
+of material applied would be stored on the Input Log itself, but the "Target"
+is stored in the relationship between the Plan and the Log.
+
+* It is worth noting that some of this data may *also* be stored generally
+on Terms, and copied to the Plan when it is instantiated. For example: imagine
+a Crop/variety Term that has a "days to harvest" attribute on it, allowing you
+to define this as a system-wide default that is then copied into your Crop Plan
+when you create a new Plant Asset that references the Crop/variety Term. This
+allows the value to be overridden on the Plan+Asset level, in case conditions
+require it to.
+
+### Standard relationships
+
+All Plans have the same standard set of relationships. Modules can add
+additional relationships.
+
+Relationships that are common to all Plan types include:
+
+- Files
+- Images
+
+#### Images
+
+Images can be attached to Plans. This provides a place to store photos that can
+be displayed alongside the Plan in farmOS. If the photos pertain to specific
+Assets or Logs within the Plan, it may be better to attach them to those
+records instead of the Plan.
+
+#### Files
+
+Files can be attached to Plans. This provides a place to put documents such as
+Shapefiles, PDFs, CSVs, or other files associated with the Plan. If the files
+pertain to specific Assets or Logs within the Plan, it may be better to attach
+them to those records instead of the Plan.
+
+### Additional relationships
+
+Plans *may* contain additional relationships:
+
+- Assets
+- Logs
+
+However, the module that is providing the Plan type may decide to replace these
+with more advanced Asset/Log relationships if necessary. So the exact
+relationships may vary by Plan type.
+
+#### Assets
+
+Plans can reference Assets that are part of the Plan.
+
+#### Logs
+
+Plans can reference Logs that are part of the Plan.

web/profiles/farm/docs/model/type/quantity.md

@@ -0,0 +1,144 @@
+# Quantities
+
+A Quantity in farmOS is a granular unit of quantitative data used to represent
+a single data point.
+
+Quantities do not exist on their own, but rather are created with and are
+referenced by [Logs](/model/type/log). Logs provide the supporting metadata to
+give context to the data stored in Quantities, including timestamp, location,
+relation to [Assets](/model/type/asset), etc.
+
+## Type
+
+Each Quantity must have a type. All Quantity types have a common set of
+attributes and relationships. Specific Quantity types (also called "bundles")
+may also add additional attributes and relationships (collectively referred to
+as "fields"). Quantity types are defined by modules, and are only available if
+their module is enabled. The modules included with farmOS define the following
+Quantity types:
+
+- Standard
+- Material
+- Test
+
+## ID
+
+Each Quantity will be assigned two unique IDs in the database: a universally
+unique identifier (UUID), and an internal numeric ID.
+
+The UUID will be unique **across** farmOS databases. The internal ID will only
+be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs
+to ensure that IDs pulled from multiple farmOS databases do not conflict.
+Internally, farmOS modules use the internal IDs to perform CRUD operations.
+
+## Attributes
+
+Quantities have a number of attributes that serve to describe their meta
+information. All Quantities have the same standard set of attributes. Modules
+can add additional attributes.
+
+### Standard attributes
+
+Attributes that are common to all Quantity types include:
+
+- Measure
+- Value
+- Label
+
+#### Measure
+
+The Measure attribute can be used to specify what type of measurement is being
+recorded. The available options are:
+
+- Count
+- Length/depth
+- Weight
+- Area
+- Volume
+- Time
+- Temperature
+- Pressure
+- Water content
+- Value
+- Rate
+- Rating
+- Ratio
+- Probability
+
+#### Value
+
+The Quantity value is a decimal number. Internally this is represented as two
+integers (numerator and denominator).
+
+#### Label
+
+A Quantity may have a label assigned to it. This helps to distinguish multiple
+Quantities of the same measure within a Log.
+
+### Additional attributes
+
+Quantities *may* contain additional attributes:
+
+- Inventory adjustment
+
+#### Inventory adjustment
+
+A Quantity can be designated as an "inventory adjustment" to reset, increment,
+or decrement the inventory of Assets referenced (see "Inventory asset" below).
+
+For more information, see [farmOS Inventory Logic](/model/logic/inventory).
+
+## Relationships
+
+All Quantities have the same standard set of relationships. Modules can add
+additional relationships.
+
+### Standard relationships
+
+Relationships that are common to all Quantity types include:
+
+- Unit
+
+#### Unit
+
+The Unit of measurement is stored as a [Term](/model/type/term) in the Units
+vocabulary.
+
+### Additional relationships
+
+Quantities *may* contain additional relationships:
+
+- Inventory asset
+
+#### Inventory asset
+
+Quantities can reference Assets, along with the "Inventory adjustment"
+attribute (above) to record adjustments to the Asset's inventory.
+
+This field is added to all Quantity types by default only if the Inventory
+module is enabled.
+
+For more information, see [farmOS Inventory Logic](/model/logic/inventory).
+
+## Type-specific fields
+
+In addition to the fields that are common to all Quantity types described
+above, some types add additional type-specific fields. These include:
+
+#### Standard Quantities
+
+Standard Quantities do not define any type-specific fields.
+
+#### Material Quantities
+
+Material Quantities are the default type on Input logs. They have the
+following additional relationships:
+
+- Material type (References Terms in the "Material types" vocabulary)
+
+#### Test Quantities
+
+Test Quantities are the default type on Lab test logs. They have the following
+additional relationships:
+
+- Test method (References Terms in the "Test methods" vocabulary)

web/profiles/farm/docs/model/type/term.md

@@ -0,0 +1,113 @@
+# Terms
+
+Vocabularies (also referred to as taxonomies or ontologies) are used to
+organize and manage Terms used in various contexts throughout farmOS. These can
+be used for flagging, categorization, and organization of other record types.
+
+Most Terms in farmOS are user-defined, and the vocabularies are empty when
+farmOS is first installed. As [Logs](/model/type/log) and
+[Assets](/model/type/asset) are created, Terms that are used to describe them
+are automatically generated in the appropriate vocabularies. These can then be
+used to filter records in the future.
+
+## Type
+
+Each term must have a type, which is a reference to the vocabulary that it is
+in. Vocabularies are defined by modules, and are only available if their module
+is enabled. The modules included with farmOS define the following vocabularies:
+
+- Animal type
+- Log category
+- Material type
+- Plant type
+- Product type
+- Season
+- Unit
+
+## ID
+
+Each Term will be assigned two unique IDs in the database: a universally unique
+identifier (UUID), and an internal numeric ID.
+
+The UUID will be unique **across** farmOS databases. The internal ID will only
+be unique to a **single** farmOS database. Therefore, the farmOS API uses UUIDs
+to ensure that IDs pulled from multiple farmOS databases do not conflict.
+Internally, farmOS modules use the internal IDs to perform CRUD operations.
+
+## Attributes
+
+Terms have a number of attributes that serve to describe their meta information.
+All Terms have the same standard set of attributes. Modules can add additional
+attributes.
+
+### Standard attributes
+
+Attributes that are common to all Term types include:
+
+- Name
+- Description
+- Ontology URI
+- Weight
+
+#### Name
+
+Terms must have a name.
+
+#### Description
+
+Optionally, Terms may have a description.
+
+#### Ontology URI
+
+Terms may link to one or more external ontology URIs.
+
+#### Weight
+
+The Term's weight determines how it is ordered in the vocabulary. See related
+"Parent" relationship below for organizing Terms into a hierarchy.
+
+## Relationships
+
+All Terms have the same standard set of relationships. Modules can add
+additional relationships.
+
+### Standard relationships
+
+Relationships that are common to all Term types include:
+
+- Parent
+- Images
+- Files
+
+#### Parent
+
+Terms can specify "Parent" Terms to create a hierarchy. See related "Weight"
+attribute above for ordering Terms within the hierarchy.
+
+#### Images
+
+Images can be attached to Terms. This provides a place to store associated
+photos.
+
+#### Files
+
+Files can be attached to Terms. This provides a place to put documents such as
+Shapefiles, PDFs, CSVs, or other associated files.
+
+## Type-specific fields
+
+In addition to the fields that are common to all Term types described
+above, some types add additional type-specific fields. These include:
+
+#### Plant Type Terms
+
+Terms in the "Plant type" vocabulary have the following additional attributes:
+
+- Days to maturity (Integer)
+- Days to transplant (Integer) (Added by the optional Transplanting module)
+- Days of harvest (Integer)
+
+And the following additional relationships:
+
+- Companions (references other Terms in the "Plant type" vocabulary)
+- Crop family (references a Term in the "Crop Family" vocabulary)

web/profiles/farm/docs/model/type/user.md

@@ -0,0 +1,8 @@
+# Users
+
+Users can log into farmOS with their own user accounts, each with a unique
+user name and email address. These accounts can be granted different roles,
+which include sets of permissions that give the user access to specific farmOS
+data and features.
+
+[Logs](/model/type/log) can be assigned to Users.