Merge branch 'himkp-master-patch-60592' into 'master'

Add docs for custom schema validation

See merge request gitlab-org/gitlab!42194

doc/user/project/web_ide/index.md

@@ -53,21 +53,42 @@ If you are missing Syntax Highlighting support for any language, we prepared a s
 NOTE: **Note:**
 Single file editing is based on the [Ace Editor](https://ace.c9.io).
 
-### Schema based validation
+### Themes
+
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0.
+> - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1.
+
+All the themes GitLab supports for syntax highlighting are added to the Web IDE's code editor.
+You can pick a theme from your [profile preferences](../../profile/preferences.md).
+
+The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and
+the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228),
+which apply to the entire Web IDE screen.
+
+| Solarized Light Theme                                         | Solarized Dark Theme                                        | Dark Theme                              |
+|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------|
+| ![Solarized Light Theme](img/solarized_light_theme_v13_0.png) | ![Solarized Dark Theme](img/solarized_dark_theme_v13_1.png) | ![Dark Theme](img/dark_theme_v13_0.png) |
+
+## Schema based validation
 
-> - Support for `.gitlab-ci.yml` validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2.
+> - Support for validation based on predefined schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218472) in GitLab 13.2.
 > - It was deployed behind a feature flag, disabled by default.
 > - It's enabled on GitLab.com.
 > - It cannot be enabled or disabled per-project.
-> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-schema-based-validation).
+> - For GitLab self-managed instances, GitLab administrators can opt to [enable it](#enable-or-disable-validation-based-on-predefined-schemas).
+> - Support for validation based on custom schemas [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4.
 
 The Web IDE provides validation support for certain JSON and YAML files using schemas
-based on the [JSON Schema Store](https://www.schemastore.org/json/). This feature is
-only supported for the `.gitlab-ci.yml` file.
+based on the [JSON Schema Store](https://www.schemastore.org/json/). 
 
-#### Enable or disable Schema based validation **(CORE ONLY)**
+### Predefined schemas
 
-Schema based validation is under development and not ready for production use. It is
+The Web IDE has validation for certain files built in. This feature is only supported for
+the `*.gitlab-ci.yml` files.
+
+#### Enable or disable validation based on predefined schemas **(CORE ONLY)**
+
+Validation based on predefined schemas is under development and not ready for production use. It is
 deployed behind a feature flag that is **disabled by default** for self-managed instances,
 [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
 can enable it for your instance.
@@ -84,21 +105,35 @@ To disable it:
 Feature.disable(:schema_linting)
 ```
 
-### Themes
+### Custom schemas **(PREMIUM)**
 
-> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2389) in GitLab in 13.0.
-> - Full Solarized Dark Theme [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/219228) in GitLab 13.1.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/226982) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4.
 
-All the themes GitLab supports for syntax highlighting are added to the Web IDE's code editor.
-You can pick a theme from your [profile preferences](../../profile/preferences.md).
+The Web IDE also allows you to define custom schemas for certain JSON/YAML files in your project.
+You can do so by defining a `schemas` entry in the `.gitlab/.gitlab-webide.yml` file inside the
+repository's root. Here is an example configuration:
 
-The themes are available only in the Web IDE file editor, except for the [dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/209808) and
-the [solarized dark theme](https://gitlab.com/gitlab-org/gitlab/-/issues/219228),
-which apply to the entire Web IDE screen.
+```yaml
+schemas:
+  - uri: https://json.schemastore.org/package
+    match:
+      - package.json
+  - uri: https://somewebsite.com/first/raw/url
+    match:
+      - data/release_posts/unreleased/*.{yml,yaml}
+  - uri: https://somewebsite.com/second/raw/url
+    match:
+      - "*.meta.json"
+```
 
-| Solarized Light Theme                                         | Solarized Dark Theme                                        | Dark Theme                              |
-|---------------------------------------------------------------|-------------------------------------------------------------|-----------------------------------------|
-| ![Solarized Light Theme](img/solarized_light_theme_v13_0.png) | ![Solarized Dark Theme](img/solarized_dark_theme_v13_1.png) | ![Dark Theme](img/dark_theme_v13_0.png) |
+Each schema entry supports two properties:
+
+- `uri`: please provide an absolute URL for the schema definition file here. The schema from this URL
+is loaded when a matching file is open.
+- `match`: a list of matching paths or glob expressions. If a schema matches a particular path pattern,
+it will be applied to that file. Please enclose the pattern in quotes if it begins with an asterisk (`*`),
+it's be applied to that file. If a pattern begins with an asterisk (`*`), enclose it in quotation
+marks. Otherwise, the configuration file is not valid YAML.
 
 ## Configure the Web IDE