Add nullable types and modern C# conventions; refactor code and improve error handling

- Introduced `XPathHelpers` for safer navigation and XML handling.
- Updated `Validator`, `SchemaLoader`, and other classes to use new helper methods.
- Refactored exception handling to remove unnecessary constructors.
- Enhanced `Config` and `PhaseCollection` for better type safety.
- Updated project metadata and README for clarity and accuracy.
- Added new icon and markdown documentation.

Author: kzu

assets/img/icon.png

@@ -1,3 +1,160 @@
 # Schematron.NET
 
-This is a [Schematron ISO/IEC 2025](http://www.schematron.com/) standard processor for .NET, written in C#.
+[![Version](https://img.shields.io/nuget/vpre/Schematron.svg?color=royalblue)](https://www.nuget.org/packages/Schematron)
+[![Downloads](https://img.shields.io/nuget/dt/Schematron.svg?color=darkmagenta)](https://www.nuget.org/packages/Schematron)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/devlooped/Schematron/blob/main/license.txt)
+[![GitHub](https://img.shields.io/badge/-source-181717.svg?logo=GitHub)](https://github.com/devlooped/Schematron)
+
+<!-- #description -->
+A .NET implementation of Schematron for validating XML with standalone `.sch` schemas or
+Schematron rules embedded in W3C XML Schema. The library supports both the current ISO
+Schematron namespace and the legacy ASCC namespace, with a compact public API centered on
+`Validator` and `Schema`.
+<!-- #description -->
+
+<!-- include https://github.com/devlooped/.github/raw/main/osmf.md -->
+
+<!-- #content -->
+## Installation
+
+```shell
+dotnet add package Schematron
+```
+
+The package targets `netstandard2.0` and `net8.0`.
+
+## Usage
+
+The package exposes two primary entry points:
+
+- `Validator` loads Schematron and XML Schema definitions and validates XML documents.
+- `Schema` loads and inspects Schematron documents programmatically.
+
+### One-shot validation with a standalone Schematron schema
+
+```csharp
+using Schematron;
+
+var validator = new Validator();
+validator.AddSchema("order.sch");
+
+try
+{
+    validator.Validate("order.xml");
+    Console.WriteLine("Document is valid.");
+}
+catch (ValidationException ex)
+{
+    Console.WriteLine(ex.Message);
+}
+```
+
+`Validate` returns the loaded `IXPathNavigable` document on success and throws
+`ValidationException` when XML Schema or Schematron validation fails.
+
+### Validating XSD plus embedded Schematron
+
+When the schema is a W3C XML Schema document with embedded Schematron, `Validator` runs
+both validations in one pass:
+
+```csharp
+using Schematron;
+
+var validator = new Validator(OutputFormatting.XML);
+
+// Use the overload with the target namespace when the XSD imports or includes other schemas.
+validator.AddSchema("http://example.com/po-schematron", "po-schema.xsd");
+
+try
+{
+    validator.Validate("purchase-order.xml");
+}
+catch (ValidationException ex)
+{
+    Console.WriteLine(ex.Message); // XML formatted output
+}
+```
+
+### Schematron-only validation for in-memory XML
+
+If you already have an `IXPathNavigable`, use `ValidateSchematron` to skip XML Schema
+validation and evaluate only the loaded Schematron rules:
+
+```csharp
+using System.Xml.XPath;
+using Schematron;
+
+var validator = new Validator();
+validator.AddSchema("rules.sch");
+
+var document = new XPathDocument("order.xml");
+validator.ValidateSchematron(document);
+```
+
+### Selecting the phase, formatter, and return type
+
+`Validator` lets you control the active phase, output format, and result type:
+
+```csharp
+using Schematron;
+using Schematron.Formatters;
+
+var validator = new Validator(OutputFormatting.XML, NavigableType.XmlDocument)
+{
+    Phase = "paymentInfo",
+    Formatter = new XmlFormatter(),
+};
+
+validator.AddSchema("purchase-order.sch");
+var result = validator.Validate("purchase-order.xml");
+```
+
+Use `Phase.All` (`#ALL`) to evaluate every pattern regardless of phase activation.
+
+### Loading and inspecting a schema
+
+Use `Schema` directly when you want to inspect a Schematron document without validating
+an instance document yet:
+
+```csharp
+using Schematron;
+
+var schema = new Schema();
+schema.Load("rules.sch");
+
+Console.WriteLine(schema.Title);
+Console.WriteLine(schema.SchematronEdition);
+Console.WriteLine(schema.DefaultPhase);
+Console.WriteLine(schema.IsLibrary);
+Console.WriteLine(schema.Patterns.Count);
+Console.WriteLine(schema.Lets.Contains("maxAge"));
+```
+
+This is useful for tooling, analyzers, test helpers, or apps that need to inspect declared
+phases, patterns, diagnostics, parameters, and `let` bindings.
+
+## Core API
+
+Schematron keeps the public surface intentionally small:
+
+- `Validator` is the main entry point for loading schemas and validating XML.
+- `Schema` loads and inspects Schematron documents programmatically.
+- `OutputFormatting` selects the built-in output style: `Default`/`Log`, `Simple`,
+  `Boolean`, or `XML`.
+- `Validator.Phase`, `Validator.Formatter`, and `Validator.ReturnType` let you choose
+  the active phase, custom output formatter, and returned document type.
+- `BadSchemaException` signals invalid schema input, while `ValidationException`
+  signals XML or Schematron validation failures.
+
+## Supported features
+
+The package currently supports the main scenarios expected for a v1 release, including:
+
+- Standalone `.sch` schemas and Schematron embedded in W3C XML Schema
+- ISO Schematron namespace (`http://purl.oclc.org/dsdl/schematron`) and legacy ASCC namespace compatibility
+- ISO Schematron 2025 features such as `<library>`, phase `@when`, rule `@visit-each`, rule flags, and schema parameters
+- Schema-, pattern-, and rule-level `let` bindings
+- Diagnostics, severity metadata, abstract patterns/rules, and groups
+<!-- #content -->
+
+<!-- include https://github.com/devlooped/sponsors/raw/main/footer.md -->

readme.md

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <Product>Schematron.NET</Product>
     <Description>A C# high-performance implementation of Schematron ISO/IEC standard</Description>
-    <PackageProjectUrl>https://github.com/kzu/Schematron</PackageProjectUrl>
+    <PackageProjectUrl>https://github.com/devlooped/Schematron</PackageProjectUrl>
     <ImplicitUsings>true</ImplicitUsings>
   </PropertyGroup>
 

src/Directory.props

@@ -21,13 +21,6 @@ public BadSchemaException() { }
     /// <param name="message">The error message that explains the reason for the exception.</param>
     public BadSchemaException(string message) : base(message) { }
 
-    /// <summary>
-    /// Initializes a new instance of the <see cref="BadSchemaException"/> class.
-    /// </summary>
-    /// <param name="info">Info</param>
-    /// <param name="context">Context</param>
-    protected BadSchemaException(SerializationInfo info, StreamingContext context) : base(info, context) { }
-
     /// <summary>
     /// Initializes a new instance of the <see cref="BadSchemaException"/> class.
     /// </summary>

src/Schematron/BadSchemaException.cs

@@ -35,7 +35,7 @@ static Config()
         full.Phases.Add(full.CreatePhase(Phase.All));
 
         //TODO: should we move all the schema language elements to a resource file?
-        navigator = new XmlDocument().CreateNavigator();
+        navigator = new XmlDocument().CreateRequiredNavigator();
         navigator.NameTable.Add("active");
         navigator.NameTable.Add("pattern");
         navigator.NameTable.Add("assert");
@@ -146,4 +146,4 @@ public static void Setup()
         System.Diagnostics.Trace.Write(TagExpressions.Dir().RightToLeft);
         System.Diagnostics.Trace.WriteLine(FormattingUtils.XmlErrorPosition.RightToLeft);
     }
-}
+}

src/Schematron/Config.cs

@@ -2,6 +2,7 @@
 using System.Xml;
 using System.Xml.Schema;
 using System.Xml.XPath;
+using Schematron;
 
 namespace Schematron.Formatters;
 /// <summary>
@@ -115,7 +116,7 @@ protected static StringBuilder FormatMessage(Test source, XPathNavigator context
                     // name of the first node, which is compatible with XSLT implementation.
                     var nodes = (XPathNodeIterator)context.Evaluate(nameExpr);
                     if (nodes.MoveNext())
-                        result = nodes.Current.Name;
+                        result = nodes.CurrentOrThrow().Name;
                 }
                 else
                 {
@@ -136,7 +137,7 @@ protected static StringBuilder FormatMessage(Test source, XPathNavigator context
                     var nodes = (XPathNodeIterator)context.Evaluate(selectExpr);
                     result = string.Empty;
                     while (nodes.MoveNext())
-                        result += nodes.Current.Value;
+                        result += nodes.CurrentOrThrow().Value;
                 }
                 else
                 {

src/Schematron/Formatters/FormatterBase.cs

@@ -53,7 +53,12 @@ public static string GetFullNodePosition(XPathNavigator context, string previous
         {
             if (context.Prefix == string.Empty)
             {
-                pref = source.GetContext()!.LookupPrefix(source.GetContext()!.NameTable.Get(context.NamespaceURI));
+                var sourceContext = source.GetContext();
+                var nameTable = sourceContext?.NameTable;
+                var namespaceName = nameTable?.Get(context.NamespaceURI);
+                pref = sourceContext is null || namespaceName is null
+                    ? string.Empty
+                    : sourceContext.LookupPrefix(namespaceName) ?? string.Empty;
             }
             else
             {
@@ -62,9 +67,9 @@ public static string GetFullNodePosition(XPathNavigator context, string previous
 
             if (!namespaces.ContainsKey(context.NamespaceURI))
             {
-                namespaces.Add(context.NamespaceURI, pref ?? "");
+                namespaces.Add(context.NamespaceURI, pref);
             }
-            else if (((string)namespaces[context.NamespaceURI]) != pref &&
+            else if ((namespaces[context.NamespaceURI] as string ?? string.Empty) != pref &&
                 !namespaces.ContainsKey(context.NamespaceURI + ":" + pref))
             {
                 namespaces.Add(context.NamespaceURI + " " + pref, pref);
@@ -132,7 +137,7 @@ public static string GetNodeSummary(XPathNavigator context, Hashtable namespaces
         // Get the element name
         XmlQualifiedName name;
         if (ctx.NamespaceURI != string.Empty)
-            name = new XmlQualifiedName(ctx.LocalName, namespaces[ctx.NamespaceURI].ToString());
+            name = new XmlQualifiedName(ctx.LocalName, namespaces[ctx.NamespaceURI] as string ?? string.Empty);
         else
             name = new XmlQualifiedName(ctx.LocalName);
 
@@ -165,15 +170,15 @@ public static string GetNamespaceSummary(XPathNavigator context, Hashtable names
         foreach (var key in keys)
         {
             sb.Append(spacing).Append("xmlns");
-            pref = namespaces[key].ToString();
+            pref = namespaces[key] as string ?? string.Empty;
 
             if (pref != string.Empty)
                 sb.Append(":").Append(namespaces[key]);
 
             sb.Append("=\"");
 
             if (pref != string.Empty)
-                sb.Append(removeprefix.Replace(key.ToString(), string.Empty));
+                sb.Append(removeprefix.Replace(key?.ToString() ?? string.Empty, string.Empty));
             else
                 sb.Append(key);
 

src/Schematron/Formatters/FormattingUtils.cs

@@ -3,6 +3,7 @@
 using System.Xml;
 using System.Xml.Schema;
 using System.Xml.XPath;
+using Schematron;
 
 namespace Schematron.Formatters;
 
@@ -118,8 +119,14 @@ public override void Format(Schema source, XPathNavigator context, StringBuilder
         foreach (string prefix in source.NsManager)
         {
             if (!prefix.StartsWith("xml"))
-                writer.WriteAttributeString("xmlns", prefix, null,
-                    source.NsManager.LookupNamespace(source.NsManager.NameTable.Get(prefix)));
+            {
+                var nameTable = source.NsManager.NameTable
+                    ?? throw new InvalidOperationException("The namespace manager does not have an associated name table.");
+                var namespacePrefix = nameTable.Get(prefix) ?? prefix;
+                var namespaceUri = source.NsManager.LookupNamespace(namespacePrefix);
+                if (namespaceUri is not null)
+                    writer.WriteAttributeString("xmlns", prefix, null, namespaceUri);
+            }
         }
 
         if (source.Title != string.Empty) writer.WriteAttributeString("title", source.Title);

src/Schematron/Formatters/XmlFormatter.cs

@@ -18,13 +18,6 @@ public InvalidExpressionException() : base() { }
     /// <param name="message">The error message that explains the reason for the exception.</param>
     public InvalidExpressionException(string message) : base(message) { }
 
-    /// <summary>
-    /// For serialization purposes.
-    /// </summary>
-    /// <param name="info">Info</param>
-    /// <param name="context">Context</param>
-    protected InvalidExpressionException(SerializationInfo info, StreamingContext context) : base(info, context) { }
-
     /// <summary>
     /// Initializes an instance of the class with a specified error message
     /// and a reference to the inner exception that is the cause for this exception.

src/Schematron/InvalidExpressionException.cs

@@ -1,4 +1,5 @@
 using System.Collections;
+using System.Collections.Generic;
 
 namespace Schematron;
 
@@ -14,7 +15,8 @@ public PhaseCollection()
     /// <summary>Required indexer.</summary>
     public Phase this[string key]
     {
-        get { return (Phase)Dictionary[key]; }
+        get => Dictionary[key] as Phase
+            ?? throw new KeyNotFoundException($"The phase '{key}' was not found.");
         set { Dictionary[key] = value; }
     }