Quick Start with Atlantis Schema Inspector: Installation to InsightsAtlantis Schema Inspector is a tool designed to help teams validate, explore, and understand schema definitions across data pipelines, APIs, and application models. This guide takes you from first installation through practical inspection workflows, showing how to extract meaningful insights from your schemas and integrate the Inspector into a developer or data engineer workflow.
What Atlantis Schema Inspector does (at a glance)
- Validates schema conformance across environments and versions.
- Visualizes relationships between types, fields, and references.
- Reports inconsistencies, missing fields, deprecated elements, and potential breaking changes.
- Integrates with CI/CD, version control, and documentation systems to enforce schema quality over time.
1. Prerequisites
Before installing Atlantis Schema Inspector, make sure you have:
- Node.js 14+ or Python 3.8+ (depending on the distribution you choose).
- Git for cloning repositories and integrating with version control.
- Access to your schema files (JSON Schema, OpenAPI/Swagger, GraphQL SDL, or custom YAML/JSON definitions).
- Optional: Docker if you prefer containerized deployment.
2. Installation
There are three common installation methods: npm/pip, Docker, and from source.
Install via npm (Node distribution)
- Open a terminal.
- Run:
npm install -g atlantis-schema-inspector - Verify:
atlantis-inspector --version
Install via pip (Python distribution)
- Open a terminal.
- Run:
pip install atlantis-schema-inspector - Verify:
atlantis-inspector --version
Run with Docker
- Pull the image:
docker pull atlantis/schema-inspector:latest - Run (example mounting local schemas):
docker run --rm -v $(pwd)/schemas:/schemas atlantis/schema-inspector inspect /schemas
From source (for contributors)
- Clone the repo:
git clone https://github.com/atlantis-labs/schema-inspector.git cd schema-inspector - Follow the repository README for build steps (usually
npm install/make/python setup.py install).
3. Quick configuration
Create a simple config file (atlantis.config.yml) in your project root to point the Inspector at your schema sources and define desired checks:
sources: - type: filesystem path: ./schemas - type: git repo: https://github.com/myorg/api-definitions checks: - name: missing-required-fields - name: deprecated-usage - name: breaking-changes output: format: html path: ./inspector-report Run:
atlantis-inspector run --config atlantis.config.yml 4. Core features and how to use them
Validation
Atlantis Schema Inspector validates schemas against a chosen specification (JSON Schema draft, OpenAPI 3.x, GraphQL rules). Use the validator to catch syntax errors and structural problems early.
Example command:
atlantis-inspector validate ./schemas/openapi.yaml Diffing and breaking-change detection
Compare two schema versions to identify breaking vs. non-breaking changes. Useful in PR checks.
Example:
atlantis-inspector diff old_schema.yaml new_schema.yaml --report breaking-changes Visualization
Generate interactive diagrams showing type relationships and references.
Example:
atlantis-inspector visualize ./schemas --output ./visuals This creates HTML/SVG graphs you can open in a browser.
Reporting
Produce reports in HTML, JSON, or CSV to include in CI artifacts.
Example:
atlantis-inspector run --config atlantis.config.yml --output-format json 5. Integration into CI/CD
Add the Inspector to your CI pipeline to run on pull requests and merges. Example GitHub Actions step:
- name: Run Atlantis Schema Inspector uses: actions/checkout@v3 - name: Install Inspector run: npm install -g atlantis-schema-inspector - name: Inspect Schemas run: atlantis-inspector run --config atlantis.config.yml --output-format json Fail the job if breaking changes are detected:
run: | atlantis-inspector run --config atlantis.config.yml --fail-on breaking 6. Common inspection workflows
- Pre-merge check: Validate and diff schemas in PRs to prevent accidental breaking changes.
- Release audit: Run a full inspection across tagged releases to create a changelog of schema changes.
- Documentation sync: Generate visualization and field-level descriptions to embed in docs sites.
- Data migration planning: Use diff reports to plan migrations when fields are removed or types change.
7. Interpreting the results
- Errors: Immediate issues that prevent correct parsing or violate the schema spec. Must be fixed.
- Warnings: Suspicious patterns or deprecated usages. Review and consider remediation.
- Breaking changes: Additions/removals/alterations that will likely break consumers. Coordinate version bumps or migrations.
- Suggestions: Non-critical improvements (naming, description gaps) for better maintainability.
8. Tips & best practices
- Run the Inspector early and often — catch schema issues before code hits production.
- Version your schemas and store them in source control.
- Use the –fail-on option in CI to enforce standards.
- Combine visualization outputs with documentation generators for clearer API docs.
- Configure checks to match your team’s compatibility guarantees (e.g., allow additive non-breaking changes).
9. Troubleshooting
- Memory/timeouts: Increase container resources or run per-directory scans.
- False positives: Adjust rule thresholds or add rule exceptions in the config.
- Unsupported syntax: Ensure you’re using a supported schema spec/version or open an issue with the project.
10. Next steps and learning resources
- Explore advanced config options (rule tuning, custom rule plugins).
- Integrate with documentation sites (e.g., Docusaurus, MkDocs) to publish visuals.
- Automate release notes from diff reports.
- Contribute custom validators if your organization uses proprietary schema extensions.
Quick-start checklist:
- Install Atlantis Schema Inspector (npm/pip/Docker).
- Create atlantis.config.yml pointing to your schemas.
- Run validation and diff locally.
- Add Inspector to CI to block breaking changes.
- Generate visual reports and integrate into docs.
For specific commands or help tuning checks for your schema format, paste a sample schema and I’ll show exact commands and example outputs.
Leave a Reply