Skip to content

Commit 4e42afc

Browse files
author
Michael Hahn
committed
Open source hack-json-schema
0 parents  commit 4e42afc

File tree

134 files changed

+18354
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

134 files changed

+18354
-0
lines changed

‎.gitignore

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/vendor/
2+
.vscode
3+
.notes
4+
composer.phar
5+
.DS_Store

‎.hhconfig

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
sharedmem_hash_table_pow=20
2+
sharedmem_dep_table_pow=20
3+
enable_experimental_tc_features=safe_pass_by_ref,unpacking_check_arity,no_fallback_in_namespaces,disallow_untyped_lambda_as_non_function_type,disallow_refs_in_array,shape_field_check,sealed_classes
4+
safe_array = true
5+
safe_vector_array = true
6+
disallow_destruct = true
7+
disallow_elvis_space=true
8+
disallow_non_arraykey_keys=true
9+
disallow_unsafe_comparisons=true
10+
decl_override_require_hint=true

‎CONTRIBUTING.md

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Contributors Guide
2+
3+
Interested in contributing? Awesome! Before you do though, please read our
4+
[Code of Conduct](https://slackhq.github.io/code-of-conduct). We take it very seriously, and expect that you will as
5+
well.
6+
7+
There are many ways you can contribute! :heart:
8+
9+
### Bug Reports and Fixes :bug:
10+
- If you find a bug, please search for it in the [Issues](https://github.com/slackhq/hack-json-schema/issues), and if it isn't already tracked,
11+
[create a new issue](https://github.com/slackhq/hack-json-schema/issues/new). Fill out the "Bug Report" section of the issue template. Even if an Issue is closed, feel free to comment and add details, it will still
12+
be reviewed.
13+
- Issues that have already been identified as a bug (note: able to reproduce) will be labelled `bug`.
14+
- If you'd like to submit a fix for a bug, [send a Pull Request](#creating_a_pull_request) and mention the Issue number.
15+
- Include tests that isolate the bug and verifies that it was fixed.
16+
17+
### New Features :bulb:
18+
- If you'd like to add new functionality to this project, describe the problem you want to solve in a [new Issue](https://github.com/slackhq/hack-json-schema/issues/new).
19+
- Issues that have been identified as a feature request will be labelled `enhancement`.
20+
- If you'd like to implement the new feature, please wait for feedback from the project
21+
maintainers before spending too much time writing the code. In some cases, `enhancement`s may
22+
not align well with the project objectives at the time.
23+
24+
### Tests :mag:, Documentation :books:, Miscellaneous :sparkles:
25+
- If you'd like to improve the tests, you want to make the documentation clearer, you have an
26+
alternative implementation of something that may have advantages over the way its currently
27+
done, or you have any other change, we would be happy to hear about it!
28+
- If its a trivial change, go ahead and [send a Pull Request](#creating_a_pull_request) with the changes you have in mind.
29+
- If not, [open an Issue](https://github.com/slackhq/hack-json-schema/issues/new) to discuss the idea first.
30+
31+
If you're new to our project and looking for some way to make your first contribution, look for
32+
Issues labelled `good first contribution`.
33+
34+
## Requirements
35+
36+
For your contribution to be accepted:
37+
38+
- [x] You must have signed the [Contributor License Agreement (CLA)](https://cla-assistant.io/slackhq/hack-json-schema).
39+
- [x] The test suite must be complete and pass.
40+
- [x] The changes must be approved by code review.
41+
- [x] Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.
42+
43+
If the contribution doesn't meet the above criteria, you may fail our automated checks or a maintainer will discuss it with you. You can continue to improve a Pull Request by adding commits to the branch from which the PR was created.
44+
45+
[Interested in knowing more about about pull requests at Slack?](https://slack.engineering/on-empathy-pull-requests-979e4257d158#.awxtvmb2z)
46+
47+
## Creating a Pull Request
48+
49+
1. :fork_and_knife: Fork the repository on GitHub.
50+
51+
2. :runner: Clone/fetch your fork to your local development machine. It's a good idea to run the tests just
52+
to make sure everything is in order.
53+
3. :herb: Create a new branch and check it out.
54+
4. :crystal_ball: Make your changes and commit them locally. Magic happens here!
55+
5. :arrow_heading_up: Push your new branch to your fork. (e.g. `git push username fix-issue-16`).
56+
6. :inbox_tray: Open a Pull Request on github.com from your new branch on your fork to `master` in this
57+
repository.

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2016-present Slack Technologies, Inc.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.PHONY: test hh_autoload composer
2+
3+
COMPOSER=~/.cache/composer/composer.phar
4+
5+
test: hh_autoload
6+
hhvm ./vendor/bin/hacktest tests
7+
8+
hh_autoload:
9+
./vendor/bin/hh-autoload
10+
11+
composer-fetch:
12+
test -f $(COMPOSER) || mkdir -p `dirname $(COMPOSER)`
13+
test -f $(COMPOSER) || wget -O $(COMPOSER) https://getcomposer.org/download/1.8.0/composer.phar
14+
15+
composer-install: composer-fetch
16+
hhvm $(COMPOSER) install
17+
18+
composer-update: composer-fetch
19+
hhvm $(COMPOSER) update
20+
21+
format:
22+
find {src,tests} -type f -exec hackfmt -i {} \;
23+
24+
examples: hh_autoload
25+
hhvm ./bin/generate-examples.php

‎README.md

+98
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Hack JSON Schema
2+
Hack JSON Schema is a library for validating JSON inputs, using JSON schemas, in Hack. Given a JSON schema file, you can generate a validator in Hack to validate incoming JSON against the schema. If the JSON conforms to the schema, the validator will returned typed output.
3+
4+
There are several benefits to generation:
5+
6+
- We don't have to parse the JSON schema to validate the incoming object at runtime.
7+
- We can output typed shapes that are generated from the JSON schema, increasing the type safety of downstream code.
8+
9+
## Usage
10+
11+
### Codegen::forPath
12+
The most basic way to use this library is to generate a validator from a JSON schema file:
13+
14+
```
15+
use type Slack\Hack\JsonSchema\Codegen\Codegen;
16+
17+
Codegen::forPath('/path/to/json-schema.json', shape(
18+
'validator' => shape(
19+
'file' => '/path/to/MyJsonSchemaValidator.php',
20+
'class' => 'MyJsonSchemaValidator',
21+
),
22+
))->build();
23+
```
24+
25+
`/path/to/MyJsonSchemaValidator.php` now exists with a class:
26+
27+
```
28+
final class MyJsonSchemaValidator extends BaseValidator {
29+
... class contents
30+
}
31+
```
32+
33+
Each validator has a `validate` method, which takes a decoded JSON object:
34+
35+
```
36+
$json = json_decode($args['json_input'], true);
37+
$validator = new MyJsonSchemaValidator($json);
38+
$validator->validate();
39+
if (!$validator->isValid()) {
40+
print_r("invalid_json", $validator->getErrors());
41+
return;
42+
}
43+
44+
// JSON is valid, get typed object:
45+
$validated = $validator->getValidatedInput();
46+
```
47+
48+
### Codegen::forPaths
49+
If you have multiple JSON schemas that leverage the `$ref` attribute, you should prefer to use `Codegen::forPaths` over `Codegen::forPath`.
50+
51+
The workflow for `Codegen::forPath` is:
52+
- Given a JSON schema, "de-reference" the schema. De-referencing is the process of resolving all of the `$ref` paths with their actual schema. This creates a single de-referenced schema.
53+
- With the de-referenced schema, generate a validator.
54+
55+
This works well if you only have one primary schema, but if you have multiple schemas, each with common refs, you'll start to generate a lot of duplicate code.
56+
57+
In these cases, you can use `Codegen::forPaths`.
58+
59+
```
60+
use type Slack\Hack\JsonSchema\Codegen\Codegen;
61+
62+
$schemas = vec['/path/to/json-schema-1.json', '/path/to/json-schema-2.json', '/path/to/json-schema-3.json'];
63+
Codegen::forPaths($schemas, shape(
64+
'validator' => shape(
65+
'refs' => shape(
66+
'unique' => shape(
67+
'source_root' => '/path/to',
68+
'output_root' => '/path/gen'
69+
)
70+
)
71+
),
72+
))->build();
73+
```
74+
75+
By defining the `source_root` and `output_root` we can generate unique validators per `$ref` we come across. We can then re-use those validators when generating other validators.
76+
77+
## Developing
78+
79+
### Installing Dependencies
80+
We use composer to install our dependencies. Running the following will install composer (if it doesn't exist already) and install the dependencies:
81+
82+
```
83+
make composer-install
84+
```
85+
86+
### Running Tests
87+
```
88+
make test
89+
```
90+
91+
## Related Libraries
92+
This library was inspired by the ideas in these related libraries:
93+
94+
- https://github.com/hhvm/hack-router-codegen
95+
- https://github.com/justinrainbow/json-schema
96+
97+
## License
98+
Hack JSON Schema is MIT-licensed.

‎bin/hackfmt

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#!/bin/bash
2+
3+
file=`realpath $1`
4+
shift # remove filename so getopts ignores it
5+
6+
# Since this wrapper performs in-place modification of a file, it can speed up
7+
# some editor workflows (e.g., Sublime) to perform the formatting over a
8+
# tempfile that is generated during a pre-save hook. Such tempfiles will cause
9+
# false negatives in the test for ignored file paths, so we provide an option
10+
# for the caller to provide an effective ignore path as a flag.
11+
ignore_path=$file
12+
while getopts "i:" opt; do
13+
case ${opt} in
14+
i )
15+
ignore_path=$OPTARG
16+
shift
17+
;;
18+
esac
19+
done
20+
shift $((OPTIND -1)) # cleanup getopts
21+
22+
# run hackfmt if file doesn't match regex of ignored file paths
23+
[[ "$ignore_path" =~ ^(examples|external_examples) ]] || hackfmt --in-place $file

‎composer.json

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"name": "slack/hack-json-schema",
3+
"description": "Hack JSON Schema generator",
4+
"type": "library",
5+
"authors": [
6+
{
7+
"name": "Michael Hahn",
8+
"email": "[email protected]"
9+
}
10+
],
11+
"require": {
12+
"facebook/hack-codegen": "4.0.2",
13+
"hhvm/hsl": "3.30.0",
14+
"hhvm/type-assert": "3.2.6"
15+
},
16+
"require-dev": {
17+
"facebook/fbexpect": "2.3.0",
18+
"hhvm/hacktest": "1.3"
19+
},
20+
"autoload": {
21+
"classmap": [ "src/" ]
22+
},
23+
"autoload-dev": {
24+
"classmap": [ "tests/" ]
25+
}
26+
}

0 commit comments

Comments
 (0)