diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 29da2850..bb5e8d39 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,7 +2,7 @@ If you are patching a security vulnerability, please do not submit a pull request. Instead, follow the guidelines described in our [security policy](../blob/main/SECURITY.md). -If you are submitting a bug fix for an an error or fixing an incompatibility +If you are submitting a bug fix for an error or fixing an incompatibility with the [official JSON5 specification][spec], please continue. If you are submitting a feature request or code improvement that is compatible diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d04cf06..5756a4c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -322,7 +322,7 @@ This release tightens JSON5 support and adds helpful utility features: This was the first implementation of this JSON5 parser. - Support unquoted object keys, including reserved words. Unicode characters - and escape sequences sequences aren't yet supported. + and escape sequences aren't yet supported. - Support single-quoted strings. diff --git a/README.md b/README.md index 00ee7939..89524bc7 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,12 @@ and has been adopted by major projects like [WebStorm](https://www.jetbrains.com/help/webstorm/json.html), and [more](https://github.com/json5/json5/wiki/In-the-Wild)**. It's also natively supported on **[Apple platforms](https://developer.apple.com/documentation/foundation/jsondecoder/3766916-allowsjson5)** -like **MacOS** and **iOS**. +like **macOS** and **iOS**. Formally, the **[JSON5 Data Interchange Format](https://spec.json5.org/)** is a superset of JSON (so valid JSON files will always be valid JSON5 files) that expands its syntax to include some productions from [ECMAScript 5.1] (ES5). -It's also a strict _subset_ of ES5, so valid JSON5 files will always be valid ES5. +It's also a _subset_ of ES5, so valid JSON5 files will always be valid ES5.[*](#ecmascript-compatibility) This JavaScript library is a reference implementation for JSON5 parsing and serialization, and is directly used in many of the popular projects mentioned above @@ -239,7 +239,7 @@ please submit an issue to the official **[_specification_ repository](https://github.com/json5/json5-spec)**. Note that we will never add any features that make JSON5 incompatible with ES5; -that compatibility is a fundamental premise of JSON5. +that compatibility is a fundamental premise of JSON5.[*](#ecmascript-compatibility) To report bugs or request features regarding this **JavaScript implementation** of JSON5, please submit an issue to **_this_ repository**. @@ -248,6 +248,14 @@ of JSON5, please submit an issue to **_this_ repository**. To report a security vulnerability, please follow the follow the guidelines described in our [security policy](./SECURITY.md). +## ECMAScript Compatibility +While JSON5 aims to be fully compatible with ES5, there is one exception where +both JSON and JSON5 are not. Both JSON and JSON5 allow unescaped line and +paragraph separator characters (U+2028 and U+2029) in strings, however ES5 does +not. A [proposal](https://github.com/tc39/proposal-json-superset) to allow these +characters in strings was adopted into ES2019, making JSON and JSON5 fully +compatible with ES2019. + ## License MIT. See [LICENSE.md](./LICENSE.md) for details.