Skip to main content

sbol3/
lib.rs

1//! Rust support for the Synthetic Biology Open Language (SBOL) 3.1.0
2//! specification.
3//!
4//! The crate keeps RDF parsing and serialization behind a small adapter while
5//! exposing SBOL documents, typed builders, owned typed client objects, and
6//! structured validation diagnostics.
7//!
8//! ```
9//! use sbol3::constants::SBO_DNA;
10//! use sbol3::prelude::*;
11//!
12//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
13//! let component = Component::builder("https://example.org/lab", "my_component")?
14//!     .types([SBO_DNA])
15//!     .name("My component")
16//!     .build()?;
17//!
18//! let document = Document::from_objects(vec![SbolObject::Component(component)])?;
19//! document.check()?;
20//!
21//! assert_eq!(document.components().count(), 1);
22//! # Ok(())
23//! # }
24//! ```
25//!
26//! # Mental model
27//!
28//! SBOL describes designed biology as a graph of typed objects. Every object
29//! has a stable [`Iri`] identity, a `displayId`, and a namespace. Objects
30//! split into two layers:
31//!
32//! - **Top-level objects** live directly in a [`Document`]:
33//!   [`Component`] (the central design unit: DNA, RNA, protein, complexes,
34//!   functional descriptions), [`Sequence`], [`Collection`],
35//!   [`CombinatorialDerivation`], [`Implementation`], [`ExperimentalData`],
36//!   [`Experiment`], [`Model`], [`Attachment`], plus PROV-O activities
37//!   ([`Activity`], [`Plan`], [`Agent`]) and OM unit definitions ([`Unit`]
38//!   and friends).
39//! - **Owned children** belong to a top-level parent and live nested inside
40//!   it: [`SubComponent`] / [`LocalSubComponent`] /
41//!   [`ExternallyDefined`] / [`SequenceFeature`] / [`ComponentReference`]
42//!   hang off [`Component`]; [`Range`] / [`Cut`] / [`EntireSequence`] hang
43//!   off features; [`Interaction`]s contain [`Participation`]s;
44//!   [`Constraint`]s relate features.
45//!
46//! References between objects are typed: a [`SubComponent`] names the
47//! [`Component`] it instantiates, an [`ExternallyDefined`] points to a term in
48//! an external ontology, and so on. Reference traversal lives on the typed
49//! structs and takes anything implementing [`ObjectGraph`]: a [`Document`]
50//! for single-file work, a [`DocumentSet`] when references cross document
51//! boundaries.
52//!
53//! # Document lifecycle
54//!
55//! A typical flow:
56//!
57//! 1. **Read.** [`Document::read_path`] infers the format from the file
58//!    extension; [`Document::read`] takes an explicit [`RdfFormat`] for
59//!    in-memory input.
60//! 2. **Validate.** [`Document::validate`] returns a full
61//!    [`ValidationReport`] with errors, warnings, and per-rule coverage.
62//!    Use it when you want to inspect or render the report regardless of
63//!    pass/fail state. [`Document::check`] is the `?`-friendly convenience
64//!    that maps errors to `Err` (warnings ignored), and
65//!    [`Document::check_complete`] additionally fails on
66//!    partial-application diagnostics for strict CI gates.
67//! 3. **Traverse / mutate.** Typed accessors on [`Document`] iterate each
68//!    top-level class (`document.components()`, `document.sequences()`,
69//!    `document.activities()`, …). Builders ([`Component::builder`], etc.)
70//!    construct new objects without invalidating existing IRIs.
71//! 4. **Write.** [`Document::write`] takes an [`RdfFormat`];
72//!    `write_turtle`, `write_rdf_xml`, `write_jsonld`, and `write_ntriples`
73//!    are shortcut methods. Round-trip preserves unknown extension triples.
74//!
75//! # Error model
76//!
77//! Errors are surfaced through four distinct types so callers can branch on
78//! the failure mode without parsing strings:
79//!
80//! - [`ReadError`]: I/O or parse failure when ingesting RDF.
81//! - [`BuildError`]: invariant violation at builder time (invalid
82//!   `displayId`, malformed namespace, missing required field).
83//! - [`WriteError`]: serialization failure.
84//! - [`ValidationReport`]: structured diagnostics from validation
85//!   (multiple issues per call, each with its `sbol3-*` rule identifier).
86//!
87//! # Where to go next
88//!
89//! - **[Crate guide](https://github.com/SynBioDex/sbol-rs/blob/master/docs/crate-guide.md)**:
90//!   architectural tour and where each subsystem lives.
91//! - **[Validation system overview](https://github.com/SynBioDex/sbol-rs/blob/master/docs/validation.md)**:
92//!   what the validator covers, `check` vs `check_complete`, CI wiring,
93//!   trust boundaries.
94//! - **[RDF I/O](https://github.com/SynBioDex/sbol-rs/blob/master/docs/rdf-io.md)**:
95//!   format inference, round-trip guarantees, cross-implementation
96//!   conformance.
97//! - **[Conformance grid](https://github.com/SynBioDex/sbol-rs/blob/master/docs/conformance.md)**:
98//!   generated per-rule status for every SBOL 3.1.0 rule.
99//! - **[`prelude`]**: re-exports the symbols you'll need for most code;
100//!   `use sbol3::prelude::*;` is the conventional import. It includes the
101//!   [`SbolIdentified`] and [`SbolTopLevel`] accessor traits so methods
102//!   like `component.name()`, `component.display_id()`, and
103//!   `component.namespace()` are available on every typed object.
104//! - **[`constants`]**: IRIs for SBO / SO / EDAM / SBOL terms that show up
105//!   as builder arguments (`SBO_DNA`, `SO_PROMOTER`, etc.).
106
107#![forbid(unsafe_code)]
108// `check`/`check_complete` deliberately return the full ValidationReport in
109// both Ok and Err arms so callers always get the report; boxing the Err arm
110// would split that surface.
111#![allow(clippy::result_large_err)]
112
113mod client;
114mod conformance;
115pub mod constants;
116pub mod design;
117mod document;
118mod error;
119pub mod identity;
120mod model;
121mod object;
122pub mod owl_conformance;
123pub mod prelude;
124mod resolve;
125pub mod schema;
126mod specification;
127mod validation;
128#[doc(hidden)]
129pub mod vocab;
130
131pub use client::{
132    Activity, ActivityBuilder, Agent, AgentBuilder, Association, AssociationBuilder, Attachment,
133    AttachmentBuilder, BinaryPrefix, BinaryPrefixBuilder, Collection, CollectionBuilder,
134    CombinatorialDerivation, CombinatorialDerivationBuilder, Component, ComponentBuilder,
135    ComponentReference, ComponentReferenceBuilder, CompoundUnit, CompoundUnitBuilder, Constraint,
136    ConstraintBuilder, Cut, CutBuilder, EntireSequence, EntireSequenceBuilder, Experiment,
137    ExperimentBuilder, ExperimentalData, ExperimentalDataBuilder, ExtensionTriple,
138    ExternallyDefined, ExternallyDefinedBuilder, FeatureData, FeatureRef, IdentifiedData,
139    IdentifiedExtension, IdentifiedExtensionBuilder, Implementation, ImplementationBuilder,
140    Interaction, InteractionBuilder, Interface, InterfaceBuilder, LocalSubComponent,
141    LocalSubComponentBuilder, LocationData, LocationRef, Measure, MeasureBuilder, Model,
142    ModelBuilder, Participation, ParticipationBuilder, Plan, PlanBuilder, Prefix, PrefixBuilder,
143    PrefixData, PrefixedUnit, PrefixedUnitBuilder, Range, RangeBuilder, SIPrefix, SIPrefixBuilder,
144    SbolIdentified, SbolObject, SbolTopLevel, Sequence, SequenceBuilder, SequenceFeature,
145    SequenceFeatureBuilder, SingularUnit, SingularUnitBuilder, SubComponent, SubComponentBuilder,
146    ToRdf, TopLevelData, TryFromObject, Unit, UnitBuilder, UnitData, UnitDivision,
147    UnitDivisionBuilder, UnitExponentiation, UnitExponentiationBuilder, UnitMultiplication,
148    UnitMultiplicationBuilder, Usage, UsageBuilder, VariableFeature, VariableFeatureBuilder,
149};
150pub use conformance::render_conformance_report;
151pub use document::Document;
152pub use error::{BuildError, ReadError, WriteError};
153pub use identity::{DisplayId, HashAlgorithm, Namespace, SbolIdentity, SequenceElements};
154pub use model::{Identified, SbolClass, TopLevel};
155pub use object::ObjectClasses;
156pub use owl_conformance::{
157    OWL_ONLY_ALLOWLIST, OwlConformanceReport, OwlIdentifiers, OwlPinInfo, RUST_ONLY_ALLOWLIST,
158    analyze_owl_conformance, extract_owl_identifiers, extract_vocab_iris,
159    render_owl_conformance_report,
160};
161pub use resolve::{FeatureTrace, ObjectGraph, ReferenceError, VariantSet};
162pub use sbol_core::diff::{Diff, ObjectDiff, PropertyChange};
163pub use sbol_core::document::{ObjectStore, RawDocument};
164pub use sbol_core::object::Object;
165pub use sbol_ontology::{Ontology, OntologyRegistry};
166pub use sbol_rdf::{Graph as RdfGraph, Iri, Literal, RdfFormat, Resource, Term, Triple};
167pub use specification::{SPEC_VERSION, SPECIFICATION_URL};
168pub use validation::CachingHttpResolver;
169pub use validation::HttpResolver;
170pub use validation::{
171    AppliedOptions, Blocker, ContentResolver, CoverageKind, DocumentResolver, DocumentSet,
172    DocumentSetError, ExternalValidationMode, FileResolver, HashAlgorithmRegistry, Hint,
173    NormativeSeverity, NotApplied, NotAppliedReason, PartialApplication, PolicyOptions,
174    ResolutionError, ResolutionErrorKind, ResolvedContent, RuleCoverage, RuleOverride, RuleStatus,
175    Severity, TopologyCompleteness, UnknownRule, VALIDATION_OUTPUT_SCHEMA_VERSION,
176    VALIDATION_RULE_SPEC_CANONICAL_URL, VALIDATION_RULE_SPEC_PATH, VALIDATION_RULE_SPEC_PDF_SHA256,
177    VALIDATION_RULE_SPEC_VERSION, ValidationConfig, ValidationContext, ValidationIssue,
178    ValidationOptions, ValidationReport, ValidationRuleStatus, to_json, validation_rule_statuses,
179};