Skip to content

Example: API reference type page

An API reference page documents one public type. Doc gen produces one per public type under docs/libraries/<slug>/api/<namespace>/<Type>.md, and every page must be listed in the Types table of api/index.md.

What reviewers should check

  • The opening paragraph states what the type actually does, who calls it, and any side effects. Declaration restatements ("ValidationEngine is a public class") and name echoes are defects, not summaries.
  • Every public member is documented on this page with a complete signature. Truncated or line-continuation-mangled VB signatures are the most common defect in these libraries.
  • The page is self-contained. "See RuleSetLoader for details" or "identical to the base class" in place of a real Purpose cell is wrong, including for inherited members.
  • Purpose cells describe effect or meaning, never accessor shape. "Gets or sets Name", "Returns a string", and "Constructor" are all rejected.
  • Inherited members carry † and an Origin naming both the base class and its library, and the note box explaining *, **, and † sits immediately before ## Sources.
  • Behavioral notes marked * are genuinely inferred; anything stated flatly should be verifiable in the files under ## Sources.

Example

The document below is a complete, correct api/<Type>.md for a fictional library.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

---
title: ValidationEngine
summary: API reference for ValidationEngine.
status: draft
owner: Policy Systems Team
last_reviewed: 2026-02-18
library: SAIF.Framework.Validation
reference_type: package
---

# ValidationEngine

`ValidationEngine` is the single entry point consuming applications use to run
a rule set against a policy or claims record. It resolves the named rule set
through `RuleSetLoader`, evaluates every rule in declaration order without
short-circuiting, and aggregates the outcomes into one `ValidationResult` so
callers can present all failures at once. It never throws for a business
validation failure — failures are data, not exceptions — and it mutates no
caller state. Instances hold the resolved rule set and an accumulating result
buffer, so they are not safe to share across threads or requests.

## Purpose
- Runs every rule in a named rule set against a supplied record and returns the
  complete set of failures and warnings in one pass, so operators in
  `SAIF.Claims.Intake` correct all problems in a single round trip.
- Enforces the severity split between blocking failures and acceptable
  warnings described in BR-004.
- Provides the jurisdiction-aware evaluation path required by BR-002 by
  threading the caller's `IValidationContext` into every rule evaluation.

## Context
- Namespace: `SAIF.Framework.Validation`
- Assembly/package: `SAIF.Framework.Validation` (NuGet package
  `SAIF.Framework.Validation`, assembly `SAIF.Framework.Validation.dll`)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| ValidationEngine | `Public Sub New(ByVal ruleSetName As String, ByVal context As IValidationContext)` | Binds the engine to a named rule set and the caller's context; throws `ArgumentNullException` when either argument is missing. |
| RuleSetName | `Public ReadOnly Property RuleSetName As String` | Name of the rule set this engine evaluates, used in log entries and batch error output to identify which rules ran. |
| Context | `Public ReadOnly Property Context As IValidationContext` | Jurisdiction, effective date, and user identity supplied by the host application and passed to each rule. |
| Validate | `Public Function Validate(ByVal record As Object) As ValidationResult` | Evaluates every rule in the rule set against the record and returns the aggregated failures and warnings. |
| ValidateField | `Public Function ValidateField(ByVal record As Object, ByVal fieldName As String) As ValidationResult` | Evaluates only the rules targeting the named field, used for per-field feedback as an operator tabs through a claim entry screen. |
| Reload | `Public Sub Reload()` | Discards the cached rule set and forces the next evaluation to re-read the rule set XML from disk. |

## Inherited public members

Members in this section are inherited from `ValidationComponentBase` in
`SAIF.Framework.Core`. They are available on this type through inheritance.

| Member | Signature | Purpose | Origin |
| --- | --- | --- | --- |
| ComponentName | `Public Overridable ReadOnly Property ComponentName As String` | Stable identifier written to the framework trace log so a failing evaluation can be traced to the component that produced it.† | `SAIF.Framework.Core` — `ValidationComponentBase` |
| WriteTrace | `Protected Sub WriteTrace(ByVal message As String)` | Emits a trace entry tagged with the component name when framework tracing is enabled; does nothing when tracing is off.† | `SAIF.Framework.Core` — `ValidationComponentBase` |
| IsInitialized | `Public ReadOnly Property IsInitialized As Boolean` | Reports whether framework initialization completed, allowing callers to detect use before startup configuration ran.† | `SAIF.Framework.Core` — `ValidationComponentBase` |

## Behavioral notes
- `Validate` evaluates all rules even after a failure, so a returned
  `ValidationResult` contains every failure the record produced rather than
  only the first.
- Rule set resolution happens on the first call to `Validate` or
  `ValidateField`, not in the constructor, so a missing rule set file surfaces
  as a `RuleSetNotFoundException` at evaluation time.
- `ValidateField` returns an empty passing result when no rule targets the
  named field; it does not signal an error for an unknown field name.
- `Reload` clears the shared `RuleSetLoader` cache, which affects every engine
  instance in the process, not just this one.*
- Evaluation order follows the order rules appear in the rule set XML, which
  lets later rules assume earlier format checks already ran.*

## Constraints and usage notes
- Create one instance per request or per batch record. The accumulating result
  buffer makes concurrent use of a single instance unsafe.
- Do not pass data-reader or connection-bound objects as `record`. Rules expect
  a fully materialized object with readable properties.
- The `IValidationContext` implementation must return a non-null jurisdiction
  code; jurisdiction-scoped rules treat a missing code as a failure of BR-002.
- Rule set XML changes require `Reload` or an application recycle before they
  take effect.

> **Note:** Statements marked with * were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not
> available in source artifacts. Statements marked with ** could not be
> confirmed; treat as unknown until verified. Statements marked with † were
> retrieved from dependency library documentation via the Legends CLI RAG
> service. They describe inherited behavior from the indicated origin library
> and should be verified if the dependency version changes.

## Sources
- src/SAIF.Framework.Validation/ValidationEngine.vb
- src/SAIF.Framework.Validation/RuleSetLoader.vb
- src/SAIF.Framework.Validation/IValidationContext.vb
- src/SAIF.Framework.Validation/SAIF.Framework.Validation.vbproj