diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6dfab557b45..5160b6aa9f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,9 +8,10 @@ - [Recommended Extensions](#recommended-extensions) - [Schema Authoring](#schema-authoring) - [Best practices](#best-practices) - - [Avoiding overconstraint](#avoiding-overconstraint) - - [Undocumented Features](#undocumented-features) - - [API Compatibility](#api-compatibility) + - [Avoiding Overconstraint](#avoiding-overconstraint) + - [Undocumented Features](#undocumented-features) + - [API Compatibility](#api-compatibility) + - [Use of `CODEOWNERS` file](#use-of-codeowners-file) - [Troubleshooting](#troubleshooting) - [How-to](#how-to) - [How to add a JSON Schema that's hosted in this repository](#how-to-add-a-json-schema-thats-hosted-in-this-repository) @@ -87,10 +88,8 @@ There is an [unofficial draft-07][draft-07-unofficial-strict] schema that uses J ❌ **Don't forget** add test files. - Always be consistent across your schema: order properties and describe in the one style. -- Always use `title` when property type is an object to enhance editor experience which use - this property to show errors (like VS Code). [Why](./editor-features.md)? - Always use `description`, `type`, `additionalProperties`. - - Always set `additionalProperties` to `false` until documentation permits + - Always set `additionalProperties` to `false` unless documentation permits additional properties explicitly. That tool the JSON schema is created for can be changed in the future to allow wrong extra properties. - Always use `minLength`/`maxLength`/`pattern`/etc for property values. @@ -109,7 +108,7 @@ There is an [unofficial draft-07][draft-07-unofficial-strict] schema that uses J [base-04]: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/base-04.json [draft-07-unofficial-strict]: https://json.schemastore.org/metaschema-draft-07-unofficial-strict.json -#### Avoiding overconstraint +#### Avoiding Overconstraint Sometimes, constraints do more harm than good. For example, [cron strings](http://pubs.opengroup.org/onlinepubs/7908799/xcu/crontab.html) validation regexes. False positives are likely as due to their complexity and abundance of implementations; and, when there is an error, the error message isn't helpful. Such cases can include: @@ -117,7 +116,7 @@ Sometimes, constraints do more harm than good. For example, [cron strings](http: - string-embedded DSLs - SSH URLs, HTTPS URLs, and other complex URIs -### Undocumented Features +#### Undocumented Features The use of undocumented features in schemas is permitted and encouraged. However they must be labeled as such. @@ -151,9 +150,9 @@ However, that is not always possible or correct. Alternatively, use `$comment`: In this case, `{ "tsBuildInfoFile": null }` is not documented. Using a string value is, however. -Note that JSON Schema draft `2019-09` adds support for a `deprecated` field. While this would be the best option, most schemas in this repository are `draft-07` - and as a result, Editors and IDEs may not use it. +Note that JSON Schema draft `2019-09` adds support for a `deprecated` field. While this would be the best option, most schemas in this repository are `draft-07`. As a result, Editors and IDEs may not use it. -### API Compatibility +#### API Compatibility Care must be taken to reduce breaking changes; some include: @@ -175,7 +174,16 @@ Many tools, such as [validate-pyproject](https://github.com/abravalheri/validate validate-pyproject --tool cibuildwheel=https://json.schemastore.org/cibuildwheel.toml#/properties/tool/properties ``` -This means that renames in subschema paths aren't zero-cost. If a rename is necessary, keep the old path and `$ref` where necessary. +This means that renames in subschema paths is a potentially breaking change. If a rename is necessary, it is recommended to keep the old path and `$ref` to the new location, if necessary. + +### Use of `CODEOWNERS` file + +This repository uses the [the code-owner-self-merge](https://github.com/OSS-Docs-Tools/code-owner-self-merge) GitHub action to give project maintainers more control over their schema. It allows for: + +- Mentioning a user when a schema is modified in a PR +- Enabling a user to merge a PR, so long it only modifies files that is "owned" by that user + +See the [CODEOWNERS](.github/CODEOWNERS) file, the [action configuration](.github/workflows/codeowners-merge.yml), and [action documentation](https://github.com/OSS-Docs-Tools/code-owner-self-merge) for more information. ### Troubleshooting diff --git a/editor-features.md b/editor-features.md index a2c7e83818b..b899a645991 100644 --- a/editor-features.md +++ b/editor-features.md @@ -47,24 +47,3 @@ More information [here](https://taplo.tamasfe.dev/configuration/developing-schem - `x-intellij-language-injection` - `x-intellij-html-description` - `x-intellij-enum-metadata` - -## Schema Properties - -### `title` as an expected object type - -Consider the following schema: - -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "properties": { - "first": { - "title": "first", - "type": "object" - } - }, - "title": "schema title" -} -``` - -If integer or another incorrect value is passed to `first`, then `Incorrect type. Expected "first".` error is shown. If `title` for this property is removed, then `Incorrect type. Expected "schema title".` is displayed. **The most nested `title` is used for the error message**.