Contributing to OpenSensation™

Contributions enter through version-controlled YAML and pull requests. The public service has no write endpoints or user accounts. Until the canonical GitHub repository is configured, prepare a local branch or patch using this checkout; no repository owner or URL is invented here.

First contribution

Open a focused issue describing the concept or claim you want to change.
Fork or branch the canonical repository. Install the development dependencies using the README.
Add or edit one YAML file under the correct data/ collection. The filename must equal slug; id must be opensensation:<kind>:<slug>.
Describe the entity and give every relationship a local claim ID. Source-supported claims reference opensensation:source:<slug> records. Preserve uncertainties and species/device scope.
Run validation, tests, lint and graph export. Submit the diff, sources and limitations in a pull request.
A maintainer checks software/data integrity; a qualified reviewer checks scientific claims. Merge does not automatically make a claim expert-reviewed.

python -m scripts.validate_data
python -m pytest
python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m scripts.export_graph

Add a concept

Use a neighboring record as a formatting example and the JSON Schema as the complete contract. Do not copy its evidence status without support.

Concept	Directory	Required considerations
Modality	`data/modalities`	Classification and organism applicability; no default human applicability
Sensor	`data/sensors`	Artificial/hybrid classification, input and output relationships, implementation scope
Biological receptor	`data/receptors`	Biological mechanism, species and associated modality
Stimulus	`data/stimuli`	Physical quantity, units, multiple dimensions where applicable
Sensation	`data/sensations`	Encoded/sensed state separate from semantic meaning
Threshold or range	`data/thresholds`, `data/ranges`	Bounds, units, population/device, conditions and measurement method
Transduction	`data/transductions`	Conversion mechanism, input, output and nonlinear behavior
Signal	`data/signals`	Signal type, stage, units and known timing/noise properties
Processing	`data/processing`	Biological vs artificial mechanism; functional similarity is not equivalence
Context or percept	`data/contexts`, `data/percepts`	Conditions and candidate status; no deterministic interpretation
Capability	`data/capabilities`	A scoped function such as detect, measure or estimate
Limitation	`data/limitations`	Conditions, severity if known, and mitigation
Failure mode	`data/failure_modes`	Observable failure with evaluation definition
Source	`data/sources`	Real bibliographic metadata, URL, access date and source type
Evidence	`data/evidence`	Explicit association with the supported concept or claim

Numeric real-world ranges need source support. Synthetic examples must set illustrative: true and identify the fictional device/protocol. Unknown bounds should be null, not made-up averages. New units require a reviewed contract update, schema regeneration and tests. Never replace missing data with zero.

Challenge a claim

Identify the stable entity ID, local claim ID, dataset version, the contested statement, your reason and contradictory sources. Preserve the original position in the review history. Propose disputed when disagreement remains unresolved, explaining the scope; do not erase inconvenient evidence.

Submit an expert review

Create your own contributor record under data/contributors. Include display name, declared expertise, credential status and conflicts. Only share contact/credential information you consent to publish. Verification documentation should be handled privately by maintainers; do not put private evidence or identifiers in Git history. No credential verification service is implemented.

Create a review entity under data/reviews with a review block:

review:
  reviewer: opensensation:contributor:your-slug
  entity: opensensation:sensor:lidar
  claim: definition
  decision: needs_revision
  comments: Explain the precise scope that needs revision.
  sources: []
  contradictory_sources: []
  expertise: [sensor engineering]
  date: '2026-09-12'
  conflict_of_interest: Describe relevant interests or state none declared.
  dataset_version: 0.1.0

This is a block example, not a complete canonical record or a real submitted review. Add the normal entity ID, kind, slug, name, description and evidence. Use the actual review date. The reviewer must exist, and the entity and claim must resolve. Decisions are agree, qualified_agreement, disagree, insufficient_evidence, needs_revision, or outside_expertise. An expert_reviewed claim requires a matching affirmative review from a verified contributor. Credentials are scoped, revocable and do not settle scientific disputes.

Schema and releases

Edit app/schemas/entities.py, regenerate with python -m scripts.generate_schema, and include tests for the changed rule. Stable IDs should survive wording improvements. Deprecate before removal and record changes in the changelog. After merge and release, import the same canonical commit into PostgreSQL and optionally Neo4j. See the maintainer guide for rollback.

By submitting a contribution, you offer software and original text under Apache-2.0 and database contributions under ODC-By 1.0. Confirm you have rights to the material. Cite external publications instead of copying their full text.