Cuanto Lexicons

Cuanto is built on the AT Protocol (aka atproto), a decentralized data storage and publishing protocol. In atproto, different kinds of data are defined by lexicons, and data that conform to a lexicon are stored in collections on their author's Personal Data Server (PDS). Cuanto defines a few of its own lexicons and reuses a few others. This page describes what they are and how they relate to each other. These lexicons are modeled after the Darwin Core Conceptual Model (DwC-CM) and designed to be exportable into a Darwin Core Data Package (DwC-DP), which are both data standards for storing and exchanging biodiversity data.

Each arrow points from the record that holds the reference to the one it references (two records that reference each other get one arrow each); the Relationships table below names the field for each. Dashed boxes are shared lexicons.bio records.

Lexicons for protocol authors

These records belong to people who author the protocols on Cuanto. SurveyProtocol is more akin to a DwC Protocol than a DwC Survey Protocol, the latter being more of a join model. The Cuanto ProtocolTarget has no analog in Darwin Core, but since protocol authors and surveyors can be different people on Cuanto, we needed a separate lexicon to specify what protocol authors want people to look for. The scope concept also derives from a previous DwC-related Humboldt Extension spec, but should be compatible with the current DwC-CM.

Protocol source

bio.cuanto.surveyProtocol

Defines the contents of a Survey, including what participants should look for and what fields they must fill out.

title: string
description: string
createdAt: datetime
requiredFields?: string[]
locationOptions?: place[]

ProtocolTarget source

bio.cuanto.protocolTarget

Subject for surveys following a Protocol.

protocol: at-uri
scope: (taxonScope | verbatimScope)[]

#taxonScope

A taxonomic criterion for a survey target.

taxonID?: uri
scientificName: string
vernacularName?: string
taxonRank: string
kingdom?: string

#verbatimScope

A free-text criterion for cases not covered by structured types (sensu Humboldt eco:verbatimTargetScope).

verbatimTargetScope: string

Lexicons for surveyors

These records belong to people who add surveys on Cuanto. Note that SurveyTarget duplicates a ProtocolTarget but belongs to the surveyor, so if the protocol author deletes or adds ProtocolTargets, the surveyor's copies remain in the surveyor's PDS and the Occurrences that reference them don't break. SurveyTarget is a closer analog to a DwC-CM Survey Target, except that there is only one record per user per ProtocolTarget, as opposed to one per Survey in DwC-CM, which would result in a lot of duplication (which does have to happen when exporting to DwC-DP).

Note that non-detections are inferred from SurveyTargets. A species counts as not detected for a Survey if a SurveyTarget for it exists in the surveyor's PDS, was created before the Survey, and was not retired before the Survey took place. A SurveyTarget is retired when its corresponding ProtocolTarget is deleted by the protocol author.

Occurrence and Identification are both reused from lexicons.bio. The actual count lives in organismQuantity in the Occurrence.

Follow source

bio.cuanto.surveyProtocol.follow

A user's declaration of intent to participate in surveys following a Protocol.

subject: at-uri
createdAt: datetime

SurveyTarget source

bio.cuanto.surveyTarget

A surveyor's copy of a protocol's target, created when the surveyor adopts a Protocol. Carries its own copy of the target scope so what was sought stays durable and under the surveyor's control even if the protocol author deletes the Protocol. Occurrences reference these via surveyTargetID.

protocol: at-uri
protocolTargetID: at-uri
createdAt: datetime
retiredAt?: datetime
scope: (taxonScope | verbatimScope)[]

Survey source

bio.cuanto.survey

An event where participants collect data required by a Survey Protocol.

protocol: strongRef
createdAt: datetime
samplingPerformedBy?: did[]
surveyorCount?: integer
eventDate?: string
eventDurationUnit?: string
eventDurationValue?: integer
location: place
track?: track

#track

A spatial path recorded during a survey.

gpx: blob
source: string

Occurrence source

bio.lexicons.temp.v0-1.occurrence

A biodiversity observation record following Darwin Core standards. Represents a single occurrence of an organism.

eventDate?: string
decimalLatitude?: string
decimalLongitude?: string
coordinateUncertaintyInMeters?: integer
media?: strongRef[]
taxonID?: uri
acceptedIdentificationID?: strongRef
surveyTargetID?: at-uri
eventID?: at-uri
organismQuantity?: string
organismQuantityType?: string

Identification source

bio.lexicons.temp.v0-1.identification

An identification suggestion for an existing observation. Used to propose or agree with a taxonomic identification.

occurrence: strongRef
scientificName: string
taxonRank?: string
kingdom?: string
taxonID?: uri
identificationRemarks?: string
vernacularName?: string

Relationships

The field on the referring record that carries each link.

ProtocolTarget → Protocol

field: protocolTarget.protocol
cardinality: N : 1

An author defines the targets of a protocol.

Survey → Protocol

field: survey.protocol
cardinality: N : 1

Surveys are conducted under a protocol (strongRef).

Follow → Protocol

field: follow.subject
cardinality: N : 1

Surveyors following a protocol.

SurveyTarget → Protocol

field: surveyTarget.protocol
cardinality: N : 1

Adopted targets keep a link to the protocol.

SurveyTarget → ProtocolTarget

field: surveyTarget.protocolTargetID
cardinality: N : 1

Provenance: which target this was copied from.

Occurrence → Survey

field: occurrence.eventID
cardinality: N : 1

Observations recorded during the survey.

Occurrence → SurveyTarget

field: occurrence.surveyTargetID
cardinality: N : 1

Which target an observation was meant to satisfy.

Identification → Occurrence

field: identification.occurrence
cardinality: N : 1

Proposed IDs for an observation (strongRef).

Occurrence → Identification

field: occurrence.acceptedIdentificationID
cardinality: N : 0..1

The ID the observer accepted (strongRef).

References marked strongRef pin an exact record version (CID + URI); the rest are plain AT-URIs.

References marked *strongRef* pin an exact record version (CID + URI); the rest are plain AT-URIs.
From	To	Reference field	Cardinality	Meaning
ProtocolTarget	Protocol	protocolTarget.protocol	N : 1	An author defines the targets of a protocol.
Survey	Protocol	survey.protocol	N : 1	Surveys are conducted under a protocol (strongRef).
Follow	Protocol	follow.subject	N : 1	Surveyors following a protocol.
SurveyTarget	Protocol	surveyTarget.protocol	N : 1	Adopted targets keep a link to the protocol.
SurveyTarget	ProtocolTarget	surveyTarget.protocolTargetID	N : 1	Provenance: which target this was copied from.
Occurrence	Survey	occurrence.eventID	N : 1	Observations recorded during the survey.
Occurrence	SurveyTarget	occurrence.surveyTargetID	N : 1	Which target an observation was meant to satisfy.
Identification	Occurrence	identification.occurrence	N : 1	Proposed IDs for an observation (strongRef).
Occurrence	Identification	occurrence.acceptedIdentificationID	N : 0..1	The ID the observer accepted (strongRef).