Contributing to Core Server OpenAPI Specs

January 23, 2026 · View on GitHub

Thank you for contributing to the Calimero Network OpenAPI specifications!

How to Contribute

1. Making Changes

  1. Fork and clone this repository
  2. Create a branch for your changes: 
    git checkout -b update-core-server-api
  3. Make your changes to the relevant OpenAPI spec file
  4. Validate your changes: 
    npm install
npm run validate
  5. Check for breaking changes (if updating existing spec): 
    # Compare against the base branch
git checkout main
npm run validate
git checkout your-branch
bash scripts/check-breaking-changes.sh \
  specs/core-server/openapi.yaml \
  specs/core-server/openapi.yaml

2. Submitting Changes

  1. Commit your changes with a clear message: 
    git commit -m "Add new endpoint for user management"
  2. Push to your fork: 
    git push origin update-core-server-api
  3. Open a Pull Request with:
    • Clear description of changes
    • Reference to related issues
    • Notes on breaking vs. non-breaking changes

3. Breaking Changes

If your changes include breaking changes:

  1. Update the version in the spec's info.version field
    • Major version bump for breaking changes
    • Minor version bump for new features
    • Patch version bump for fixes
  2. Document the breaking changes in the PR description
  3. Ensure all dependent repositories are aware of the changes

4. Validation Requirements

All PRs must pass:

  • ✅ OpenAPI spec validation
  • ✅ No syntax errors
  • ✅ Breaking change detection (if applicable)
  • ✅ CI workflow checks

5. Spec Structure Guidelines

  • Use OpenAPI 3.0+ format
  • Include descriptions for all endpoints and schemas
  • Use tags to organize endpoints
  • Include examples where helpful
  • Follow RESTful conventions
  • Document authentication requirements
  • Include error responses

6. Testing

Before submitting:

# Validate syntax
npm run validate

# Check for common issues
npm run lint

# Test breaking change detection
bash scripts/check-breaking-changes.sh \
  specs/core-server/openapi.yaml \
  specs/core-server/openapi.yaml

Questions?

Open an issue or reach out to the Calimero Network team.