json_sentinel 0.4.0

Lightweight runtime JSON validation for Dart. Configurable logger, redaction, and batch validation — routes failures to any error reporter. No code generation.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.4.0 - 2026-06-03

Added

• CONTRIBUTING.md — contribution guide covering prerequisites, local CI commands, code standards, and CHANGELOG update instructions.
• SECURITY.md — security policy with supported versions and private vulnerability reporting process.
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• GitHub issue templates (bug_report.yml, feature_request.yml) using YAML issue forms.
• .github/pull_request_template.md — PR checklist aligned with CI requirements.
• API documentation deployed to GitHub Pages at https://igeetheron.github.io/json-sentinel/ on every push to main.
• Codecov coverage reporting with badge; coverage collected on every CI run.
• validateList() — validates a bare List<dynamic> returned directly from jsonDecode. Non-Map items at index N produce a JsonValidationResult.failure counted in failureIndices with a descriptive message, rather than throwing a cast error. Accepts the same optional parameters as validateBatch(), including warnUnexpected, validators, optional, strict, escalate, and generatePreviews. Compatible with tryFromJson-style guards via batch.isValid or batch.failureIndices.
• warnUnexpected parameter (bool, default false) on validate(), validateBatch(), and validateList(): logs unexpected keys as warnings without failing validation — result.isValid remains true. Intended for APIs that add fields in minor versions so teams are notified of contract drift without breaking the app. Mutually exclusive with strict (asserted in debug mode); warning log entries always use escalate: false.
• validators parameter (Map<String, bool Function(Object?)>?) on validate(), validateBatch(), and validateList(): per-key predicate functions for value-level checks run after type validation passes for each key. A predicate returning false adds a bullet error identifying the key. Predicates are skipped for absent optional keys and for keys that already failed type validation.

Changed

• pubspec.yaml: added documentation: URL and updated description to vendor-agnostic language.
• README: added Codecov and API docs badges; linked Contributing, Security, and Code of Conduct in Additional information.

0.3.0 - 2026-06-02

Added

• parentContext parameter (String?) on validate(): when provided, log output and extras['context'] use the full chained path '$parentContext > $context', making it possible to locate failing nested models by call site (e.g. [UserPage.data[2] > MetaModel]).
• redactKeys (Set<String>?) and redactionPlaceholder (String, default '[REDACTED]') parameters on configure() and silence(). Top-level JSON field values whose keys appear in redactKeys are replaced with the placeholder before any json_preview or item_previews snapshot is encoded and forwarded to Sentry/Crashlytics — the validated data itself is never modified.

Changed

• Added logging and observability topics to pubspec.yaml for better pub.dev discoverability.

0.2.0 - 2026-05-29

Added

• JsonSentinel.validateBatch() — validates a list of Map<String, dynamic> payloads against a shared schema and emits a single consolidated log entry covering all failures, preventing one Sentry/Crashlytics event per failure when validating API response lists. Accepts the same optional, strict, escalate, and context parameters as validate() (including the same 'UnknownModel' default for context). Accepts generatePreviews: false to skip per-item JSON serialisation for high-volume batches. Returns a BatchValidationResult.
• BatchValidationResult — result type for validateBatch(). Fields: isValid (true only when every item passed), results (one JsonValidationResult per input item in order), failureCount, and failureIndices (zero-based indices of failing items). All list fields are unmodifiable.
• validateBatch() logger extras include 'context', 'failure_count' (int), 'total_count' (int), and 'item_previews' — a List<String> of truncated JSON previews for each failing item in failureIndices order. item_previews is absent when generatePreviews: false is passed.

Changed

• JsonValidationResult.failure() now asserts in debug mode that the errors list is non-empty. A failure result with no errors is semantically contradictory. Callers passing failure([]) will receive an AssertionError in debug builds (including dart test); release builds are unaffected.
• verbose: true now emits a dart:developer trace on every failing validate() and validateBatch() call in addition to the existing passing-call traces. Failures are now visible in DevTools Logging even when a Sentry/Crashlytics logger is registered.

0.1.1 - 2026-05-28

Fixed

• Corrected repository and issue tracker URLs to point to IgeeTheron/json-sentinel.

0.1.0 - 2026-05-28

Added

• JsonSentinel.validate() — validates a Map<String, dynamic> against an expected key/type schema at runtime without code generation. Collects all errors before logging so callers always see the full picture in a single log entry.
• JsonValidationResult — structured result returned by validate(), with an isValid flag and an unmodifiable errors list for programmatic access.
• JsonLogFn typedef — function signature for the logging callback. Carries message, stackTrace, extras (including context label and json_preview), and escalate hint.
• JsonSentinel.configure() — registers a JsonLogFn for all validation failures. Asserts in debug mode if called more than once; first registration wins in release.
• JsonSentinel.silence() — no-op alternative to configure(); suppresses all log output for purely programmatic use via result.errors. Mutually exclusive with configure().
• JsonSentinel.logger getter — exposes the currently configured JsonLogFn?; null until configure() or silence() is called.
• JsonSentinel.resetLoggerForTesting() — resets the logger and verbose flag to their initial state; for use in test tearDown.
• context parameter on validate() — labels each log entry and the context extras key with the model name for searchable Sentry/Crashlytics context. Defaults to 'UnknownModel'.
• optional parameter on validate() — keys marked optional are skipped when absent but still type-checked when present.
• strict mode on validate() — flags unexpected keys not declared in the schema.
• escalate parameter on validate() — per-call hint to the logger for elevated capture (e.g. a Sentry event rather than a breadcrumb). Defaults to false.
• Nullable fields and union types via the expectedTypes type-list syntax: [String, null] for nullable, [int, double] for unions, null or [] for existence-only checks.
• verbose parameter on configure() and silence() — enables trace-level dart:developer logs in debug mode: a confirmation on initialisation, a success trace on every passing validate() call, and a diagnostic when JSON serialisation fails.
• Fallback logging via dart:developer when no logger is configured; suppressed in release builds — always call configure() or silence() in production code.
• Zero runtime dependencies — pure Dart, works in Flutter, server, and CLI projects.