+ Help and clarify how JSON Schema can be interpreted from validation rules to data definition. This extends to how those data definitions can be represented in any programming language +
+ +## Status + +While the project is only first getting started, the initial agenda is: +1. Define a processing model for interpreting JSON Schema to data definitions. + * Define code generation vocabulary as needed, while the processing model is being defined + +## Charter +To help explain the process, the project, the SIG and the community, in terms of how they all relate, please refer to the [charter](./charter.md). + +## Code of Conduct +Respect each other. Choose empathy over judgement. Act according to the [Code of Conduct](./CODE_OF_CONDUCT.md). + +## Getting involved +If you want to review changes, creating documentation, help form suggestions or take charge in figuring out a specific task, we welcome any way you want to get involved. + +If you find an issue you would like to work on you can drop a comment, ask questions or discuss the approaches. Or if you see we are missing specific things feel free to create new issues. + +We have a dedicated slack channel `#vocab-idl`- in the JSON Schema slack, join the JSON Schema slack here: https://json-schema.org/slack. + +You can use this channel if you don't know where to get started, discuss specifics of issues, get updates, or in general hang out. + +## Contributing +In case contributions are for changing content on git, please refer to [git workflow](./git_workflow.md). + +Any contributions that changes the content of this repository MUST go through pull requests. + +We use [All Contributors](https://allcontributors.org) specification to handle recognitions. You can help us out in many different ways. Just check out [this](https://allcontributors.org/docs/en/emoji-key) list of possible contributions. All of this is a contribution! diff --git a/charter.md b/charter.md new file mode 100644 index 0000000..ab1cb10 --- /dev/null +++ b/charter.md @@ -0,0 +1,43 @@ +# JSON Schema IDL charter +The purpose of this charter is to give a brief introduction to the project, the SIG, and the community how they all relate. + +## Section 0: Guiding Principles + +Because of the nature of JSON Schema, you don't define the data structure but the validation rules that data should comply with, trying to interpret these rules definitions is a pain point for many. Providing a clear description of how this can be achieved would help not only the developer that uses JSON Schema in this area, but also helps standardize the behavior improving the user experience. + +## Section 1: Scope + +Help and clarify how JSON Schema can be interpreted from validation rules to data definition. This extends to how those data definitions can be represented in any programming language. To accommodate the JSON Schema spec and the interpretation process a code generation vocabulary will be created. + +Implementations are neither in nor out of scope for the project, but it is not a high prioritization. + +A test suite is expected to be produced along side the work, to better discuss and formulate specific cases. + +## Section 2: Relationship with JSON Schema organization. + +The project is not directly involved with the actual JSON Schema specification development, however contributors may be contributors of both. The JSON Schema organization and community may provide guidance and review on vocabulary proposals and proposed releases. It is expected that this project and resulting artifacts will be maintained by teams other than those part of the JSON Schema organization. + +The JSON Schema organization will force this project to comply with the organization-level code of conduct if required, and may require other project level changes such as workflow changes. + +## Section 3: The Special interest group + +The SIG members are no different from the regular community besides it is their responsibility to understand all points of view of the community and push the project forward. + +The community can get involved by jumping into discussions in issues, pull requests, etc, as long as the [Code of Conduct](./CODE_OF_CONDUCT.md) and [git workflow](./git_workflow.md) is adhered to. + + +SIG memberships are not time-limited. There is no maximum size of the SIG. It is expected that the SIG members actively participate in discussions and maintain the repository, otherwise they will remain a contributor. + +Any SIG members that do not actively participate in discussions or maintain the repository within 30 days will be removed from the SIG list and return to being contributors. + +The SIG group is currently made up of the following individuals. Feel free to submit an issue requested to be added. + +- Jonas Lagoni ([Senior Software Engineer at Postman, working on AsyncAPI](https://www.linkedin.com/in/jonaslagoni/)) +- [Jason Desrosiers](https://github.com/jdesrosiers) + +## Section 4: Definitions + +Definitions that should be clarified to align meaning. + +- **Validation rules**, i.e. a JSON Schema as such `{type: string}` define that data should validate against a string, it does not define that the data is a string. For small validation rules, there is almost no difference, but with more complex ones it becomes apparent. +- **Data definition**, i.e. it defines the exact structure of the data. diff --git a/git_workflow.md b/git_workflow.md new file mode 100644 index 0000000..5e75c3d --- /dev/null +++ b/git_workflow.md @@ -0,0 +1,87 @@ +> Copied mostly from the [AsyncAPI Git-workflow](https://github.com/asyncapi/.github/blob/master/git-workflow.md) + +This document is the best practice guide that contains the rules to follow when working with the repository. + +### Basic rules + +Each contributor must follow this workflow: + +* Work on forked repositories. +* Create branches on the fork and avoid working directly on the `main` branch. + +## Prepare the fork + +A fork is a copy of the repository from which you raise pull requests to propose changes to the original repository. + +The unified contribution workflow that bases on forks allows both SIG members and contributors to contribute code and content through the same process. This keeps the main repositories branches clean as contributors create branches only on the forked repositories. + +## Configure your fork + +The document refers to the original repository as the upstream repository and to the forked repository as the origin repository. We assume you already have a fork of the upstream and you `git clone` it already. + +### Working on a Fork on local + +> If you perform such configuration for the first time, it is recommended to do it manually to understand all the steps. Next time you do it you can write a script for it or use something like [this](https://gist.github.com/derberg/87319e9c486e4a6c9bef5b629ab0d386) + +Configure a `remote` repository that points to the upstream repository. This allows you to synchronize changes you make on the fork with the original repository. + +In the terminal, navigate to the location of your fork and perform the following steps: + +1. Run the `git remote -v` command to list the current configured remote repository for your fork. +The result is as follows: + ``` + origin https://github.com/{your-username}/{your-fork}.git (fetch) + origin https://github.com/{your-username}/{your-fork}.git (push) + ``` + See the example: + ``` + origin https://github.com/i000000/json-schema-idl.git (fetch) + origin https://github.com/i000000/json-schema-idl.git (push) + ``` + +2. Specify a new remote upstream repository to synchronize with the fork: + ``` + git remote add upstream https://github.com/{original-owner}/{original-repository}.git + ``` + See the example: + ``` + git remote add upstream https://github.com/json-schema-org/json-schema-idl.git + ``` +3. Run the `git fetch upstream main` command to fetch all branches. +4. Set up the local `main` branch to track the remote `main` branch from the upstream repository: + ``` + git branch -u upstream/main main + ``` + +Now, each time you rebase or check out the `main` branch, you refer to the `main` branch of the upstream repository. In other words, when you create a branch from local up-to-date `main` means creating a branch from latest upstream `main`. + +To verify that your local `main` branch points to the `upstream/main`, run the `git branch -vv` command. The result is similar to the following: +``` +* main c2226e0 [upstream/main] Update the README.md document +``` + +### Working on a Fork in GitHub UI + +In case you are a contributor who suggests minor changes using GitHub UI, it is recommended to use a [Pull bot](https://probot.github.io/apps/pull). This bot keeps your fork up to date by creating and merging a pull request with latest changes into the `main `branch of your fork. + +## Start Contributing + +After you set up your fork, start contributing code and content. + +Follow these steps: + +1. Create a branch on your fork. + +2. Commit changes. Always provide clear commit messages to track commit changes easier. + +3. Push the changes to the remote forked repository. + + >**NOTE:** Before you push local changes, make sure you are on the branch you are currently working on. Do not push any changes from the `main` branch. + + If you push local changes from the terminal to your remote fork for the first time, use this command: + ``` + git push -u origin {branch-name} + ``` + Use the `git push` command to push any further commits made on your local branch to a remote repository. + +4. Create a pull request from the branch of your forked repository to the `main` branch of the upstream repository and wait for the maintainers' review.