Contributing

Thank you for helping test whether organizational judgment can have a useful portable format.

This is a research preview. Critical feedback, counterexamples, and removal proposals are as valuable as additive features.

Good first contributions

• a pack example from a domain unlike the existing examples;
• an ambiguity or contradiction in the draft prose;
• a case accepted by the schema that should be rejected;
• a case rejected by the schema that should be portable;
• an interoperability, privacy, security, or authoring-cost concern;
• evidence that a concept belongs in a profile rather than Core.

Working on an issue

You're welcome to comment that you'd like to take an issue, and a maintainer may assign it to you. Only that assignment reserves it. Without one, the first pull request that meets the issue's acceptance criteria is the one that gets merged, and until then the issue stays open to anyone.

Work on one issue at a time. Finish the pull request you have open, or say you're withdrawing it, before you take another. We assign at most one issue to each contributor at once.

If an assigned issue goes quiet for a couple of weeks with no pull request, a maintainer will check in. If there's no reply within a week after that, the issue is unassigned so someone else can pick it up. You're welcome to take it back while it's still open.

Before proposing a feature

Open a design issue describing:

1. the user or interoperability problem;
2. at least two realistic examples;
3. why an extension or external product behavior is insufficient;
4. compatibility and migration consequences;
5. security and privacy consequences; and
6. how two independent implementations could test agreement.

Material changes should become a Request for Comments (RFC). Copy the structure in rfcs/0000-rfc-process.md.

Pull requests

A pull request should:

• remain focused on one problem;
• link the relevant issue or RFC;
• update prose, schema, examples, and conformance cases together when applicable;
• include at least one negative or adversarial case for normative behavior;
• identify breaking changes explicitly; and
• avoid claiming that conformance proves truth, authorization, or safety.

Normative changes are not accepted solely because the reference implementation supports them.

Local checks

CI runs the repository checks on Python 3.12. That is what the workflow currently uses rather than a declared minimum version for the project.

Install the test dependencies:

python -m pip install -r requirements-dev.txt

Run the same checks CI runs:

python -m unittest discover -s tests -v

Install the dependencies even if the suite appears to run without them. requirements-dev.txt pins jsonschema[format-nongpl], and the format keyword is only checked when those extras are present. Without them, jsonschema silently ignores format, so conformance cases that exist to prove a malformed URI or timestamp is rejected come back valid and the suite passes while checking less than it says it does. Two current corpus cases behave exactly that way.

Developer Certificate of Origin

Contributions must be signed off using Git's --signoff option. The sign-off certifies the Developer Certificate of Origin 1.1: https://developercertificate.org/.

License

By contributing, you agree that your contribution is licensed under Apache License 2.0.

Conduct

Participation is governed by CODE_OF_CONDUCT.md.