# json_schema 4.0.4

JSON Schema implementation in Dart




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'json_schema:4.0.4'
```
Published: 2023-04-19T17:43:54.615333Z
Expected archive SHA-256: e83eb104920a5d7a5876e391f59e4ecfef4e93a0bbda8394b89e6c7d17225caa

Available in cache; verification: upstream_checksum
## Direct dependencies
- collection: ^1.14.6
- http: ^0.13.0
- logging: ^1.0.0
- rfc_6901: ^0.1.0
- uri: >=0.11.1 <2.0.0

## Package README (untrusted upstream documentation)
# 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.

```dart
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](https://github.com/Workiva/json_schema/blob/master/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 `JsonSchema`s 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](https://github.com/Workiva/json_schema/blob/master/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](https://github.com/Workiva/json_schema/blob/master/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](https://github.com/Workiva/json_schema/blob/master/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](https://github.com/Workiva/json_schema/blob/master/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](https://github.com/Workiva/json_schema/blob/master/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
## 4.0.3
- Remove usages of `.slice` to help downstream packages work around [a dart2js compiler bug](https://github.com/dart-lang/sdk/issues/48762#issuecomment-1139932469)

## 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, `$ref`s 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.
  - `$dynamicRef`s 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](./MIGRATION.md) 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.