Skip to content

docs: update CONTRIBUTING with JSON schema advice #148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: update CONTRIBUTING with JSON schema advice #148

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d6b9480
docs: simplify CONTRIBUTING lead-in
cpu Jun 11, 2025
4e32e38
docs: update CONTRIBUTING with JSON schema advice
cpu Jun 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 33 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Want to contribute? Great! First, read this page (including the small print at
the end).
Want to contribute? Great!

### Before you contribute
Before you start working on a larger contribution, you should get in touch with
Expand All @@ -15,3 +14,35 @@ bugs have been acknowledged or fixed.
### Code reviews
All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose.

### Test schemas
All new test types should be accompanied by [JSON schema] files describing the
test vector data structure. See the [`schemas/` directory][schema dir] for
existing examples.

Test vector files are [linted in CI][schema lint] against their schemas. You can
run the lint locally after installing Go with `go run ./tools/vectorlint`.

#### Schema best practices

All new schema files should:

* Describe common top-level properties matching pre-existing schemas/vectors
(e.g. `algorithm`, `header`, `notes`, `numberOfTests`, and `schema`).
* Divide vector files into test groups.
* Use `"additionalProperties": false` in each defined object to prevent
unspecified fields in vector data.
* Use `"required": [...]` in each defined object to specify the expected
mandatory properties in vector data.
* Within each test group, specify a `source`, referencing the common
[`common.json#/definitions/Source`][source schema] element.
* Avoid deprecated schema fields (e.g. `generatorVersion`).
* Avoid duplicating complex schema elements across many schema files (e.g.
public key definitions). Instead, create a separate schema file for the common
object and [reference it][schema ref] throughout other schema files.

[JSON schema]: https://json-schema.org/
[schema dir]: https://github.com/C2SP/wycheproof/tree/main/schemas
[schema lint]: https://github.com/C2SP/wycheproof/blob/main/.github/workflows/vectorlint.yml
[source schema]: https://github.com/C2SP/wycheproof/blob/main/schemas/common.json
[schema ref]: https://json-schema.org/understanding-json-schema/structuring#dollarref