{"id":20802968,"url":"https://github.com/sv-tools/roas","last_synced_at":"2026-05-26T00:03:01.424Z","repository":{"id":201095762,"uuid":"699556146","full_name":"sv-tools/roas","owner":"sv-tools","description":"Rust OpenAPI Specification (v2, v3.0, v3.1)","archived":false,"fork":false,"pushed_at":"2025-04-30T19:03:01.000Z","size":245,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-30T19:36:26.993Z","etag":null,"topics":["openapi","openapi3","openapi31","rust","swagger"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sv-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-02T21:40:47.000Z","updated_at":"2025-04-30T19:01:53.000Z","dependencies_parsed_at":"2023-11-06T03:32:15.143Z","dependency_job_id":"141573a5-a72d-4aa0-92c0-b0c8be61e8a4","html_url":"https://github.com/sv-tools/roas","commit_stats":null,"previous_names":["sv-tools/roas"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sv-tools%2Froas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sv-tools%2Froas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sv-tools%2Froas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sv-tools%2Froas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sv-tools","download_url":"https://codeload.github.com/sv-tools/roas/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252794295,"owners_count":21805174,"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":["openapi","openapi3","openapi31","rust","swagger"],"created_at":"2024-11-17T18:39:30.078Z","updated_at":"2026-05-26T00:03:01.398Z","avatar_url":"https://github.com/sv-tools.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# roas\n\n`roas` is a Rust **SDK and command-line tool** for the OpenAPI Specification:\nparse, validate, convert, and round-trip OpenAPI / Swagger documents from\nRust code *or* from the shell. Every released OpenAPI version is supported:\nv2.0 (Swagger), v3.0.x, v3.1.x, and v3.2.x.\n\n## Use it as a CLI\n\n[`roas-cli`](crates/roas-cli) ships a `roas` binary with `validate`,\n`convert`, and `preview` subcommands. Install via Cargo, Homebrew, or\nDocker — pick whichever fits the host:\n\n```shell\ncargo install roas-cli                                                # any platform with a Rust toolchain\nbrew install sv-tools/apps/roas                                       # macOS arm64, Linux\ndocker run --rm -v \"$PWD:/specs\" -w /specs ghcr.io/sv-tools/roas:latest validate openapi.yaml\n```\n\nSee the [`roas-cli` README](crates/roas-cli/README.md) for the full\nsubcommand reference, piping examples, and the live-reload preview server.\n\n## Use it as a Rust SDK\n\n- **Parsers and serialisers** — deserialise OpenAPI documents from JSON or YAML\n  into strongly-typed Rust structs (one type tree per spec version) and\n  serialise them back with full round-trip fidelity.\n- **Description validators** — validate that an OpenAPI description conforms\n  to its specification version: required fields, `$ref` resolution, tag /\n  `operationId` uniqueness, unused-component detection, and more. Each check\n  is independently togglable via the `validation::Options` enum.\n- **Schema validators** — every `Schema Object` (the JSON Schema dialect for\n  the matching OAS version) is structurally validated, including `$ref`\n  resolution, discriminator / mapping correctness, and the per-keyword rules\n  the spec mandates. The schema validator is exercised as part of the larger\n  description validator, and also reusable on its own.\n- **Version converters** — upconvert OpenAPI descriptions across major\n  versions: v2.0 → v3.0.x → v3.1.x → v3.2.x. A chain of `From\u003cv_X::Spec\u003e for\n  v_Y::Spec` migrations performs the conversion in pure Rust; the same\n  converters are exposed as a CLI sub-command via [`roas-cli`](crates/roas-cli).\n- **Pluggable loader** — `ResourceFetcher` / `AsyncResourceFetcher` traits\n  for resolving external `$ref`s, with first-party fetcher crates for\n  [filesystem](crates/roas-file-fetcher) and [HTTP](crates/roas-http-fetcher)\n  sources (JSON or YAML bodies, optional async).\n\n## Crates\n\n| Crate                                           | Docs                                                                                         | crates.io                                                                                                         |\n|-------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|\n| [`roas`](crates/roas)                           | [![docs.rs](https://docs.rs/roas/badge.svg)](https://docs.rs/roas)                           | [![crates.io](https://img.shields.io/crates/v/roas.svg)](https://crates.io/crates/roas)                           |\n| [`roas-file-fetcher`](crates/roas-file-fetcher) | [![docs.rs](https://docs.rs/roas-file-fetcher/badge.svg)](https://docs.rs/roas-file-fetcher) | [![crates.io](https://img.shields.io/crates/v/roas-file-fetcher.svg)](https://crates.io/crates/roas-file-fetcher) |\n| [`roas-http-fetcher`](crates/roas-http-fetcher) | [![docs.rs](https://docs.rs/roas-http-fetcher/badge.svg)](https://docs.rs/roas-http-fetcher) | [![crates.io](https://img.shields.io/crates/v/roas-http-fetcher.svg)](https://crates.io/crates/roas-http-fetcher) |\n| [`roas-cli`](crates/roas-cli)                   | —                                                                                            | [![crates.io](https://img.shields.io/crates/v/roas-cli.svg)](https://crates.io/crates/roas-cli)                   |\n\n## OpenAPI versions\n\n| Spec                                                              | Status                                                                                                                   |\n|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|\n| OpenAPI [v2.0](https://spec.openapis.org/oas/v2.0.html) (Swagger) | parser, description validator, schema validator, converter to v3, documentation rendering via `roas preview`             |\n| OpenAPI [v3.0.x](https://spec.openapis.org/oas/v3.0.4.html)       | parser, description validator, schema validator, converter to v3.1 / v3.2, documentation rendering via `roas preview`    |\n| OpenAPI [v3.1.x](https://spec.openapis.org/oas/v3.1.2.html)       | parser, description validator, schema validator, converter to v3.2, documentation rendering via `roas preview`           |\n| OpenAPI [v3.2.x](https://spec.openapis.org/oas/v3.2.0.html)       | parser, description validator, schema validator, documentation rendering via `roas preview` (target of all upconverters) |\n\nSee each crate's `README.md` for usage examples, and `AGENTS.md` at the\nrepository root for contributor guidelines.\n\n\u003e [!CAUTION]\n\u003e The project is in early development; treat any `0.x.x` version as unstable\n\u003e and subject to breaking changes.\n\n## License\n\nLicensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or\n[MIT license](LICENSE-MIT) at your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsv-tools%2Froas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsv-tools%2Froas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsv-tools%2Froas/lists"}