Viewing version 5.0.0. Open the latest package page.
json_schema
5.0.0JSON Schema implementation in Dart
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
- Ensure you have latest stable Dart installed.
make pubgetmake formatmake analyzemake test-with-serve-remotes
Alternative Test Running Strategy (To run specific tests, or pass other args to dart test):
make serve-remotes(in a separate terminal tab - HTTP fixtures need to be served for tests to pass)make testordart test -n <YOUR TEST>- SIGINT your
make serve-remotestab or runmake 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
make gen-fixturesGenerates Dart source files that contain the JSON-Schema-Test-Suite tests and fixtures for use in cross-platform testing that doesn't requiredart:ioto read the files on disk.- 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.0
- Bump minimum Dart SDK version to 2.12.0
- Migration to null safety
4.0.3
- Remove usages of
.sliceto help downstream packages work around a dart2js compiler bug
4.0.2
- Fix bug where
typegetter would throw whentypeListwas null
4.0.1
- Performance:
- cache calls to
resolvePath JsonSchema.schemaMapis now truly unmodifiable (was before in practice anyway) andhashCodeis cached by taking advantage of that.
- cache calls to
- 4.0 Release Mistake:
Validator.evaluatedPropertieswas 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> customVocabulariescan be passed to all JsonSchema factories.CustomVocabularyCustomKeywordValidationContext
- Custom Formats:
Map<String, Function> customFormatscan be passed to andJsonSchemafactory.ValidationContext
- Support for JSON Schema Draft 2019-09 (
- Deprecated:
validateWithResultsin favor ofvalidatewhich now returns the same thing (ValidationResults).DefaultValidatorsand related globals in favor of passingcustomFormatsto theJsonSchemafactories.
- Removed Deprecations:
- Removed
bin/schemadot.dart,lib/schema_dot.dartand related examples - Removed
lib/browser.dartandlib/vm.dartand associated globalscreateSchemaFromUrlBrowser,configureJsonSchemaForBrowser,globalCreateJsonSchemaFromUrlcreateSchemaFromUrlVm,configureJsonSchemaForVmandresetGlobalTransportPlatform. These were for configuring the runtime environment, which now happens automatically. - Removed
JsonSchema.createSchemaAsyncin favor ofJsonSchema.createAsync - Removed
JsonSchema.createSchemain favor ofJsonSchema.create - Removed
JsonSchema.createSchemaFromUrlin favor ofJsonSchema.createFromUrl - Removed
RefProvider.asyncSchema,RefProvider.syncSchema,RefProvider.asyncJson, andRefProvider.syncJsonin favor ofRefProvider.asyncandRefProvider.async, which are easier to use. - Removed
JsonSchema.refMap
- Removed
- Breaking change to
validate:- now returns
ValidationResultinstead ofboollikevalidateWithResults(now deprecated).
- now returns
- Notable change of behavior to
resolvePathwith 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.)
- When used with draft 2019-09 or draft 2020-12,
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
ValidationErrorclass
2.1.4
- Use deep equality to compare maps, fixing equality when enums are present
2.1.3
- New
validateWithErrorsmethod onJsonSchemareturns all validation errors as a list of objects ValidationErrorobjects 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
createSchemaandcreateSchemaAsync - Ability to do custom resolution of $refs with
RefProviderandRefProviderAsync - Optional parsing of JSON strings passed to
validatewithparseJson = 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
argspackage.
1.0.3
- Add a dependency on the
argspackage.
1.0.2
- Add a dependency on the
loggingpackage.
Installing
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'json_schema:5.0.0'pubspec.yaml
name: json_schema
version: 5.0.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: '>=0.9.3 <2.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
| Version | Published | Archive | SHA-256 |
|---|---|---|---|
| 0.0.1 | Cached · Upstream SHA-256 matched | Download | 6e971894…ba8d04 |
| 0.0.2 | Cached · Upstream SHA-256 matched | Download | 830a3456…dfe101 |
| 1.0.0 | Cached · Upstream SHA-256 matched | Download | 3a945c9a…f3d551 |
| 1.0.1 | Cached · Upstream SHA-256 matched | Download | 928b3024…20c89b |
| 1.0.2 | Cached · Upstream SHA-256 matched | Download | fe7c4b2a…d1fe7a |
| 1.0.3 | Cached · Upstream SHA-256 matched | Download | 0f19f647…d2fcd3 |
| 1.0.4 | Cached · Upstream SHA-256 matched | Download | 32746b07…75f861 |
| 1.0.5 | Cached · Upstream SHA-256 matched | Download | bf4e3762…cf3f67 |
| 1.0.6 | Cached · Upstream SHA-256 matched | Download | 0e37180c…021ae1 |
| 1.0.7 | Cached · Upstream SHA-256 matched | Download | 6dafff24…f5de64 |
| 1.0.8 | Cached · Upstream SHA-256 matched | Download | 09f61ada…b00371 |
| 1.0.9 | Cached · Upstream SHA-256 matched | Download | d34cdf92…eeee52 |
| 1.0.10 | Cached · Upstream SHA-256 matched | Download | 7cd7d0fb…f06ce6 |
| 2.0.0-RC1 | Cached · Upstream SHA-256 matched | Download | 958f7471…3614ac |
| 2.0.0-RC2 | Cached · Upstream SHA-256 matched | Download | 9771c5e7…8d6157 |
| 2.0.0-RC3 | Cached · Upstream SHA-256 matched | Download | 337ee155…fc9a20 |
| 2.0.0 | Cached · Upstream SHA-256 matched | Download | d6c7f992…f60bf8 |
| 2.0.1 | Cached · Upstream SHA-256 matched | Download | 0f59efb9…fb6816 |
| 2.1.0 | Cached · Upstream SHA-256 matched | Download | 8f9a5eb7…48c841 |
| 2.1.2 | Cached · Upstream SHA-256 matched | Download | 7896f5da…737f4f |
| 2.1.3 | Cached · Upstream SHA-256 matched | Download | 39054a75…6cda3b |
| 2.1.4 | Cached · Upstream SHA-256 matched | Download | 1d2c28bb…84deb8 |
| 2.2.0 | Cached · Upstream SHA-256 matched | Download | 811b34af…e03d7d |
| 2.2.1 | Cached · Upstream SHA-256 matched | Download | 345c478b…83f092 |
| 3.0.0 | Cached · Upstream SHA-256 matched | Download | b8bf0e77…a7d1fe |
| 3.0.1 | Cached · Upstream SHA-256 matched | Download | 3a316f9e…0712c2 |
| 3.1.0 | Cached · Upstream SHA-256 matched | Download | 5ce9cc98…057efc |
| 3.1.1 | Cached · Upstream SHA-256 matched | Download | 0e2cba88…827f82 |
| 3.2.0 | Cached · Upstream SHA-256 matched | Download | 0e904e06…7f4fff |
| 3.2.1 | Cached · Upstream SHA-256 matched | Download | defa58d4…0d4550 |
| 4.0.0-rc.1 | Cached · Upstream SHA-256 matched | Download | 43c05020…e2211b |
| 4.0.0-rc.2 | Cached · Upstream SHA-256 matched | Download | 61f6ce6f…0c415e |
| 4.0.0 | Cached · Upstream SHA-256 matched | Download | 1ef01d65…2af7bc |
| 4.0.1 | Cached · Upstream SHA-256 matched | Download | 69e94786…886216 |
| 4.0.2 | Cached · Upstream SHA-256 matched | Download | 5243b69c…971efb |
| 4.0.3 | Cached · Upstream SHA-256 matched | Download | dd50e239…e65896 |
| 4.0.4 | Cached · Upstream SHA-256 matched | Download | e83eb104…225caa |
| 5.0.0-rc2 | Cached · Upstream SHA-256 matched | Download | 9d81fde1…0759f8 |
| 5.0.0 | Cached · Upstream SHA-256 matched | Download | d2d7b524…7807ad |
| 5.1.0 | Cached · Upstream SHA-256 matched | Download | b8df4801…30e6e0 |
| 5.1.1 | Cached · Upstream SHA-256 matched | Download | d9325bc3…6838d9 |
| 5.1.2 | Cached · Upstream SHA-256 matched | Download | 0fa8e7ba…bdd17b |
| 5.1.3 | Cached · Upstream SHA-256 matched | Download | 0a5f510e…4f6c7d |
| 5.1.4 | Cached · Upstream SHA-256 matched | Download | 7b3d4321…787046 |
| 5.1.5 | Cached · Upstream SHA-256 matched | Download | 0df75856…c1bccc |
| 5.1.6 | Cached · Upstream SHA-256 matched | Download | 58d4c200…c00933 |
| 5.1.7 | Cached · Upstream SHA-256 matched | Download | f1bcf816…62f358 |
| 5.2.0 | Cached · Upstream SHA-256 matched | Download | b183ba82…d0a2cf |
| 5.2.1 | Cached · Upstream SHA-256 matched | Download | fc8c3e28…f20382 |
| 5.2.2 | Cached · Upstream SHA-256 matched | Download | f37d9c3f…43fa1a |
Dependencies
collection "^1.15.0"
http "^0.13.4"
logging "\u003e=0.9.3 \u003c2.0.0"
rfc_6901 "^0.1.0"
uri "\u003e=0.11.1 \u003c2.0.0"