Skip to main content

ifc_validate/
lib.rs

1//! `ifc-validate` -- Schema and model validation: is this file actually legal IFC?
2//!
3//! Split from parsing on purpose. A reader that rejects everything imperfect is
4//! useless on real data -- roughly half of production files violate something --
5//! so parsing is permissive and validation is an explicit, separate pass.
6//!
7//! # What a report means
8//!
9//! ```no_run
10//! # use ifc_model::Model;
11//! # fn demo(model: &Model) {
12//! let report = ifc_validate::validate(model, ifc_schema::ifc4());
13//! if report.is_conformant() {
14//!     // No *errors*. There may still be warnings, and there are certainly
15//!     // rules this validator does not evaluate -- `report.summary()`
16//!     // says how many.
17//! }
18//! # }
19//! ```
20//!
21//! The four severities are not a mood scale. [`Severity::Error`] means the
22//! file breaks a schema requirement; [`Severity::EvaluationError`] means an
23//! implemented rule applied to an instance but could not be decided for it;
24//! [`Severity::Warning`] means it is legal but will behave badly;
25//! [`Severity::Unsupported`] is a statement about *this validator*, not about
26//! the file. Errors and evaluation errors affect [`Report::is_conformant`]:
27//! a rule nobody could decide is not a rule that passed.
28//!
29//! # What this crate deliberately does not do
30//!
31//! It does not bundle the schemas' rule text: the IFC schemas are CC BY-ND
32//! 4.0, and the bundled tables keep only rule labels. [`validate`] runs a
33//! hand-written subset of the WHERE rules ([`where_rule::RULES`]) and
34//! reports the rest it knows of as unsupported. Given the release's own
35//! `.exp` text, the [`express`] evaluator (feature `express`, on by
36//! default) evaluates every WHERE rule, type rule and global rule of the
37//! release through [`validate_with_options`], so a clean report never
38//! silently means "unchecked".
39//!
40//! It checks the aggregate bounds, nesting and element uniqueness of
41//! explicit attributes, and every `UNIQUE` clause of the declared release
42//! ([`structure`]). A bound written as an expression, and the bounds of an
43//! aggregate reached through a defined type, are not evaluated.
44//!
45//! The hand-written rules do not derive `INVERSE` relationships, so one
46//! whose IFC2X3 form depends on an inverse is reported unsupported; the
47//! [`express`] evaluator resolves INVERSE attributes through the reverse
48//! index.
49//!
50//! # Module map
51//!
52//! | Module | Role |
53//! |---|---|
54//! | [`header`] | Declared schema and implementation level |
55//! | [`structure`] | References, required slots, cardinality, bounds, UNIQUE clauses |
56//! | [`type_check`] | Values against their declared EXPRESS types |
57//! | [`where_rule`] | Native rules, and honest reporting of the rest |
58//! | [`express`] | Every EXPRESS rule, evaluated from the release's text |
59//! | [`property_set`] | `Pset_`/`Qto_` names, and the members of catalog sets |
60//! | [`options`] | What a run is given: budget, rules, catalog |
61//! | [`report`] | Findings, paths, severities, summaries |
62//! | [`error`] | Why validation could not run |
63
64pub mod error;
65#[cfg(feature = "express")]
66pub mod express;
67pub mod header;
68pub mod options;
69pub mod property_set;
70pub mod report;
71pub mod structure;
72pub mod type_check;
73pub mod where_rule;
74
75pub use error::ValidateError;
76pub use options::{validate_with_options, ValidateOptions};
77pub use property_set::{
78    CatalogMember, CatalogMemberForm, CatalogQuantityKind, CatalogSet, CatalogSetKind,
79    PropertySetCatalog,
80};
81pub use report::{
82    BudgetExceeded, CatalogMemberDetail, CatalogMismatch, Finding, FindingDetail, NotEvaluated,
83    Path, Report, ReservedSetName, RuleDetail, RuleOutcome, RuleScope, Severity, Summary,
84};
85pub use where_rule::Budget;
86
87use ifc_model::Model;
88use ifc_schema::Schema;
89
90/// Validate a model against a schema with the default budget.
91///
92/// Runs every check this crate implements: header, structure, types, and the
93/// natively implemented rules. Unsupported rules are recorded rather than
94/// skipped.
95#[must_use]
96pub fn validate(model: &Model, schema: &Schema) -> Report {
97    validate_with(model, schema, Budget::DEFAULT)
98}
99
100/// Validate under an explicit budget.
101///
102/// A budget bounds how many findings are recorded. Hitting it marks the
103/// report truncated: `12 errors` from a truncated report means "at least 12".
104#[must_use]
105pub fn validate_with(model: &Model, schema: &Schema, budget: Budget) -> Report {
106    validate_with_options(model, schema, &ValidateOptions::new().budget(budget))
107}
108
109/// Validate against the schema the file itself declares.
110///
111/// # Errors
112///
113/// Returns [`ValidateError`] when the file declares no schema, or declares
114/// one this build has no tables for. A release known by name but published
115/// without an EXPRESS schema (`IFC4X3_TC1`, `IFC4X3_ADD1`) is
116/// [`ValidateError::UnpublishedSchema`], never validated as IFC4X3 ADD2 by
117/// assumption; a caller choosing to do so passes those tables to
118/// [`validate`]. Validating an IFC2X3 file against IFC4
119/// tables would produce confident nonsense, so it is refused rather than
120/// approximated. Which releases have tables is the build's choice: the
121/// release features (`ifc2x3`, `ifc4`, `ifc4x1`, `ifc4x2`, `ifc4x3`, all on
122/// by default) each bundle one.
123pub fn validate_declared(model: &Model) -> Result<Report, ValidateError> {
124    use ifc_schema::SchemaVersion;
125
126    let token = model
127        .header()
128        .schema_token()
129        .ok_or(ValidateError::NoSchemaDeclared)?;
130    let version = SchemaVersion::from_header_token(token).ok_or_else(|| {
131        if ifc_schema::UnpublishedRelease::from_header_token(token).is_some() {
132            ValidateError::UnpublishedSchema(token.to_string())
133        } else {
134            ValidateError::UnknownSchema(token.to_string())
135        }
136    })?;
137    // `for_version` refuses a recognised schema this build does not bundle
138    // with `NotBundled`. Both cases are refusals, but they are different
139    // facts: one is "no idea what that token is", the other is "known schema,
140    // no tables".
141    let schema = ifc_schema::for_version(version)
142        .map_err(|_| ValidateError::UnbundledSchema(token.to_string()))?;
143    Ok(validate(model, schema))
144}