Originaler README-Schnappschuss aus dem verknüpften Quell-Repository. Aktuelle Inhalte finden Sie im Repository.
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 pubget
make format
make analyze
make 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 test or dart test -n <YOUR TEST>
- 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
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.
- 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() {
final mustBeIntegerSchemaMap = {"type": "integer"};
final n = 3;
final decimals = 3.14;
final str = 'hi';
final schema = JsonSchema.create(mustBeIntegerSchemaMap);
print('$n => ${schema.validate(n)}');
print('$decimals => ${schema.validate(decimals)}');
print('$str => ${schema.validate(str)}');
}
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.