Add JSON schemas for pyrefly.toml and pyproject.toml validation #2100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed

Prathamesh-tech-eng wants to merge 8 commits into facebook:main from Prathamesh-tech-eng:main

.gitignore

-Original file line number
+Diff line change
@@ -1,3 +1,14 @@
     debug.json
     debug.js
     target/
+    # Ignore all files in schemas/ except specific JSON schemas and supporting files
+    schemas/*
+    !schemas/pyproject-tool-pyrefly.json
+    !schemas/pyrefly.json
+    !schemas/validate_schemas.py
+    !schemas/test-pyrefly.toml
+    !schemas/test-pyproject.toml
+    !schemas/README.md
+    !schemas/CONTRIBUTING.md
+    !schemas/SCHEMASTORE.md

schemas/CONTRIBUTING.md

-Original file line number
+Diff line change
@@ -0,0 +1,173 @@
+    # Contributing to Pyrefly Schemas
+    Thank you for your interest in improving Pyrefly's JSON Schema definitions!
+    ## Overview
+    The schemas in this directory provide validation, autocomplete, and documentation for Pyrefly configuration files. When updating the schemas, it's important to keep them in sync with the actual configuration implementation.
+    ## Schema Files
+    - **pyrefly.json**: Schema for standalone `pyrefly.toml` files
+    - **pyproject-tool-pyrefly.json**: Schema for the `[tool.pyrefly]` section in `pyproject.toml`
+    Both schemas should have identical configuration options, just wrapped differently.
+    ## When to Update Schemas
+    Update the schemas whenever:
+. **New configuration options are added** to Pyrefly
+. **Configuration options are modified** (renamed, type changed, etc.)
+. **Configuration options are deprecated or removed**
+. **Default values change**
+. **Enum values are added or removed**
+    ## How to Update Schemas
+    ### 1. Check the Source of Truth
+    The authoritative source for configuration options is:
+    - `crates/pyrefly_config/src/config.rs` - Main config structure
+    - `crates/pyrefly_config/src/base.rs` - Base config options
+    - `website/docs/configuration.mdx` - User-facing documentation
+    Always verify your changes against these sources.
+    ### 2. Update Both Schema Files
+    When adding a new configuration option, update both:
+    - `pyrefly.json` at the top level
+    - `pyproject-tool-pyrefly.json` under `properties.tool.properties.pyrefly.properties`
+    Ensure the option definitions are identical.
+    ### 3. Follow JSON Schema Best Practices
+    - **Use descriptive descriptions**: Each property should have a clear description
+    - **Set appropriate types**: Use `string`, `boolean`, `array`, `object`, etc.
+    - **Add default values**: Include the actual default value from the Rust code
+    - **Use enums for fixed values**: For options like `python-platform` or `untyped-def-behavior`
+    - **Add patterns for validation**: For example, version strings should match `^\d+(\.\d+)?(\.\d+)?$`
+    - **Mark required properties**: Use `required` array for mandatory fields
+    ### 4. Add Test Cases
+    Add examples of the new configuration option to the test files:
+    - `test-pyrefly.toml` - Examples for `pyrefly.toml`
+    - `test-pyproject.toml` - Examples for `pyproject.toml`
+    ### 5. Validate Your Changes
+    Run the validation script to ensure the schemas are correct:
+    ```bash
+    python schemas/validate_schemas.py
+    ```
+    This script validates the test configuration files against the schemas.
+    ### 6. Update Documentation
+    If you're adding a new configuration option, also update:
+    - `schemas/README.md` - If the change affects how users interact with schemas
+    - `website/docs/configuration.mdx` - User-facing documentation (if not already done)
+    ## Schema Structure
+    ### Common Properties Format
+    ```json
+    "property-name": {
+      "description": "Clear description of what this does",
+      "type": "string|boolean|array|object|number",
+      "default": <default-value>,
+      "enum": ["value1", "value2"],  // For fixed set of values
+      "pattern": "regex",            // For string validation
+      "items": {...},                // For array element types
+      "properties": {...}            // For object properties
+    }
+    ```
+    ### Naming Conventions
+    - Use kebab-case for property names: `python-version`, not `python_version`
+    - Match the exact names used in the TOML configuration
+    - For deprecated options, add a note in the description
+    ### Example: Adding a New Boolean Option
+    ```json
+    "new-option-name": {
+      "description": "Whether to enable the new feature. Default is false.",
+      "type": "boolean",
+      "default": false
+    }
+    ```
+    ### Example: Adding a New Enum Option
+    ```json
+    "new-mode": {
+      "description": "The mode to use for the new feature.",
+      "type": "string",
+      "enum": ["strict", "lenient", "off"],
+      "default": "lenient"
+    }
+    ```
+    ### Example: Adding a New Array Option
+    ```json
+    "new-patterns": {
+      "description": "List of glob patterns for the new feature.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    }
+    ```
+    ## Testing
+    ### Manual Testing
+. Create a test configuration file with the new option
+. Open it in VS Code with the "Even Better TOML" extension
+. Verify that:
+       - Autocomplete suggests the new option
+       - Hover shows the correct description
+       - Invalid values are highlighted
+       - Default value is documented
+    ### Automated Testing
+    The `validate_schemas.py` script validates test files against schemas:
+    ```bash
+    # Install dependencies (if not already installed)
+    pip install jsonschema toml
+    # Run validation
+    python schemas/validate_schemas.py
+    ```
+    Add test cases to `test-pyrefly.toml` and `test-pyproject.toml` that exercise your new configuration option.
+    ## Submitting Changes
+. **Create a branch**: `git checkout -b update-schema-<feature-name>`
+. **Make your changes**: Update both schema files
+. **Add tests**: Update test configuration files
+. **Validate**: Run `python schemas/validate_schemas.py`
+. **Format**: Ensure JSON files are properly formatted (2-space indentation)
+. **Commit**: Write a clear commit message explaining the change
+. **Submit PR**: Create a pull request with a description of what was added/changed
+    ## Questions?
+    If you have questions about updating the schemas:
+    - Check existing schema definitions for similar patterns
+    - Review the [JSON Schema documentation](https://json-schema.org/)
+    - Open an issue or ask on [Discord](https://discord.com/invite/Cf7mFQtW7W)

schemas/README.md

-Original file line number
+Diff line change
@@ -0,0 +1,93 @@
+    # Pyrefly JSON Schemas
+    This directory contains JSON Schema definitions for Pyrefly configuration files.
+    ## Available Schemas
+    ### pyrefly.json
+    JSON Schema for `pyrefly.toml` configuration files. This schema provides validation, autocomplete, and documentation for all Pyrefly configuration options when editing `pyrefly.toml` files.
+    **Schema URL:** `https://pyrefly.org/schemas/pyrefly.json`
+    ### pyproject-tool-pyrefly.json
+    JSON Schema for the `[tool.pyrefly]` section in `pyproject.toml` files. This schema provides the same validation and autocomplete features as the pyrefly.json schema, but formatted for use within pyproject.toml files.
+    **Schema URL:** `https://pyrefly.org/schemas/pyproject-tool-pyrefly.json`
+    ## Editor Integration
+    ### VS Code
+    VS Code will automatically detect and use these schemas when you have the appropriate extensions installed:
+. **For pyrefly.toml files:**
+       - Install the "Even Better TOML" extension
+       - Add the following to your `settings.json`:
+       ```json
+       {
+         "evenBetterToml.schema.associations": {
+           "pyrefly.toml": "https://pyrefly.org/schemas/pyrefly.json"
+         }
+       }
+       ```
+. **For pyproject.toml files:**
+       - The "Even Better TOML" extension automatically supports `[tool.pyrefly]` sections
+       - No additional configuration needed
+    ### PyCharm / IntelliJ
+    PyCharm automatically recognizes TOML schemas. You can configure schema mappings in:
+    - Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings
+    ### Other Editors
+    Most modern editors with TOML support can use JSON Schemas. Consult your editor's documentation for configuring custom schema mappings.
+    ## Using Schemas Locally
+    During development, you can reference the local schema files:
+    **For pyrefly.toml:**
+    Add a comment at the top of your `pyrefly.toml`:
+    ```toml
+    # yaml-language-server: $schema=./schemas/pyrefly.json
+    ```
+    **For pyproject.toml:**
+    Add a comment in the `[tool.pyrefly]` section:
+    ```toml
+    [tool.pyrefly]
+    # yaml-language-server: $schema=./schemas/pyproject-tool-pyrefly.json
+    ```
+    ## Schema Features
+    The schemas provide:
+    - **Validation**: Ensures your configuration follows the correct structure and types
+    - **Autocomplete**: Suggests available configuration options as you type
+    - **Documentation**: Shows descriptions and default values for each configuration option
+    - **Type Checking**: Validates that values match expected types (strings, arrays, booleans, etc.)
+    - **Enum Validation**: Ensures enum values (like `python-platform` or `untyped-def-behavior`) are valid
+    ## Contributing to Schemas
+    When adding new configuration options to Pyrefly:
+. Update the schema files in this directory
+. Ensure the schema matches the actual config structure in `crates/pyrefly_config/`
+. Update the configuration documentation in `website/docs/configuration.mdx`
+. Test the schema with sample configs
+    ## Submitting to SchemaStore
+    These schemas can be submitted to [SchemaStore](https://github.com/SchemaStore/schemastore) to provide automatic validation in all compatible editors without manual configuration.
+    To submit:
+. Fork the SchemaStore repository
+. Add the schema files to the `src/schemas/json/` directory
+. Update the `src/api/json/catalog.json` to register the schemas
+. Submit a pull request
+    For more information, see the [SchemaStore contribution guide](https://github.com/SchemaStore/schemastore/blob/master/CONTRIBUTING.md).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add JSON schemas for pyrefly.toml and pyproject.toml validation #2100

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!