Best Practices Documentation?

[shitwolfymakes]

I am new to working with JSON Schema, and I'm creating schema to describe the structure and validate the data of some game files. The schema are needed by both the game itself (to validate changes to game files during CI/CD testing), and the RAD tool that develops content for the game. For simplicity and interface segregation, all schema are going to be in a separate public repo.

I have scoured the official documentation, but I haven't seen anything on:

1. Version Control: How do I test and validate changes made to the schema? (e.g., pull requests)
2. Publishing Changes: How do I publish the schema in the repo once they're ready? (e.g., always reference main, or branch for each official version?)
3. Documentation Generation: How do I publish the documentation for each version? (e.g., some sort of CI/CD action, a Pages repo that generates the docs for each tag?)
4. Repo Folder Structure: How do I organize all the schema files? (e.g., one folder with all the schema and one with all the tests, or a folder for each schema that contains both the schema file and its specific tests?)

I can definitely figure out a way to do all of this stuff, but I'd rather follow best practices wherever possible. I've also been googling for best practices on generic schema development and publishing, but I haven't found anything useful

[jdesrosiers]

Our documentation is certainly lacking (we're working on it), but I don't think any of this is the kind of thing that would go in the official documentation. It's all very subjective and isn't specific to JSON Schema. It's all stuff that applies equally to any type of code. There aren't many JSON Schema specific considerations you need to take into account. Just treat your schemas the same way you treat code and you'll be fine. I'll try to address each of your questions as best I can. I hope it's helpful.

1. Version Control
   You can write tests using your favorite testing framework just like your other code.
2. Publishing Changes
   If you choose to publish your schemas using Github URLs, keep in mind that you will not get a proper Content-Type header. Github uses something generic like text/plain. The official content type for a JSON Schema is application/schema+json. That doesn't always matter, but if it does, you'll want to publish it some other way. Other than the content type, there are no special considerations for serving schemas. You can do it same way you would any other HTTP API.
3. Documentation Generation
   You can find documentation generators on the implemations page of the website. As for processes and automation, do whatever you would do for any other documentation generation. There are no special considerations for JSON Schema.
4. Repo Folder Structure
   Treat it just like code. If you like having your tests next to your code (I do), then do that. If you like them separate, that's fine too. Use folders to organize schemas just like you would for any other code.

[Relequestual]

Treat Schemas like code is a good approach.