Crate sbol

Expand description

Rust support for the Synthetic Biology Open Language (SBOL) 3.1.0 specification.

The crate keeps RDF parsing and serialization behind a small adapter while exposing SBOL documents, typed builders, owned typed client objects, and structured validation diagnostics.

use sbol::constants::SBO_DNA;
use sbol::prelude::*;

let component = Component::builder("https://example.org/lab", "my_component")?
    .types([SBO_DNA])
    .name("My component")
    .build()?;

let document = Document::from_objects(vec![SbolObject::Component(component)])?;
document.check()?;

assert_eq!(document.components().count(), 1);

§Mental model

SBOL describes designed biology as a graph of typed objects. Every object has a stable Iri identity, a displayId, and a namespace. Objects split into two layers:

Top-level objects live directly in a Document: Component (the central design unit — DNA, RNA, protein, complexes, functional descriptions), Sequence, Collection, CombinatorialDerivation, Implementation, ExperimentalData, Experiment, Model, Attachment, plus PROV-O activities (Activity, Plan, Agent) and OM unit definitions (Unit and friends).
Owned children belong to a top-level parent and live nested inside it: SubComponent / LocalSubComponent / ExternallyDefined / SequenceFeature / ComponentReference hang off Component; Range / Cut / EntireSequence hang off features; Interactions contain Participations; Constraints relate features.

References between objects are typed: a SubComponent names the Component it instantiates, an ExternallyDefined points to a term in an external ontology, and so on. Reference traversal lives on the typed structs and takes anything implementing ObjectGraph — a Document for single-file work, a DocumentSet when references cross document boundaries.

§Document lifecycle

A typical flow:

Read. Document::read_path infers the format from the file extension; Document::read takes an explicit RdfFormat for in-memory input.
Validate. Document::validate returns a full ValidationReport with errors, warnings, and per-rule coverage — use it when you want to inspect or render the report regardless of pass/fail state. Document::check is the ?-friendly convenience that maps errors to Err (warnings ignored), and Document::check_complete additionally fails on partial-application diagnostics for strict CI gates.
Traverse / mutate. Typed accessors on Document iterate each top-level class (document.components(), document.sequences(), document.activities(), …). Builders (Component::builder, etc.) construct new objects without invalidating existing IRIs.
Write. Document::write takes an RdfFormat; write_turtle, write_rdf_xml, write_jsonld, and write_ntriples are shortcut methods. Round-trip preserves unknown extension triples.

§Error model

Errors are surfaced through four distinct types so callers can branch on the failure mode without parsing strings:

ReadError — I/O or parse failure when ingesting RDF.
BuildError — invariant violation at builder time (invalid displayId, malformed namespace, missing required field).
WriteError — serialization failure.
ValidationReport — structured diagnostics from validation (multiple issues per call, each with its sbol3-* rule identifier).

§Where to go next

Crate guide — architectural tour and where each subsystem lives.
Validation system overview — what the validator covers, check vs check_complete, CI wiring, trust boundaries.
RDF I/O — format inference, round-trip guarantees, cross-implementation conformance.
Conformance grid — generated per-rule status for every SBOL 3.1.0 rule.
prelude — re-exports the symbols you’ll need for most code; use sbol::prelude::*; is the conventional import. It includes the SbolIdentified and SbolTopLevel accessor traits so methods like component.name(), component.display_id(), and component.namespace() are available on every typed object.
constants — IRIs for SBO / SO / EDAM / SBOL terms that show up as builder arguments (SBO_DNA, SO_PROMOTER, etc.).

Re-exports§

pub use identity::DisplayId;
pub use identity::HashAlgorithm;
pub use identity::Namespace;
pub use identity::SbolIdentity;
pub use identity::SequenceElements;

Modules§

constants: Common ontology IRIs for building SBOL documents.
identity: Validated identity helpers used by the typed builder surface.
prelude: Convenient re-exports for typical SBOL construction and inspection workflows.
schema: Public schema descriptors for SBOL classes and properties.

Structs§

Activity
ActivityBuilder: Builder for Activity.
Agent
AgentBuilder: Builder for Agent.
AppliedOptions: A summary of options that were active for this run. Round-trips through the JSON output schema so downstream readers know what coverage they’re looking at.
Association
AssociationBuilder: Builder for Association.
Attachment
AttachmentBuilder: Builder for Attachment.
BinaryPrefix
BinaryPrefixBuilder: Builder for BinaryPrefix.
CachingHttpResolver: Decorator that caches HttpResolver results on disk.
Collection
CollectionBuilder: Builder for Collection.
CombinatorialDerivation
CombinatorialDerivationBuilder: Builder for CombinatorialDerivation.
Component
ComponentBuilder: Builder for Component.
ComponentReference
ComponentReferenceBuilder: Builder for ComponentReference.
CompoundUnit
CompoundUnitBuilder: Builder for CompoundUnit.
Constraint
ConstraintBuilder: Builder for Constraint.
Cut
CutBuilder: Builder for Cut.
Document: An SBOL document parsed from RDF.
DocumentSet: A set of in-memory SBOL documents indexed by object identity.
DocumentSetError
EntireSequence
EntireSequenceBuilder: Builder for EntireSequence.
Experiment
ExperimentBuilder: Builder for Experiment.
ExperimentalData
ExperimentalDataBuilder: Builder for ExperimentalData.
ExtensionTriple: A non-SBOL annotation triple attached to a typed object.
ExternallyDefined
ExternallyDefinedBuilder: Builder for ExternallyDefined.
FeatureData: Shared owned fields for SBOL Feature objects.
FeatureTrace: The result of walking a ComponentReference chain to its leaf feature.
FileResolver: File-backed resolver for opt-in local validation.
HttpResolver: HTTP(S) resolver for opt-in external validation.
Identified: Shared fields on SBOL Identified objects.
IdentifiedData: Shared owned fields for SBOL Identified objects.
IdentifiedExtension: An RDF subject preserved through the typed model when no concrete SBOL class variant matched its rdf:type set. The Identified shared fields (displayId, name, …, derived_from, generated_by, measures, extensions) are populated as usual; when the subject also carried sbol:TopLevel semantics, top_level is Some. The rdf_types vector preserves every original rdf:type IRI so re-serialization emits exactly what the parser saw.
IdentifiedExtensionBuilder: Builder for IdentifiedExtension.
Implementation
ImplementationBuilder: Builder for Implementation.
Interaction
InteractionBuilder: Builder for Interaction.
Interface
InterfaceBuilder: Builder for Interface.
Iri: An RDF IRI.
Literal: RDF literal lexical data.
LocalSubComponent
LocalSubComponentBuilder: Builder for LocalSubComponent.
LocationData: Shared owned fields for SBOL Location objects.
Measure
MeasureBuilder: Builder for Measure.
Model
ModelBuilder: Builder for Model.
NotApplied: Per-rule not-applied record.
Object: An SBOL or SBOL extension object.
Ontology: Offline ontology query surface used by SBOL validation.
OntologyRegistry: A read-only view that layers zero-or-more extension snapshots on top of the bundled Ontology.
PartialApplication: Per-rule partial-application record.
Participation
ParticipationBuilder: Builder for Participation.
Plan
PlanBuilder: Builder for Plan.
PolicyOptions: Policy decisions that affect rule semantics. Conservative defaults match current behavior bit-for-bit; opting into Strict or Lenient changes the outcome of specific Policy-blocked rules.
Prefix
PrefixBuilder: Builder for Prefix.
PrefixData: Shared OM Prefix fields. Carried by every concrete Prefix subclass so the label/symbol/factor serializers can be reused.
PrefixedUnit
PrefixedUnitBuilder: Builder for PrefixedUnit.
Range
RangeBuilder: Builder for Range.
RdfGraph: Backend-opaque in-memory RDF graph.
ResolutionError: A resolver failure with a stable kind and human-readable context.
ResolvedContent: Resolved byte content for an Attachment or Model source.
RuleCoverage: Per-rule outcome for a single validation run.
SIPrefix
SIPrefixBuilder: Builder for SIPrefix.
Sequence
SequenceBuilder: Builder for Sequence.
SequenceFeature
SequenceFeatureBuilder: Builder for SequenceFeature.
SingularUnit
SingularUnitBuilder: Builder for SingularUnit.
SubComponent
SubComponentBuilder: Builder for SubComponent.
TopLevel: Shared fields on SBOL TopLevel objects.
TopLevelData: Shared owned fields for SBOL TopLevel objects.
Triple: An RDF triple in the default graph.
Unit
UnitBuilder: Builder for Unit.
UnitData: Shared OM Unit fields. Carried by every concrete Unit subclass so the label/symbol/comment serializers can be reused.
UnitDivision
UnitDivisionBuilder: Builder for UnitDivision.
UnitExponentiation
UnitExponentiationBuilder: Builder for UnitExponentiation.
UnitMultiplication
UnitMultiplicationBuilder: Builder for UnitMultiplication.
UnknownRule: Returned when a per-rule override targets a rule that is not in the catalog — almost always a typo at the call site.
Usage
UsageBuilder: Builder for Usage.
ValidationContext: Resolver-aware validation inputs.
ValidationIssue: A single SBOL validation issue.
ValidationOptions: Options for local SBOL validation.
ValidationReport: Structured validation result for a document.
ValidationRuleStatus
VariableFeature
VariableFeatureBuilder: Builder for VariableFeature.
VariantSet: The expanded variant Components for a CombinatorialDerivation.

Enums§

Blocker: Classification of why a Partial or Deferred validation rule is not yet fully implemented.
BuildError: Errors produced while building an SBOL document from owned typed objects.
CoverageKind: What a Partial rule’s local subset actually covered for this validation run. Stable, machine-grep-able tags so downstream tooling can filter rather than parse prose.
ExternalValidationMode: Controls whether validation may inspect resources outside the primary document.
FeatureRef: A child feature resolved from a Component’s hasFeature list.
HashAlgorithmRegistry: How sbol:hashAlgorithm values are validated.
Hint: Actionable hint surfaced alongside a diagnostic. Closed enum so renderers can pick a representation rather than scraping prose.
LocationRef: A child location resolved from a SequenceFeature’s hasLocation list.
NormativeSeverity: RFC2119-style normative force of a spec rule. Distinguishes “Partial-but-MUST” rules (gaps that block strict-mode compliance) from “Partial-but-SHOULD” rules (gaps in recommended-but-optional behavior).
NotAppliedReason: Why a rule did not run for this validation run.
RdfFormat: RDF serialization format.
ReadError: Errors produced while reading an SBOL document.
ReferenceError: Failure mode when resolving a typed SBOL reference.
ResolutionErrorKind: Coarse class of a resolution failure.
Resource: RDF subject resource.
RuleOverride: Per-rule override applied at issue-emit time.
RuleStatus: Per-rule classification. Five categories, each capturing one meaningful axis: algorithm complete with Error severity, algorithm complete with Warning severity, configurable (behavior depends on resolver / ontology snapshot / policy / external context), spec-▲ (not to be machine-reported), or unimplemented.
SbolClass: SBOL RDF classes handled by this crate.
SbolObject: Owned SBOL object variants supported by the client API.
Severity: Validation severity.
Term: RDF object term.
TopologyCompleteness: Controls whether validators assume missing nucleic-acid topology is knowable.
WriteError: Errors produced while writing an SBOL document.

Constants§

SPECIFICATION_URL: Canonical URL for the targeted SBOL specification.
SPEC_VERSION: The SBOL specification version targeted by this crate.
VALIDATION_OUTPUT_SCHEMA_VERSION: JSON schema version emitted by to_json. Bumps on any breaking rename/removal of fields.
VALIDATION_RULE_SPEC_CANONICAL_URL
VALIDATION_RULE_SPEC_PATH
VALIDATION_RULE_SPEC_PDF_SHA256
VALIDATION_RULE_SPEC_VERSION

Traits§

ContentResolver: Resolves an Attachment or Model source into bytes.
DocumentResolver: Resolves an external resource into an SBOL document.
ObjectGraph: In-memory scope of SBOL objects keyed by identity.
SbolIdentified: Read-only access to the shared metadata every SBOL Identified object carries: displayId, name, description, the PROV wasDerivedFrom / wasGeneratedBy resource sets, OM measures, and round-tripped non-SBOL extension triples.
SbolTopLevel: Read-only access to the metadata SBOL TopLevel objects carry on top of SbolIdentified: the document namespace and any attached sbol:Attachment resources.
ToRdf: Converts an owned typed SBOL value into RDF triples.
TryFromObject: Converts an RDF-collected object into an owned typed SBOL value.

Functions§

render_conformance_report: Renders the conformance report markdown for the supplied rule catalog. Pass validation_rule_statuses() to render the canonical committed report.
to_json: Serialize a ValidationReport to JSON v1.
validation_rule_statuses

Crate sbol

Crate sbol Copy item path

§Mental model

§Document lifecycle

§Error model

§Where to go next

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate sbol