Add a JSON Schema to improve developer experience in VS Code

[amarcadet]

The experience of maintaining large swiftlint configuration files can be tedious, it would be great to add a JSON Schema describing the configuration file allowing VS Code to lint and provide autocomplete.

The Schema could be contributed to https://www.schemastore.org/json/ or manually configured in VS Code settings.json like so:

    "yaml.schemas": {
        "./swiftlint.schema.json": [
            "/.swiftlint.yml",
            "/.swiftlint.yaml",
            "/.swiftlint.*.yml",
            "/.swiftlint.*.yaml"
        ]
    },

I have manually written a partial Schema to test the idea (see below) but I think it would be better to generate it from the code and parameters itself.

Note that thanks to JSON Schema anyOf it is possible to document both implicit and explicit rule configuration (see exemple with rule accessibility_label_for_image below).

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://https://realm.github.io/SwiftLint/swiftlint.schema.json",
  "title": "SwiftLint Configuration",
  "type": "object",
  "properties": {
    "excluded": {
      "type": "array",
      "description": "Case-sensitive paths to ignore during linting. Takes precedence over `included`."
    },
    "included": {
      "type": "array",
      "description": "Case-sensitive paths to include during linting. `--path` is ignored if present."
    },
    "reporter": {
      "enum": [
        "csv",
        "checkstyle",
        "codeclimate",
        "emoji",
        "github-actions-logging",
        "gitlab",
        "html",
        "json",
        "junit",
        "markdown",
        "relative-path",
        "sonarqube",
        "summary",
        "xcode"
      ],
      "description": "Reporter type"
    },
    "strict": {
      "type": "boolean",
      "description": "If true, SwiftLint will treat all warnings as errors."
    },
    "disabled_rules": {
      "type": "array",
      "description": "Disable rules from the default enabled set."
    },
    "opt_in_rules": {
      "type": "array",
      "description": "Enable rules that are not part of the default set. The special `all` identifier will enable all opt in linter rules, except the ones listed in `disabled_rules`."
    },
    "only_rules": {
      "type": "array",
      "description": "Only the rules specified in this list will be enabled. Cannot be specified alongside `disabled_rules` or `opt_in_rules`."
    },
    "accessibility_label_for_image": {
      "anyOf": [
        {
          "allOf": [
            {
              "$ref": "#/$defs/severity"
            },
            {
              "default": false,
              "description": "Images that provide context should have an accessibility label or should be explicitly hidden from accessibility.\nDocumentation: https://realm.github.io/SwiftLint/accessibility_label_for_image.html"
            }
          ]
        },
        {
          "default": false,
          "description": "Images that provide context should have an accessibility label or should be explicitly hidden from accessibility.\nDocumentation: https://realm.github.io/SwiftLint/accessibility_label_for_image.html",
          "properties": {
            "severity": {
              "$ref": "#/$defs/severity"
            }
          }
        }
      ]
    },
    "file_length": {
      "type": "object",
      "description": "Files should not span too many lines.\nDocumentation: https://realm.github.io/SwiftLint/file_length.html",
      "properties": {
        "warning": {
          "type": "integer",
          "default": 400
        },
        "error": {
          "type": "integer",
          "default": 1000
        },
        "ignore_comment_only_lines": {
          "type": "boolean",
          "default": false
        }
      }
    }
  },
  "$defs": {
    "severity": {
      "enum": [
        "warning",
        "error"
      ]
    }
  }
}

[amarcadet]

I have been toying around with the concept here : https://gist.github.com/amarcadet/40bbd809928b64dd54b92c5e2cd87437

I might update it if I find some time to work on it but this first draft illustrates every required concept and also manage to describe :

• only_rules being exclusive with disabled_rules and opt_in_rules
• custom_rules allowing dynamic keys
• accessibility_label_for_image that can define explicit or implicit configuration

With the little experience I got from writing this first draft I don't think it could be generated without adding a lot of annotation, comments and configuration in the existing codebase to use JSON Schema to its full potential.

I will try to update it in the coming days but that's a lot of work and time, I don't know if I be able to keep up so I share it here for anyone interested in contributing.