Open Substance Information Standard (OSIS)
Functional Requirements Specification — Draft v0.1
Project: Barkly Labs Status: Draft for community review Version: 0.1 Purpose: Open, interoperable substance information and harm-reduction infrastructure
1. Purpose
The Open Substance Information Standard (OSIS) defines a vendor-neutral framework for identifying substance-related products, associating products and samples with relevant information, and communicating drug-checking results and uncertainty to the public.
The system is intended to help people make more informed decisions by making relevant information easier to find, understand, and verify.
OSIS must distinguish between information supplied by a seller, manufacturer, or community member and information supported by independent testing.
Core principle: People should be able to access understandable, evidence-based information about substances without needing to trust an unverified label or disclose their identity.
2. Scope
OSIS covers:
Product and sample identification.
Machine-readable identifiers, including QR codes and NFC tags.
Standardized substance information records.
Links to qualified drug-checking and laboratory results.
Reporting of detected substances and relevant testing limitations.
Community-submitted observations and alerts.
Provenance, timestamps, and verification status.
Privacy-preserving public access.
Interoperability between independent applications and services.
OSIS does not itself chemically identify substances, certify a product as safe, replace professional laboratory testing, or guarantee the accuracy of submitted records.
3. Definitions
Product: An item represented as containing a substance or mixture.
Sample: A specific physical specimen submitted for analysis.
Batch: A group of products claimed to share a common production or supply origin.
Identifier: A machine-readable code associated with a product, sample, or record.
Claimed composition: Information about contents supplied by a manufacturer, seller, or other source that has not necessarily been independently verified.
Test result: Findings reported by a documented testing process, associated with a particular sample and method.
Verified record: A record whose source or integrity has been checked according to a documented verification procedure. This does not mean every claim in the record is independently confirmed.
Unknown: Information that is unavailable, untested, inconclusive, or otherwise not established.
4. Functional requirements
FR-001 — Unique record identification
The system MUST assign or recognize a unique identifier for each registered record.
The identifier MUST distinguish a product record from a specific sample's testing record.
The system MUST NOT imply that two physical items have identical contents solely because they share a product or batch identifier.
FR-002 — Multiple identification methods
Implementations MUST support a documented method of opening a record using a machine-readable identifier.
The standard SHOULD support QR codes and MAY support NFC tags or other compatible technologies.
A user MUST also be able to search for publicly available records without owning an NFC-compatible device.
FR-003 — Claimed contents
A record MUST support the publication of claimed contents when such information is available.
Each claim MUST identify its source and indicate whether it has been independently confirmed.
The system MUST NOT automatically classify seller-provided or manufacturer-provided claims as laboratory findings.
FR-004 — Sample-specific test results
The system MUST support test results associated with an individual sample.
A test-result record MUST identify, when available:
The testing organization or service.
The date of analysis.
The analytical method or method category.
The substances reported as detected.
Reported quantities or concentrations, when measured and provided.
Relevant limitations, uncertainty, and interpretive notes.
The sample identifier to which the findings apply.
Unavailable fields MUST be marked as unknown or not provided rather than fabricated.
FR-005 — Distinction between product and sample
The system MUST clearly distinguish product-level information from sample-specific findings.
A result for one sample MUST NOT be presented as proof of the composition of every product sharing its name, packaging, or batch label.
When a result is associated with a batch, the record MUST explain the basis for that association and its limitations.
FR-006 — Testing limitations
The system MUST display relevant limitations of each test result.
A substance not reported as detected MUST NOT automatically be described as absent.
The system MUST distinguish, where applicable, between:
Detected.
Not detected by the reported method.
Inconclusive.
Not tested.
Unknown.
FR-007 — Evidence provenance
Every substantive claim or test result MUST retain its source information.
The system MUST record the source type, relevant timestamps, and verification status.
Records SHOULD preserve a history of material corrections and updates so that changes can be reviewed.
FR-008 — Community submissions
Implementations MAY accept community-submitted reports, observations, and warnings.
Community submissions MUST be distinguishable from laboratory results and independently verified information.
The system SHOULD provide moderation, duplicate-report handling, correction requests, and procedures for flagging potentially misleading submissions.
FR-009 — Public warnings
The system SHOULD support warnings concerning reported unexpected substances, contamination, or other relevant hazards.
Warnings MUST include the available evidence, source, publication date, and scope.
The system MUST NOT generalize a warning beyond the evidence supporting it.
FR-010 — Search and discovery
Users MUST be able to search records using available identifiers and relevant descriptive fields.
Implementations SHOULD support searching by substance name, product name, sample identifier, testing organization, date, and location at an appropriately privacy-preserving level.
Search results MUST display enough context to prevent a result for one sample from being mistaken for a universal finding about a substance or product.
FR-011 — Understandable presentation
The user interface MUST distinguish claimed information, community reports, and documented test results through clear labels.
The interface MUST explain important uncertainty in plain language.
The system MUST NOT display a generic “safe” status merely because a record exists, a product has been tested, or a particular substance was not detected.
FR-012 — Open interoperability
The standard MUST document its data fields, permitted values, identifier rules, and versioning policy.
Independent developers MUST be able to implement compatible readers without requiring permission from a single commercial platform.
The standard SHOULD provide example records, a public schema, and conformance tests.
FR-013 — Offline and low-bandwidth access
Basic identification MUST NOT require a paid account or a proprietary application.
Implementations SHOULD provide lightweight public records suitable for low-bandwidth devices.
Where offline records are supported, the interface MUST indicate when the information was last updated and whether it may be stale.
FR-014 — Privacy
The system MUST NOT require a person's identity merely to read public information.
Public records MUST NOT contain unnecessary personal information about people who use, possess, or submit samples.
Implementations MUST document data collection, retention, and sharing practices.
Location and submission metadata MUST be handled in a way that minimizes risks to contributors.
FR-015 — Security and record integrity
Implementations MUST validate incoming records and handle malformed or unsupported data safely.
The standard SHOULD support authenticated publishers and tamper-evident records.
A valid identifier or digital signature MUST NOT be treated as proof that a substance's composition is safe or accurate.
FR-016 — Corrections and disputes
The system MUST provide a documented process for correcting inaccurate records.
Material corrections MUST preserve appropriate provenance and timestamps.
Disputed information MUST be identified as disputed while it is reviewed, where doing so is necessary to prevent misleading presentation.
FR-017 — Version compatibility
Each record MUST identify the version of the data standard it uses.
Implementations MUST handle unsupported versions without silently misinterpreting their fields.
Changes to the standard MUST be documented, and compatibility expectations MUST be defined for each release.
FR-018 — Accessibility
Public information MUST be presented in a format that supports accessible navigation and understandable text.
Implementations SHOULD support screen readers, keyboard navigation, mobile devices, and plain-language summaries.
5. Minimum information model
A conforming implementation MUST support the following conceptual entities:
Product record: Describes a product and its declared information.
Sample record: Identifies a particular sample without implying that it represents all similar items.
Test record: Documents the testing process and its reported findings.
Substance record: Provides a consistent reference for a substance name or identifier.
Source record: Describes the origin of a claim or report.
Warning record: Communicates an evidence-backed warning and its scope.
Revision record: Documents relevant corrections and updates.
The exact serialization format and required field definitions will be established in a separate data-schema document.
6. Nonfunctional requirements
NFR-001 — Reliability
Implementations SHOULD provide predictable behavior for missing, malformed, duplicate, or conflicting records.
NFR-002 — Performance
Basic public records SHOULD load promptly on ordinary mobile connections. Implementations SHOULD publish performance targets after measuring representative deployments.
NFR-003 — Maintainability
The standard MUST have a public change history and documented process for proposing and reviewing revisions.
NFR-004 — Scalability
The information model SHOULD support multiple independent data providers and growing record collections without requiring a single centralized database.
NFR-005 — Transparency
The standard MUST document the difference between technical conformance, source verification, and the scientific reliability of a test result.
NFR-006 — Language
Implementations SHOULD allow records and public explanations to be localized while preserving standardized field identifiers and original source information.
7. Acceptance criteria
An initial conforming implementation MUST demonstrate that:
A user can open a public record using its supported identifier.
A record can display claimed contents separately from test results.
A sample-specific test result cannot silently become a universal product claim.
Unknown, inconclusive, and not-tested statuses remain distinguishable.
Test limitations and source information are accessible to the user.
Community reports are clearly separated from documented laboratory findings.
Corrections and material record changes can be traced.
Invalid records and unsupported schema versions are handled explicitly.
Basic public information can be accessed without a paid account.
Public browsing does not require unnecessary personal information.
Another developer can validate the same sample records using the published schema and test suite.
8. Out of scope for version 0.1
The initial release will not:
Claim to identify a substance through NFC, QR codes, or packaging alone.
Guarantee the safety, purity, or authenticity of a product.
Treat unverified community reports as laboratory-confirmed findings.
Guarantee that a tested sample represents an entire batch.
Replace qualified analytical testing or professional interpretation.
Require a centralized commercial service for all records.
9. Development milestones
Milestone 1 — Data model: Define the core entities, field names, source types, and uncertainty labels.
Milestone 2 — Public specification: Publish the normative requirements, example records, and machine-readable schema.
Milestone 3 — Reference implementation: Develop a basic record reader and validator using synthetic data.
Milestone 4 — Evidence and provenance: Add test-result records, source attribution, revision history, and verification metadata.
Milestone 5 — Community review: Seek feedback from harm-reduction organizations, qualified drug-checking services, analytical laboratories, accessibility advocates, and people with lived experience.
Milestone 6 — Pilot release: Evaluate usability, privacy, data quality, and interoperability before declaring a stable release.
10. Guiding principle
OSIS exists to make reliable substance information easier to access, not to make unsupported assurances.
Every record should help a person understand what is known, how it is known, what remains uncertain, and where the evidence came from.
The standard should be open, transparent, privacy-preserving, and designed around the people who need the information most.