Atlantis Schema Inspector: The Complete Guide for DevelopersAtlantis Schema Inspector is a developer-focused tool designed to simplify the work of validating, inspecting, and improving JSON/GraphQL/OpenAPI schemas used by modern applications. This guide covers what the inspector does, why it matters, how to integrate it in real projects, practical workflows, advanced features, and best practices for maintaining reliable schemas over time.
What is Atlantis Schema Inspector?
Atlantis Schema Inspector is a schema validation and analysis tool that helps developers find inconsistencies, potential breaking changes, and inefficiencies in API and data schemas. It supports common schema formats (JSON Schema, OpenAPI/Swagger, GraphQL SDL) and provides automated checks, human-readable reports, and suggestions for fixes.
Key capabilities:
- Schema validation against specification rules.
- Detection of breaking changes and compatibility issues.
- Linting rules tailored to best practices.
- Visualization of schema structure and relationships.
- Integration with CI/CD pipelines and developer workflows.
Why use a schema inspector?
Modern applications rely heavily on well-defined schemas for data exchange, contract testing, client generation, and documentation. Problems in schemas can cause runtime errors, production outages, poor developer experience, or subtle data corruption.
Benefits:
- Catch errors early — find mismatches before they reach production.
- Improve interoperability — ensure clients and services share the same expectations.
- Streamline onboarding — clearer schemas make it faster to understand APIs.
- Reduce technical debt — detect deprecated fields, inconsistent naming, and duplication.
Supported schema formats
Atlantis Schema Inspector typically supports:
- JSON Schema (Draft-07, 2019-09, 2020-12 depending on version)
- OpenAPI / Swagger (v2 and v3)
- GraphQL SDL and introspection results
- Protobuf and Avro (via plugins or adapters in some setups)
Check your Atlantis version for exact format support and plugin availability.
Core features and what they do
- Validation engine: verifies schema syntax and structural correctness.
- Linter: enforces style and best-practice rules (naming conventions, required descriptions, avoiding additionalProperties where inappropriate, etc.).
- Change detector: compares schema versions and flags breaking vs non-breaking changes.
- Type inconsistency checks: finds places where types diverge across references.
- Schema folding and visualization: generates diagrams or navigable trees to see object relationships.
- Auto-fix suggestions: for certain lint rules, offers recommended edits.
- CLI, GUI, and API: use the inspector in automated pipelines, locally, or through a web interface.
- Reporting: machine-readable (JSON) and human-readable (HTML, markdown) reports for PRs and CI.
Installation and setup
Below are typical installation paths. Adapt commands to your environment.
CLI install (npm):
npm install -g atlantis-schema-inspector Docker:
docker pull atlantis/schema-inspector:latest docker run --rm -v $(pwd):/workspace atlantis/schema-inspector inspect /workspace/schema.yaml CI example (GitHub Actions):
- name: Run Atlantis Schema Inspector run: atlantis-schema-inspector inspect ./openapi.yaml --output report.html For GraphQL projects you might add a config file (atlantis.config.json) to specify rules, formats, and output preferences.
Basic usage examples
Validate a JSON Schema:
atlantis-schema-inspector validate schema.json Lint an OpenAPI file and produce HTML report:
atlantis-schema-inspector lint openapi.yaml --rules recommended --format html --out report.html Compare two schema versions to detect breaking changes:
atlantis-schema-inspector diff old_schema.json new_schema.json --breaking-only Inspect a GraphQL schema via introspection endpoint:
atlantis-schema-inspector graphql --endpoint https://api.example.com/graphql --output schema-inspection.json Integrating into development workflow
- Pre-commit hooks: run a quick lint/validate step to avoid committing invalid schemas.
- Pull request checks: use the diff and lint features to block PRs that introduce breaking changes.
- CI pipelines: fail builds on critical schema errors, generate reports for teams to review.
- Documentation pipeline: auto-generate API docs and diagrams from validated schemas.
- Contract testing: pair Atlantis output with contract tests to verify runtime conformance.
Example GitHub Actions step for PR validation:
- name: Schema Validation uses: actions/checkout@v3 - name: Run Schema Inspector run: atlantis-schema-inspector lint ./api/openapi.yaml --rules ci --format json --out ./reports/schema.json - name: Upload report uses: actions/upload-artifact@v3 with: name: schema-report path: ./reports/schema.json Common workflows and patterns
-
Local development
- Run quick lint and validation on file save or commit.
- Use auto-fix for trivial issues, then manually review non-trivial suggestions.
-
Team reviews
- Configure CI to attach inspector reports to PRs.
- Add checklist items in PR templates: “Schema inspected” with link to report.
-
Versioned APIs
- Use diff to detect breaking changes across versions.
- Maintain a changelog generated from schema diffs for consumers.
-
Microservices
- Enforce schema contracts in CI to prevent incompatible deployments.
- Share common schema modules and run cross-repo checks.
Advanced features
- Custom rule sets: define organization-specific lint rules (naming, required docs, deprecation policies).
- Plugins: extend support for additional formats (Protobuf), custom visualizers, or integrations.
- Schema normalization: canonicalize references and $ref targets to reduce duplication.
- Dependency graph analysis: reveals how types and endpoints depend on one another.
- Automated migration hints: when a breaking change is detected, suggest a migration path (e.g., new field + deprecation header).
Best practices
- Keep schemas small and modular. Break large schemas into referenced components.
- Version schemas explicitly and follow semantic versioning for public APIs.
- Use descriptive field names and include documentation strings for fields and endpoints.
- Prefer additive changes; use deprecation fields rather than immediate removal.
- Automate validation in CI and require passing reports for merges to protected branches.
- Regularly run dependency-graph checks to find unused or orphaned definitions.
Troubleshooting common issues
- False positives from lint rules: review and tune rule configuration, disable overly strict rules for legacy modules.
- $ref resolution failures: ensure base URIs and relative paths are correct; use the inspector’s –base flag if needed.
- Large schema performance: split into components, run incremental checks, or increase inspector memory limits.
- GraphQL schema mismatch: check introspection endpoint access (auth), and compare client vs server schemas with the diff tool.
Example: CI pipeline that blocks breaking changes
- Run inspector diff between main branch schema and PR branch schema.
- If breaking changes found, fail the job and post a report to the PR.
- Allow exceptions through a documented process (e.g., API deprecation plan) but require explicit approvals.
This approach prevents accidental breaking changes reaching consumers and creates a transparent history of schema evolution.
Security and privacy considerations
- Treat schemas as sensitive when they contain internal endpoint structure or PII field definitions.
- Limit who can approve breaking changes and require reviews for public APIs.
- For remote introspection, ensure authentication tokens are handled securely in CI secrets and not logged.
Conclusion
Atlantis Schema Inspector streamlines schema quality assurance for teams building APIs and data-driven applications. By validating schemas early, enforcing best practices, and detecting breaking changes automatically, it reduces runtime errors and improves developer velocity. Integrate it into local development, CI, and release processes to maintain robust, consistent schema contracts across your systems.
If you want, I can produce: sample atlantis.config.json for your project, CI snippets tailored to GitHub/GitLab, or a checklist for reviewing schema diffs. Which would you like?
Leave a Reply