{"id":15091329,"url":"https://github.com/up9inc/oas-diff","last_synced_at":"2025-07-05T17:05:42.723Z","repository":{"id":38008956,"uuid":"457402945","full_name":"up9inc/oas-diff","owner":"up9inc","description":"OAS 3.1 Validation and Diff CLI Tool","archived":false,"fork":false,"pushed_at":"2022-06-12T12:29:34.000Z","size":1133,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-12T07:14:26.782Z","etag":null,"topics":["diff","golang","openapi","openapi-spec","openapi-specification","openapi-validation","openapi31"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/up9inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-09T14:54:00.000Z","updated_at":"2024-10-16T17:36:40.000Z","dependencies_parsed_at":"2022-09-12T13:42:34.096Z","dependency_job_id":null,"html_url":"https://github.com/up9inc/oas-diff","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/up9inc/oas-diff","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up9inc%2Foas-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up9inc%2Foas-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up9inc%2Foas-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up9inc%2Foas-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/up9inc","download_url":"https://codeload.github.com/up9inc/oas-diff/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/up9inc%2Foas-diff/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263776297,"owners_count":23509698,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diff","golang","openapi","openapi-spec","openapi-specification","openapi-validation","openapi31"],"created_at":"2024-09-25T10:40:28.134Z","updated_at":"2025-07-05T17:05:42.655Z","avatar_url":"https://github.com/up9inc.png","language":"Go","readme":"[![acceptance tests](https://github.com/up9inc/oas-diff/actions/workflows/acceptance_tests.yml/badge.svg?branch=develop)](https://github.com/up9inc/oas-diff/actions/workflows/acceptance_tests.yml)\n# OAS-DIFF \nOAS 3.1 Validation and Diff Tool\n\n## Dependencies\n- Git\n- Make\n- Go 1.18+\n\n## Build\n- Build\n    ````\n    make build\n    ````\n- Run\n    ````\n    ./build/oasdiff --version\n    ````\n## Options\n- Validate\n    ````\n    --base-file value, --f1 value    path of the base OAS 3.1 file\n    --help, -h                                   show help (default: false)\n   ````\n- Diff\n    ````\n    --base-file value, --f1 value    path of the base OAS 3.1 file\n    --second-file value, --f2 value  path of the second OAS 3.1 file\n    --type-filter value, --tf value  changelog Type filter (create/update/delete)\n    --output-html, --oh              save an html report (default: false)\n    --output-endpoint, --oe          endpoint based changelog output (default: false)\n    --loose, -l                      loosely diff, ignores global case sensitivity for strings comparisons and ignore headers that start with 'x-' and 'user-agent' (default: false)\n    --include-file-path, --ifp       whether or not to include the full file path from the diff changelog (default: false)\n    --ignore-descriptions, --id      whether or not to ignore descriptions when performing the diff (default: false)\n    --ignore-examples, --ie          whether or not to ignore examples when performing the diff (default: false)\n    --help, -h                       show help (default: false)\n    ````\n## Examples\n- Version\n    ````\n    ./build/oasdiff -v\n    ````\n- Available Commands\n    ````\n    ./build/oasdiff\n    ````\n- Validate\n    ````\n    ./build/oasdiff validate --base-file examples/invalid.json\n    ./build/oasdiff validate --f1 examples/invalid.json\n    ````\n- Diff\n    ````\n    ./build/oasdiff diff --base-file examples/simple.json --second-file examples/simple2.json\n    ./build/oasdiff diff --base-file examples/simple.json --second-file examples/simple2.json --loose\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --type-filter create\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --type-filter update\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --type-filter delete\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --ignore-descriptions\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --ignore-examples\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --loose --ignore-descriptions --ignore-examples\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --output-html\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --output-endpoint\n    ./build/oasdiff diff --f1 examples/simple.json --f2 examples/simple2.json --output-endpoint --output-html --type-filter update\n    ````\n\n## Array Identifiers\n Array identifiers are used only for arrays to compare arrays by a matching identifier and not based on order. If an identifiable element is found in both the from and to structures, they will be directly compared\n\n- Servers\n    ````\n    URL         string             `json:\"url,omitempty\" diff:\"url,identifier\"`\n    ````\n- Tags\n    ````\n    Name         string        `json:\"name,omitempty\" diff:\"name,identifier\"`\n    ````\n- Parameters\n    ````\n    Name         string        `json:\"name,omitempty\" diff:\"name,identifier\"`\n    ````\n\n## Changelog Rules\n- Arrays\n    ````\n    CREATE/DELETE -\u003e Always the entire element\n    UPDATE -\u003e Only the property, exception if the property is the identifier\n    ````\n\n## Limitations\n- `openapi` field is not a part of the changelog, we only support OAS version 3.1, so any changes will cause a validation failure\n- `jsonSchemaDialect` field is not a part of the changelog, we only support OAS version 3.1 and it uses `JSON Schema Validation Draft 2020-12`\n- `Specification Extensions` are not supported (TODO)\n- `parameters` array of `Reference Object` are not supported (TODO)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fup9inc%2Foas-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fup9inc%2Foas-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fup9inc%2Foas-diff/lists"}