https://github.com/seddryck/schemathief
Schemathief is a .NET CLI tool that compares a C# class with an existing jsonSchema and forges a clean, standards-compliant JSON Schema delta. It’s ideal for schema evolution tracking, CI pipelines, and making sure your custom additions don’t silently diverge from the spec.
https://github.com/seddryck/schemathief
cli-tool json-schema
Last synced: 9 days ago
JSON representation
Schemathief is a .NET CLI tool that compares a C# class with an existing jsonSchema and forges a clean, standards-compliant JSON Schema delta. It’s ideal for schema evolution tracking, CI pipelines, and making sure your custom additions don’t silently diverge from the spec.
- Host: GitHub
- URL: https://github.com/seddryck/schemathief
- Owner: Seddryck
- License: apache-2.0
- Created: 2025-05-05T18:22:49.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2025-05-09T07:20:04.000Z (15 days ago)
- Last Synced: 2025-05-15T18:17:09.675Z (9 days ago)
- Topics: cli-tool, json-schema
- Language: C#
- Homepage:
- Size: 3.18 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Schemathief
Schemathief is a lightweight .NET library and CLI tool for generating JSON-Schema delta documents from your CLR types. Whether you need to keep your API schema up-to-date, drive automated data-model documentation, or generate client stubs only for the new fields you’ve added, Schemathief does the heavy lifting:
### Load & compare
* Fetches a base schema from a URL or file via a pluggable IBaseSchemaLoader
* Reflects over your target assembly to discover all public, read/write properties
* Allows you to exclude known fields (e.g. legacy or deprecated properties)
### Generate delta
* Maps .NET types to JSON-Schema types (string, integer, array, object) with full support for nullable, primitive, and complex types
* Recursively builds nested definitions for child objects and collections
* Produces a minimal “delta schema” that you can combine with your base via an allOf merge
### CLI & API
* A dotnet tool–friendly System.CommandLine implementation (delta verb, intuitive options) ready for CI/CD
* Dependency-injection–friendly services (IDeltaService, IBaseSchemaLoader) so you can stub or replace behavior in your own apps
* Fully unit‐tested core (SchemaBuilder, TypeInspector, ClrToJsonTypeMapper, TypeInspectorHelper) and integration‐tested end-to-end
### Pack & ship
* Ship your own JSON-Schema artifacts right inside your NuGet package via contentFiles/any/any/schemas so consumers get editor IntelliSense out of the box
* Integrates smoothly into existing build pipelines with dotnet pack, GitVersion, or any other automation
# Why Schemathief?
* Zero boilerplate: No more hand-crafting schema diffs by hand or writing reflection glue in every project.
* Future-proof: Designed around the JSON-Schema draft-07 spec today, easy to extend for draft-next tomorrow.
* Give it a try in your next microservice or data-model repo—keep your schemas in lock-step with your code
[About][] | [Installing][] | [Quickstart][]
[About]: #about (About)
[Installing]: #installing (Installing)
[Quickstart]: #quickstart (Quickstart)
## About
**Social media:** [](https://seddryck.github.io/Schemathief)
[](https://twitter.com/Seddryck)
**Releases:** [](https://github.com/seddryck/schemathief/releases/latest)
[](https://www.nuget.org/packages/Schemathief-cli/) [](https://hub.docker.com/repository/docker/seddryck/schemathief/) [](https://github.com/Seddryck/Schemathief/releases/latest) [](https://github.com/Seddryck/Schemathief/blob/master/LICENSE)
**Dev. activity:** [](https://github.com/Seddryck/Schemathief/commits)
**Continuous integration builds:** [](https://ci.appveyor.com/project/Seddryck/Schemathief/)
[](https://ci.appveyor.com/project/Seddryck/Schemathief/build/tests)
[](https://www.codefactor.io/repository/github/seddryck/Schemathief)
[](https://codecov.io/github/Seddryck/Schemathief)
**Status:** [](https://github.com/Seddryck/Schemathief/stargazers)
[](https://github.com/Seddryck/Schemathief/issues?utf8=%E2%9C%93&q=is:issue+is:open+label:bug+)
[](https://github.com/Seddryck/Schemathief/search?l=C%23)
## Installing
### Install as a .NET global tool
A .NET global tool is a console application that you can install and run from any directory on your machine. Here’s a guide on how to perform a global installation of a .NET tool:
#### Prerequisites
Before installing a .NET global tool, you must have the .NET SDK installed on your machine. You can check if it's installed by running the following command in your terminal or Command Prompt:
```bash
dotnet --version
```
If .NET is not installed, download it from [Microsoft's official website](https://dotnet.microsoft.com/download/dotnet).
#### Install a .NET Global Tool
To install a .NET global tool, you use the dotnet tool install command. This command installs a tool for all users globally on your system.
```bash
dotnet tool install -g Schemathief-cli
```
`-g`: This flag tells the dotnet command to install the tool globally.
#### Verify Installation
After installing the tool, you can verify that it's available globally by running it from any directory.
```bash
schemathief --version
```
This command will display the installed tool’s version if the installation was successful.
#### Update a .NET Global Tool
To update a globally installed .NET tool, use the dotnet tool update command:
```bash
dotnet tool update -g Schemathief-cli
```
## Quickstart
### `delta` Command – Generate a JSON Schema Delta
Generates a **delta JSON Schema** from a .NET type by comparing it against a base schema. This is useful when evolving data models incrementally, and you want to isolate new or changed fields.
#### Usage
```bash
schemathief delta --assembly --class --base [--exclude ] [--output ]
```
You can also use short options:
```bash
schemathief delta -a MyLib.dll -c My.Namespace.Type -b https://schemas/base.json -x Id|Timestamp -o delta.json
```
#### Options
| Option | Aliases | Required | Description |
|-------------------|------------------|----------|-------------|
| `--assembly` | `-a` | ✅ Yes | Path to the compiled `.dll` file containing the class. |
| `--class` | `-c` | ✅ Yes | Fully qualified name of the target .NET class (e.g. `MyApp.Models.Customer`). |
| `--base` | `-b` | ✅ Yes | URL or file path to the base JSON Schema you want to extend. |
| `--exclude` | `-x` | No | Pipe-separated list of properties to ignore in the delta (e.g. `Id|Timestamp`). |
| `--output` | `-o` | No | File path to write the generated delta schema. If omitted, output is written to the console. |
#### Examples
##### Output to console:
```bash
schemathief delta -a bin/Release/MyApi.dll -c MyApi.Models.Person -b https://schemas.example.com/person.base.json
```
##### Output to file with exclusions:
```bash
schemathief delta -a MyApi.dll -c MyApi.Models.Invoice -b base-schema.json -x "CreatedAt|Id" -o invoice.delta.schema.json
```
##### Notes
- If the generated delta schema is empty (i.e. all properties are already in the base schema or excluded), the CLI will emit:
```
No delta schema generated.
```
- The delta is combined with the base using an `allOf` JSON Schema construct.