JSON Schema Matcher #

A Dart library for JSON schema validation using native testing framework matchers.

Description #

JSON Schema Matcher provides a clean and intuitive API for validating complex JSON structures in your Dart tests. Using strongly-typed validators, you can ensure your JSON data follows the expected schema, with detailed error messages and support for optional fields.

Features #

• ✅ Type Validation: Support for primitive and nullable types (String?, int?, etc.)
• ✅ JSON Objects: Validation of objects with required and optional fields
• ✅ Arrays: Support for arrays of objects and primitive types
• ✅ Strict Validation: Optional validation of unexpected fields
• ✅ Detailed Messages: Specific errors with field paths
• ✅ Test Integration: Works natively with Dart's test framework

Installation #

Add to your pubspec.yaml:

dev_dependencies:
  json_schema_matcher: ^1.0.0

Basic Usage #

Validating JSON Objects #

import 'package:json_schema_matcher/json_schema_matcher.dart';
import 'package:test/test.dart';

void main() {
  test('user validation', () {
    final userData = {
      'id': 1,
      'name': 'John Silva',
      'email': 'john@email.com',
      'age': 30,
    };

    expect(
      userData,
      isJsonObject({
        'id': typeOf<int>(),
        'name': typeOf<String>(),
        'email': typeOf<String>(),
        'age': typeOf<int?>(), // optional field
      }),
    );
  });
}

Validating Arrays #

test('posts validation', () {
  final posts = [
    {
      'id': 1,
      'title': 'First Post',
      'content': 'Post content...',
    },
    {
      'id': 2,
      'title': 'Second Post',
      'content': null, // optional content
    },
  ];

  expect(
    posts,
    isJsonArray({
      'id': typeOf<int>(),
      'title': typeOf<String>(),
      'content': typeOf<String?>(), // allows null
    }),
  );
});

Arrays of Primitive Types #

test('tags validation', () {
  final tags = ['dart', 'json', 'validation'];

  expect(tags, isJsonArrayOf<String>());
});

test('numbers with nulls', () {
  final numbers = [1, 2, null, 4];

  expect(numbers, isJsonArrayOf<int?>()); // allows null
});

API Reference #

Main Validators #

• typeOf<T>() - Validates if the value is of type T
• jsonObject(Map<String, Validator>) - Validates JSON objects
• jsonArray(Map<String, Validator>) - Validates arrays of objects
• jsonArrayOf<T>() - Validates arrays of primitive types

Test Matchers #

• isJsonObject(Map<String, Validator>, {bool strictFields = false}) - Matcher for objects
• isJsonArray(Map<String, Validator>, {bool strictFields = false}) - Matcher for arrays of objects
• isJsonArrayOf<T>() - Matcher for primitive arrays

Optional Fields #

Use nullable types (String?, int?) for optional fields:

// Required field
'name': typeOf<String>(),

// Optional field (can be null or absent)
'nickname': typeOf<String?>(),

Strict Field Validation #

By default, the library ignores extra fields in JSON objects. Use strictFields: true to reject objects with unexpected fields:

test('strict validation', () {
  final schema = {
    'name': typeOf<String>(),
    'age': typeOf<int>(),
  };

  final dataWithExtraField = {
    'name': 'John',
    'age': 30,
    'extraField': 'not allowed',
  };

  // By default, extra fields are ignored
  expect(dataWithExtraField, isJsonObject(schema)); // ✅ passes

  // With strict validation, extra fields cause failure
  expect(
    () => expect(dataWithExtraField, isJsonObject(schema, strictFields: true)),
    throwsA(isA<TestFailure>()), // ❌ fails with "Field [extraField] is not expected"
  );
});

This also works for arrays:

test('strict array validation', () {
  final users = [
    {'id': 1, 'name': 'Alice'},
    {'id': 2, 'name': 'Bob', 'extraField': 'not allowed'},
  ];

  final schema = {'id': typeOf<int>(), 'name': typeOf<String>()};

  // Fails because the second object has an extra field
  expect(
    () => expect(users, isJsonArray(schema, strictFields: true)),
    throwsA(isA<TestFailure>()),
  );
});

Error Messages #

The library provides clear messages when validation fails:

Expected: matches JSON schema
  Actual: {id: abc, name: John}
   Which: does not match JSON schema
- Field [id] has invalid type (expected int, received String)
- Field [email] is required

Complete Example #

See the example/json_schema_matcher_example.dart file for a complete usage example of the library.

License #

MIT License

Contributing #

Contributions are welcome! Please open an issue or pull request in the project repository.