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.

PROTOCOL AUTHORSSURVEYORSdefined bytargets fromfollowsfromcopiesdescribed bydescribed byduringcountsidentifiesacceptsProtocolcuantoProtocolTargetcuantoFollowcuantoSurveyTargetcuantoSurveycuantoOccurrencelexicons.bioIdentificationlexicons.bioRemarklexicons.bio
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. The optional kingdom through family fields and higherClassification follow the Darwin Core terms of the same names and are used to sort and group targets taxonomically.

taxonID?
uri
scientificName
string
vernacularName?
string
taxonRank
string
kingdom?
string
phylum?
string
class?
string
order?
string
family?
string
higherClassification?
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
eventRemarksID?
at-uri
#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[]
organismQuantity?
string
organismQuantityType?
string
occurrenceRemarksID?
at-uri
eventRemarksID?
at-uri
taxonID?
uri
acceptedIdentificationID?
strongRef
externalRecords?
externalRecord[]
eventID?
at-uri
surveyTargetID?
at-uri
#externalRecord

A reference to a record of this occurrence kept outside this lexicon, which may still be within the AT Protocol network. The target is an occurrence record, not a photo or other media item depicting the organism; media belong on the occurrence's media field. For a record held in another AT Protocol lexicon, reference it by its at-uri, which is canonical and does not tie the reference to any one appview. For anything else, use the canonical web URL of the occurrence record on the holding service.

uri
uri
service?
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
identificationRemarksID?
at-uri
vernacularName?
string
Remark source
bio.lexicons.temp.v0-1.remark

Free text that fills a Darwin Core remarks term on another record, such as dwc:occurrenceRemarks on an occurrence. Kept in its own record so authored prose, a potential creative work, can be attributed and licensed separately from the facts in the record it describes. The record it describes points to it with an AT-URI field named for the term (e.g. occurrence.occurrenceRemarksID), and that forward reference is authoritative: a remark nothing references fills no term. Not for discussion or replies.

subject
at-uri
dwcTerm
string
body
string
license?
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.

Survey β†’ Remark
field
survey.eventRemarksID
cardinality
1 : 1

The surveyor's remark about the survey, kept as its own record so the text can be licensed separately from the counts. The forward reference is authoritative: a remark nothing points at fills no Darwin Core term.

Occurrence β†’ Remark
field
occurrence.occurrenceRemarksID
cardinality
1 : 1

The surveyor's remark about one counted target, kept as its own record like the survey's remark.

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.