Rust API
The canonical crate is openbim-idm; its Rust import name is openbim_idm.
Primary types
Document: bounded parse, serialize, lossless JSON conversion, path access, catalog-aware edits, and validation.Element,Attribute, andNode: complete XML tree primitives.SchemaCatalogand declaration types: generated content-model metadata.ValidationIssueandValidationSeverity: structured diagnostics.EditandEditBatch: versioned, serializable, reversible edit operations.NodeInfo,AttributeInfo,AttributeSlot: per-element read models for UIs.ParsedBytesandEncoding: encoding-aware reading and writing.Error: parse, size, depth, path, schema, JSON, cardinality, content-model, I/O, and encoding failures.Error::code()returns a stable machine-readable code andErrorisClone + PartialEq + Serialize.
Core operations
use openbim_idm::Document;
let mut document = Document::new_idm("Coordination", "IDM-001")?;
let actions = document.allowed_children("/idm/uc[0]")?;
let sub_uc = document.append_schema_child("/idm/uc[0]", "subUc")?;
document.set_text(&format!("{sub_uc}/uc[0]/description[0]"), "Nested use case")?;
let diagnostics = document.validate();
let xml = document.to_xml(true)?;
# Ok::<(), openbim_idm::Error>(())Paths use indexed local names such as /idm/uc[0]/subUc[1]. Every path-taking method also accepts a guid:<value> or id:<value> locator; use Document::path_of to resolve one.
Reading and I/O
Document::from_path,from_reader,parse_bytesdetect UTF-8/16 (BOM or declaration), ISO-8859-1 and windows-1252, enforce the size limit before and during reading, and reportParsedBytes::warningsabout information that serialization changes.write_pathwrites atomically (temporary file in the same directory, then rename), so a failed write leaves the original file intact.write_to,to_bytesandto_bytes_with_encodingcover streams and other encodings; unrepresentable characters are anError::Encoding.Document::from_json_str,Edit::from_json_strandEditBatch::from_json_strread JSON text at any nesting the depth limit allows (plainserde_json::from_strstops at about 40 element levels).DEFAULT_MAX_XML_DEPTH(256) bounds XML, JSON and edits alike, so no operation can exhaust a 512 KiB stack in release builds.to_xmlnever emits XML that cannot be read back: forbidden characters,]]>in CDATA,--in comments and invalid names are anError::Write, and the setters reject such characters asError::Content. Text set through the API is stored the way the reader represents it (references as separate nodes), so an edited document equals its reloaded form.node_info,attributes,attribute_slotsandschema_rulegive a property panel everything for one element.schema_rulereturnsError::Schemafor undeclared (extension) content.
Editing
set_textrejects element-only elements withError::Content(set_text_uncheckedbypasses);remove_attributerejects declared required attributes;add_schema_attributeadds a declared attribute with its default.insert_schema_child,duplicate_schema_node,paste_schema_nodeandreparent_schema_nodeare cardinality- and order-checked; copies get freshguid/idvalues (andchangedByreferences inside the copy are remapped).apply(&Edit)returns the inverse edit,apply_batch(&EditBatch)is atomic and returns the inverse batch, anddiff(&other)derives a best-effort batch. The JSON form is tagged byopand the batch carriesversion(currently1).
Validation
Document::validate checks required attributes, XSD built-in lexical types (xs:boolean, xs:integer, xs:dateTime, xs:NCName, xs:normalizedString), the declared GUID pattern, enumerations, cardinality, order, element-only content, duplicate guid/id values, and changeLog/@changedBy references. Undeclared elements and attributes are warnings (extension_element, extension_attribute), not errors, because they are preserved. ValidationIssue::attribute and ::expected locate the offending field. This is catalog-driven validation, not formal XSD validation.
verify_schema_dir(dir) hashes the six recognized files in an explicit directory and reports match, mismatch or missing against the catalog, so you can tell whether the catalog validator applies to your schema set.
Validation issue codes
| Code | Severity | Meaning |
|---|---|---|
invalid_root | error | root is not the unqualified idm element |
schema_catalog / schema_definition | error | the embedded catalog or a declaration could not be loaded |
required_attribute | error | a required attribute is missing |
attribute_pattern | error | the guid value does not match the declared pattern |
attribute_datatype / element_datatype | error | value is not valid for its xs: built-in type (expected.type) |
attribute_enumeration / element_enumeration | error | value is not in the declared enumeration (expected.enum) |
minimum_cardinality / maximum_cardinality / choice_cardinality | error | child counts outside the declared bounds (expected.min/max) |
schema_order | error | element is not in declaration order |
unexpected_text | error | character data in element-only content |
duplicate_guid / duplicate_id | error | guid / id values are not unique |
dangling_reference | warning | changeLog/@changedBy matches no author/@id (expected.oneOf) |
extension_element / extension_attribute | warning | undeclared content, preserved as an extension |
overlay codes such as idm.er.required_by_standard | error | documented standard-over-XSD semantic overlays |
Error codes
Error::code() returns one of input_too_large, max_depth_exceeded, invalid_xml, write_failed, invalid_utf8, invalid_path, path_not_found, schema, invalid_json, cardinality, content_model, io, encoding. The CLI (--json-errors), Python (IdmError.code) and JS (Error.code, Errors.codes()) expose the same strings.
WebAssembly
--features wasm on wasm32-unknown-unknown exports a Document class that mirrors the Python facade (camelCase, JSON strings for structured values, errors thrown as Error objects with a code). The only top-level exports are Document, LoadResult and the namespace classes Schema (Schema.catalogJson()), Engine (Engine.version()) and Errors (Errors.codes()); there are no flat helper functions. Generate glue with wasm-bindgen; see scripts/wasm-smoke.sh. Nothing is published to npm.
External schema access
schema_text(schema_dir, name) and local_schema_inventory(schema_dir) only read recognized filenames from the explicit directory. They never download or use embedded fallback data. schema_catalog() reads the non-normative generated metadata embedded in the crate.
For exact signatures and trait implementations, build the crate documentation:
cargo doc -p openbim-idm --all-features --no-deps