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.
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.
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[]
Subject for surveys following a Protocol.
- protocol
- at-uri
- scope
- (taxonScope | verbatimScope)[]
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
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.
A user's declaration of intent to participate in surveys following a Protocol.
- subject
- at-uri
- createdAt
- datetime
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)[]
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
A spatial path recorded during a survey.
- gpx
- blob
- source
- string
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
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
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
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.
- field
- protocolTarget.protocol
- cardinality
- N : 1
An author defines the targets of a protocol.
- field
- survey.protocol
- cardinality
- N : 1
Surveys are conducted under a protocol (strongRef).
- field
- follow.subject
- cardinality
- N : 1
Surveyors following a protocol.
- field
- surveyTarget.protocol
- cardinality
- N : 1
Adopted targets keep a link to the protocol.
- field
- surveyTarget.protocolTargetID
- cardinality
- N : 1
Provenance: which target this was copied from.
- 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.
- field
- occurrence.occurrenceRemarksID
- cardinality
- 1 : 1
The surveyor's remark about one counted target, kept as its own record like the survey's remark.
- field
- occurrence.eventID
- cardinality
- N : 1
Observations recorded during the survey.
- field
- occurrence.surveyTargetID
- cardinality
- N : 1
Which target an observation was meant to satisfy.
- field
- identification.occurrence
- cardinality
- N : 1
Proposed IDs for an observation (strongRef).
- 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.
| 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. |
| Survey | Remark | survey.eventRemarksID | 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 | occurrence.occurrenceRemarksID | 1 : 1 | The surveyor's remark about one counted target, kept as its own record like the survey's remark. |
| 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). |