Viewing version 5.1.0. Open the latest package page.

json_schema

5.1.0

JSON Schema implementation in Dart

Download archive

Readme

JSON Schema

A platform agnostic (web, flutter or vm) Dart library for validating JSON instances against JSON Schemas (multi-version support with latest of Draft 7).

Getting Started

  1. Ensure you have latest stable Dart installed.
  2. make pubget
  3. make format
  4. make analyze
  5. make test-with-serve-remotes

Alternative Test Running Strategy (To run specific tests, or pass other args to dart test):

  1. make serve-remotes (in a separate terminal tab - HTTP fixtures need to be served for tests to pass)
  2. make test or dart test -n <YOUR TEST>
  3. SIGINT your make serve-remotes tab or run make stop-serve-remotes

Note: For convenience, make stop-serve-remotes will be run as a prerequisite before make test-with-serve-remotes and make serve-remotes

Updating Test Fixtures

  1. make gen-fixtures Generates Dart source files that contain the JSON-Schema-Test-Suite tests and fixtures for use in cross-platform testing that doesn't require dart:io to read the files on disk.
  2. Commit the results of generation, if any.

Note: CI runs make gen-fixtures --check to ensure these are up-to-date on each

Simple Example Usage

The simplest way to create a schema is to pass JSON data directly to JsonSchema.create with a JSON String, or decoded JSON via Dart Map or bool.

After creating any schema, JSON instances can be validated by calling .validate(instance) on that schema. By default, instances are expected to be pre-parsed JSON as native dart primitives (Map, List, String, bool, num, int). You can also optionally parse at validation time by passing in a string and setting parseJson: schema.validate('{ "name": "any JSON object"}', parseJson: true).

Note: Creating JsonSchemas synchronously implies access to all $refs within the root schema. If you don't have access to all this data at the time of the construction, see "Asynchronous Creation" examples below.

import 'package:json_schema/json_schema.dart';

main() {
  /// Define schema in a Dart [Map] or use a JSON [String].
  final mustBeIntegerSchemaMap = {"type": "integer"};

  // Create some examples to validate against the schema.
  final n = 3;
  final decimals = 3.14;
  final str = 'hi';

  // Construct the schema from the schema map or JSON string.
  final schema = JsonSchema.create(mustBeIntegerSchemaMap);

  print('$n => ${schema.validate(n)}'); // true
  print('$decimals => ${schema.validate(decimals)}'); // false
  print('$str => ${schema.validate(str)}'); // false
}

Or see json_schema/example/readme/synchronous_creation/self_contained.dart

And run dart run ./example/readme/synchronous_creation/self_contained.dart

Advanced Usage

Synchronous Creation, Local Ref Cache

If you want to create JsonSchemas synchronously, and you have $refs that cannot be resolved within the root schema, but you have a cache of those $ref'd schemas locally, you can write a RefProvider to get them during schema evaluation.

See json_schema/example/readme/synchronous_creation/local_ref_cache.dart

Or run dart run ./example/readme/synchronous_creation/local_ref_cache.dart

Asynchronous Creation, Remote HTTP Refs

If you have schemas that have nested $refs that are HTTP URIs that are publicly accessible, you can use Future<JsonSchema> JsonSchema.createAsync and the references will be fetched as needed during evaluation. You can also use JsonSchema.createFromUrl if you want to fetch the root schema remotely as well (see next example).

See json_schema/example/readme/asynchronous_creation/remote_http_refs.dart

Or run dart run ./example/readme/asynchronous_creation/remote_http_refs.dart

Asynchronous Creation, From URL or File

You can also create a schema directly from a publicly accessible URL or File.

URLs

See json_schema/example/readme/asynchronous_creation/from_url.dart

Or run dart run ./example/readme/asynchronous_creation/from_url.dart

Files

See json_schema/example/readme/asynchronous_creation/from_file.dart

Or run dart run ./example/readme/asynchronous_creation/from_file.dart

Asynchronous Creation, with custom remote $refs:

If you have nested $refs that are either non-HTTP URIs or non-publicly-accessible HTTP $refs, you can supply an async RefProvider to createAsync, and perform any custom logic you need.

See json_schema/example/readme/asynchronous_creation/remote_ref_cache.dart

Or run dart run ./example/readme/asynchronous_creation/remote_ref_cache.dart

How To Use Schema Information

Schema information can be used for validation; but it can also be a valuable source of information about the structure of data. The JsonSchema class fully parses the schema first, which itself must be valid on all paths within the schema. Accessors are provided for all specified keywords of the JSON Schema specification associated with a schema, so tools can use it to create rich views of the data, like forms or diagrams.

Changelog

5.0.1

  • Add an JsonSchema.empty({SchemaVersion schemaVersion}) constructor

5.0.0

  • Clean up pubspec, add .pubignore
  • Bump minimum Dart SDK version to 2.12.0
  • Migration to null safety

4.0.3

4.0.2

  • Fix bug where type getter would throw when typeList was null

4.0.1

  • Performance:
    • cache calls to resolvePath
    • JsonSchema.schemaMap is now truly unmodifiable (was before in practice anyway) and hashCode is cached by taking advantage of that.
  • 4.0 Release Mistake:
    • Validator.evaluatedProperties was accidentally made public, pull it back to private.

4.0.0

json_schema 4.0 continues our journey to support additional new versions of the JSON Schema specification (Draft 2019-09 and Draft 2020-12)! Custom vocabulary and format support is also included in this release! In addition to those major features, we have better support for certain built-in formats, as well as improved spec test compliance.

We have greatly reduced the number of dependencies in preparation for a null-safety release (which we're planning in another major release). This has also come with a new Makefile instead our old dart_dev based commands (see README).

  • Additions:
    • Support for JSON Schema Draft 2019-09 (SchemaVersion.draft2019_09)
    • Support for JSON Schema Draft 2020-12 (SchemaVersion.draft2020_12)
    • Default draft is still draft7 for compatibility.
    • Custom Keywords:
      • List<CustomVocabulary> customVocabularies can be passed to all JsonSchema factories.
      • CustomVocabulary
      • CustomKeyword
      • ValidationContext
    • Custom Formats:
      • Map<String, Function> customFormats can be passed to and JsonSchema factory.
      • ValidationContext
  • Deprecated:
    • validateWithResults in favor of validate which now returns the same thing (ValidationResults).
    • DefaultValidators and related globals in favor of passing customFormats to the JsonSchema factories.
  • Removed Deprecations:
    • Removed bin/schemadot.dart, lib/schema_dot.dart and related examples
    • Removed lib/browser.dart and lib/vm.dart and associated globals createSchemaFromUrlBrowser, configureJsonSchemaForBrowser, globalCreateJsonSchemaFromUrl createSchemaFromUrlVm, configureJsonSchemaForVm and resetGlobalTransportPlatform. These were for configuring the runtime environment, which now happens automatically.
    • Removed JsonSchema.createSchemaAsync in favor of JsonSchema.createAsync
    • Removed JsonSchema.createSchema in favor of JsonSchema.create
    • Removed JsonSchema.createSchemaFromUrl in favor of JsonSchema.createFromUrl
    • Removed RefProvider.asyncSchema, RefProvider.syncSchema, RefProvider.asyncJson, and RefProvider.syncJson in favor of RefProvider.async and RefProvider.async, which are easier to use.
    • Removed JsonSchema.refMap
  • Breaking change to validate:
    • now returns ValidationResult instead of bool like validateWithResults (now deprecated).
  • Notable change of behavior to resolvePath with 2019-09 and 2020-12:
    • When used with draft 2019-09 or draft 2020-12, $refs alongside other keywords, which wasn't allowed in earlier drafts, can't always be resolved. We make a best-effort to resolve authoritatively and fall back to throwing an error if the resolution is ambiguous. In future releases, we may release support for resolving this sort of ambiguity (properties + ref, sub-property of a $ref and as sub-property conflicting, etc) based on user-preference.
    • $dynamicRefs cannot yet be resolved using this method (you will only receive the ref itself.)

3.2.0

  • Add Validator.validateWithResults (This new method gives the most complete and customizable validation results)
  • Add JsonSchema.validateWithResults
  • Deprecate JsonSchema.validate
  • Deprecate Validator.validate
  • Deprecate JsonSchema.validateWithErrors
  • Deprecate Validator.errors
  • Deprecate Validator.errorObjects

3.1.0

  • Remove the need for separate browser and VM imports
  • Deprecate non-json RefProviders
  • More specific missing-required property errors

3.0.0

  • Removed support for Dart 1

2.2.0

  • Add note about root path in error string when instance path is empty
  • Expose ValidationError class

2.1.4

  • Use deep equality to compare maps, fixing equality when enums are present

2.1.3

  • New validateWithErrors method on JsonSchema returns all validation errors as a list of objects
  • ValidationError objects include both instance & schema paths for each error
  • Error logic tweaked to provide consistent error paths in JSON pointer notation

2.0.0

  • json_schema is no longer bound to dart:io and works in the browser!
  • Full JSON Schema draft6 compatibility
  • Much better $ref resolution, including deep nesting of $refs
  • More typed keyword getters for draft6 like examples
  • Synchronous schema evaluation by default
  • Optional async evaluation and fetching with createSchemaAsync
  • Automatic parsing of JSON strings passed to createSchema and createSchemaAsync
  • Ability to do custom resolution of $refs with RefProvider and RefProviderAsync
  • Optional parsing of JSON strings passed to validate with parseJson = true
  • Dart 2.0 compatibility
  • Many small changes to make things more in line with modern dart.
  • Please see the migration guide for additional info.

1.0.8

  • Code cleanup
  • Strong mode
  • Switch build tools to dart_dev

1.0.7

  • Update dependency constraint on the args package.

1.0.3

  • Add a dependency on the args package.

1.0.2

  • Add a dependency on the logging package.

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'json_schema:5.1.0'
pubspec.yaml
name: json_schema
version: 5.1.0
description: JSON Schema implementation in Dart
homepage: https://github.com/workiva/json_schema

environment:
  sdk: '>=2.12.0 <3.0.0'

dependencies:
  collection: ^1.15.0
  http: ^0.13.4
  logging: ^1.0.0
  rfc_6901: ^0.1.0
  uri: '>=0.11.1 <2.0.0'

dev_dependencies:
  dependency_validator: ^3.1.2
  path: ^1.8.0
  shelf: ^1.0.0
  shelf_static: ^1.0.0
  test: ^1.17.0
  workiva_analysis_options: ^1.2.2

Version history

VersionPublishedArchiveSHA-256
0.0.1Cached · Upstream SHA-256 matchedDownload6e971894…ba8d04
0.0.2Cached · Upstream SHA-256 matchedDownload830a3456…dfe101
1.0.0Cached · Upstream SHA-256 matchedDownload3a945c9a…f3d551
1.0.1Cached · Upstream SHA-256 matchedDownload928b3024…20c89b
1.0.2Cached · Upstream SHA-256 matchedDownloadfe7c4b2a…d1fe7a
1.0.3Cached · Upstream SHA-256 matchedDownload0f19f647…d2fcd3
1.0.4Cached · Upstream SHA-256 matchedDownload32746b07…75f861
1.0.5Cached · Upstream SHA-256 matchedDownloadbf4e3762…cf3f67
1.0.6Cached · Upstream SHA-256 matchedDownload0e37180c…021ae1
1.0.7Cached · Upstream SHA-256 matchedDownload6dafff24…f5de64
1.0.8Cached · Upstream SHA-256 matchedDownload09f61ada…b00371
1.0.9Cached · Upstream SHA-256 matchedDownloadd34cdf92…eeee52
1.0.10Cached · Upstream SHA-256 matchedDownload7cd7d0fb…f06ce6
2.0.0-RC1Cached · Upstream SHA-256 matchedDownload958f7471…3614ac
2.0.0-RC2Cached · Upstream SHA-256 matchedDownload9771c5e7…8d6157
2.0.0-RC3Cached · Upstream SHA-256 matchedDownload337ee155…fc9a20
2.0.0Cached · Upstream SHA-256 matchedDownloadd6c7f992…f60bf8
2.0.1Cached · Upstream SHA-256 matchedDownload0f59efb9…fb6816
2.1.0Cached · Upstream SHA-256 matchedDownload8f9a5eb7…48c841
2.1.2Cached · Upstream SHA-256 matchedDownload7896f5da…737f4f
2.1.3Cached · Upstream SHA-256 matchedDownload39054a75…6cda3b
2.1.4Cached · Upstream SHA-256 matchedDownload1d2c28bb…84deb8
2.2.0Cached · Upstream SHA-256 matchedDownload811b34af…e03d7d
2.2.1Cached · Upstream SHA-256 matchedDownload345c478b…83f092
3.0.0Cached · Upstream SHA-256 matchedDownloadb8bf0e77…a7d1fe
3.0.1Cached · Upstream SHA-256 matchedDownload3a316f9e…0712c2
3.1.0Cached · Upstream SHA-256 matchedDownload5ce9cc98…057efc
3.1.1Cached · Upstream SHA-256 matchedDownload0e2cba88…827f82
3.2.0Cached · Upstream SHA-256 matchedDownload0e904e06…7f4fff
3.2.1Cached · Upstream SHA-256 matchedDownloaddefa58d4…0d4550
4.0.0-rc.1Cached · Upstream SHA-256 matchedDownload43c05020…e2211b
4.0.0-rc.2Cached · Upstream SHA-256 matchedDownload61f6ce6f…0c415e
4.0.0Cached · Upstream SHA-256 matchedDownload1ef01d65…2af7bc
4.0.1Cached · Upstream SHA-256 matchedDownload69e94786…886216
4.0.2Cached · Upstream SHA-256 matchedDownload5243b69c…971efb
4.0.3Cached · Upstream SHA-256 matchedDownloaddd50e239…e65896
4.0.4Cached · Upstream SHA-256 matchedDownloade83eb104…225caa
5.0.0-rc2Cached · Upstream SHA-256 matchedDownload9d81fde1…0759f8
5.0.0Cached · Upstream SHA-256 matchedDownloadd2d7b524…7807ad
5.1.0Cached · Upstream SHA-256 matchedDownloadb8df4801…30e6e0
5.1.1Cached · Upstream SHA-256 matchedDownloadd9325bc3…6838d9
5.1.2Cached · Upstream SHA-256 matchedDownload0fa8e7ba…bdd17b
5.1.3Cached · Upstream SHA-256 matchedDownload0a5f510e…4f6c7d
5.1.4Cached · Upstream SHA-256 matchedDownload7b3d4321…787046
5.1.5Cached · Upstream SHA-256 matchedDownload0df75856…c1bccc
5.1.6Cached · Upstream SHA-256 matchedDownload58d4c200…c00933
5.1.7Cached · Upstream SHA-256 matchedDownloadf1bcf816…62f358
5.2.0Cached · Upstream SHA-256 matchedDownloadb183ba82…d0a2cf
5.2.1Cached · Upstream SHA-256 matchedDownloadfc8c3e28…f20382
5.2.2Cached · Upstream SHA-256 matchedDownloadf37d9c3f…43fa1a

Dependencies

collection "^1.15.0"

http "^0.13.4"

logging "^1.0.0"

rfc_6901 "^0.1.0"

uri "\u003e=0.11.1 \u003c2.0.0"