diff --git a/docs/source/schema.md b/docs/source/schema.md index 245febc..a15dacc 100644 --- a/docs/source/schema.md +++ b/docs/source/schema.md @@ -54,11 +54,14 @@ Contains information that applies to the whole set of charts - string, optional - Relative path to the jacket / album cover / album art to be shown in music select for example. usually a square image. - **BPM** - - number, required + - number or string, required - Song tempo in Beats per Minute. + - Striclty positive + - Strings allowed for easier decimal representation preservation - **offset** - - number, required + - number or string, required - In seconds, opposite of the time position of the first beat in the music file. For instance, if the first beat occurs at 0.15 seconds in the audio file, `offset̀` should be -0.15 + - Strings allowed for easier decimal representation preservation - **preview** - object or string, optional - Contains either a {ref}`preview object ` or a path to a bms-style preview file @@ -76,11 +79,15 @@ Contains information that applies to the whole set of charts Describes the part of the music file that's meant to be played on loop when previewing this song at the music select screen - **start** - - number, required + - number or string, required - In seconds, start of the loop + - Positive + - Strings allowed for easier decimal representation preservation - **duration** - - number, required + - number or string, required - In seconds, duration of the loop + - Strictly positive + - Strings allowed for easier decimal representation preservation (data)= ## Data @@ -165,7 +172,7 @@ A classic note. Ticks are fractions of the beat. The resolution defines how many ticks are in a beat for a given chart. - In other words if the resolution is 420, a tick lasts for 1/420th of a beat + In other words if the resolution is 420, a tick lasts for 1/420th oLike for the BPM, sf a beat For more info about measuring time in ticks, see [bmson's docs](https://bmson-spec.readthedocs.io/en/master/doc/index.html#terminologies) (their docs refers to ticks as *pulses*). - as an array : diff --git a/docs/source/validation.md b/docs/source/validation.md index b59a919..45ad2fe 100644 --- a/docs/source/validation.md +++ b/docs/source/validation.md @@ -103,19 +103,13 @@ Since this is mostly an implicit rule that's not strictly followed by official c ## Decimal values -If possible, non-integer values like `BPM` or `offset` should be manipulated using a [Decimal Data Type](https://en.wikipedia.org/wiki/Decimal_data_type) to preserve their original decimal representation. I think no one likes to see the BPM they defined as a clean `195.3` in the editor be stored as a messy `195.3000030517578125` in the file. +If possible, non-integer values like `BPM` or `offset` should be manipulated using a [Decimal Data Type](https://en.wikipedia.org/wiki/Decimal_data_type) to preserve their original decimal representation. I think no one likes to see the BPM they defined as a clean `195.3` in the editor be stored as a messy `195.3000030517578125` in the file. If doing this is too hard with your language / library of choice, keep in mind that `1.0.0` allows strings instead : -Be careful that the serialized values in the resulting file must still be *number litterals*, not strings. - -- **Good** +- **Valid** ```json { "BPM" : 195.3 } ``` -- **Bad** +- **Valid since 1.0.0** ```json { "BPM": "195.3" } - ``` - -This is not that easy. Python's standard module `json`, for instance, allows *deserializing* (reading) numbers in a json file as `decimal.Decimal` instances, but has no easy way of *serializing* (writing) `decimal.Decimal` instances as a json number litteral that respects the original representation. - -A possible solution is to use the [simplejson](https://pypi.org/project/simplejson/) module as a near drop-in replacement for `json` and use the `use_decimal` options \ No newline at end of file + ``` \ No newline at end of file diff --git a/schema.json b/schema.json index e2285d6..95247a8 100644 --- a/schema.json +++ b/schema.json @@ -30,12 +30,11 @@ }, "BPM": { "description": "Song tempo in Beats per Minute", - "type": "number", - "exclusiveMinimum": 0 + "$ref": "#/$defs/strictlyPositiveDecimal" }, "offset": { "description": "In seconds, opposite of the time position of the first beat in the music file", - "type": "number" + "$ref": "#/$defs/decimal" }, "preview": { "description": "Describes the part of the music file that's to be played on loop when previewing this song", @@ -45,13 +44,11 @@ "properties": { "start": { "description": "In seconds, Time at which preview should start", - "type": "number", - "minimum": 0 + "$ref": "#/$defs/positiveDecimal" }, "duration": { "description": "In seconds, for how long should the preview be played past the starting point", - "type": "number", - "minimum": 0 + "$ref": "#/$defs/strictlyPositiveDecimal" } }, "required": ["start", "duration"] @@ -180,6 +177,40 @@ } } ] + }, + "decimal": { + "description": "a decimal number as either a number literal or a string", + "oneOf": [{ + "type": "number" + }, + { + "type": "string", + "pattern": "^-?\\d+(\\.\\d+)?$" + } + ] + }, + "positiveDecimal": { + "description": "a decimal number as either a number literal or a string", + "oneOf": [{ + "type": "number" + }, + { + "type": "string", + "pattern": "^\\d+(\\.\\d+)?$" + } + ] + }, + "strictlyPositiveDecimal": { + "description": "a strictly positive decimal number as either a number literal or a string", + "oneOf": [{ + "type": "number", + "exclusiveMinimum": 0 + }, + { + "type": "string", + "pattern": "^(0\\.\\d*[1-9]\\d*|\\d*[1-9]\\d*(\\.\\d+)?)$" + } + ] } } } \ No newline at end of file diff --git a/tests/data/02 - polymorphic preview/pass/good object.json b/tests/data/02 - polymorphic preview/pass/good object.json index 8e9ad3e..5a4d123 100644 --- a/tests/data/02 - polymorphic preview/pass/good object.json +++ b/tests/data/02 - polymorphic preview/pass/good object.json @@ -7,7 +7,7 @@ "offset": 0, "preview": { "start": 0, - "duration": 0 + "duration": 1 } }, "data": {} diff --git a/tests/data/06 - decimals as string/fail/negative BPM number.json b/tests/data/06 - decimals as string/fail/negative BPM number.json new file mode 100644 index 0000000..d144056 --- /dev/null +++ b/tests/data/06 - decimals as string/fail/negative BPM number.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": -1, + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/fail/negative BPM string copy.json b/tests/data/06 - decimals as string/fail/negative BPM string copy.json new file mode 100644 index 0000000..ca92578 --- /dev/null +++ b/tests/data/06 - decimals as string/fail/negative BPM string copy.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": "-1", + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/fail/preview object with decimal zero duration.json b/tests/data/06 - decimals as string/fail/preview object with decimal zero duration.json new file mode 100644 index 0000000..ea89e21 --- /dev/null +++ b/tests/data/06 - decimals as string/fail/preview object with decimal zero duration.json @@ -0,0 +1,14 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 1, + "offset": 0, + "preview": { + "start": "0", + "duration": "0.000" + } + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/fail/preview object with negative duration copy.json b/tests/data/06 - decimals as string/fail/preview object with negative duration copy.json new file mode 100644 index 0000000..c614ddd --- /dev/null +++ b/tests/data/06 - decimals as string/fail/preview object with negative duration copy.json @@ -0,0 +1,14 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 1, + "offset": 0, + "preview": { + "start": "0", + "duration": "-10.000" + } + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/fail/preview object with zero duration copy.json b/tests/data/06 - decimals as string/fail/preview object with zero duration copy.json new file mode 100644 index 0000000..a602579 --- /dev/null +++ b/tests/data/06 - decimals as string/fail/preview object with zero duration copy.json @@ -0,0 +1,14 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 1, + "offset": 0, + "preview": { + "start": "0", + "duration": "0" + } + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/fail/zero BPM decimal string.json b/tests/data/06 - decimals as string/fail/zero BPM decimal string.json new file mode 100644 index 0000000..e5f351b --- /dev/null +++ b/tests/data/06 - decimals as string/fail/zero BPM decimal string.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": "0.000", + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/fail/zero BPM number.json b/tests/data/06 - decimals as string/fail/zero BPM number.json new file mode 100644 index 0000000..72a8914 --- /dev/null +++ b/tests/data/06 - decimals as string/fail/zero BPM number.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 0, + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/fail/zero BPM string.json b/tests/data/06 - decimals as string/fail/zero BPM string.json new file mode 100644 index 0000000..ae9f892 --- /dev/null +++ b/tests/data/06 - decimals as string/fail/zero BPM string.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": "0", + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/decimal string BPM 1.json b/tests/data/06 - decimals as string/pass/decimal string BPM 1.json new file mode 100644 index 0000000..aa7ca43 --- /dev/null +++ b/tests/data/06 - decimals as string/pass/decimal string BPM 1.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": "0.1", + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/decimal string BPM 2.json b/tests/data/06 - decimals as string/pass/decimal string BPM 2.json new file mode 100644 index 0000000..4e3ae2d --- /dev/null +++ b/tests/data/06 - decimals as string/pass/decimal string BPM 2.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": "123.456", + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/decimal string offset 1.json b/tests/data/06 - decimals as string/pass/decimal string offset 1.json new file mode 100644 index 0000000..d95f800 --- /dev/null +++ b/tests/data/06 - decimals as string/pass/decimal string offset 1.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 123.456, + "offset": "-0.24" + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/decimal string offset 2.json b/tests/data/06 - decimals as string/pass/decimal string offset 2.json new file mode 100644 index 0000000..e7c0798 --- /dev/null +++ b/tests/data/06 - decimals as string/pass/decimal string offset 2.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 123.456, + "offset": "12.34" + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/integer BPM.json b/tests/data/06 - decimals as string/pass/integer BPM.json new file mode 100644 index 0000000..f31d324 --- /dev/null +++ b/tests/data/06 - decimals as string/pass/integer BPM.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 125, + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/integer string BPM.json b/tests/data/06 - decimals as string/pass/integer string BPM.json new file mode 100644 index 0000000..e0f8fb6 --- /dev/null +++ b/tests/data/06 - decimals as string/pass/integer string BPM.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": "123", + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/number BPM.json b/tests/data/06 - decimals as string/pass/number BPM.json new file mode 100644 index 0000000..2293199 --- /dev/null +++ b/tests/data/06 - decimals as string/pass/number BPM.json @@ -0,0 +1,10 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 123.456, + "offset": 0 + }, + "data": {} +} \ No newline at end of file diff --git a/tests/data/06 - decimals as string/pass/preview object.json b/tests/data/06 - decimals as string/pass/preview object.json new file mode 100644 index 0000000..560b1f2 --- /dev/null +++ b/tests/data/06 - decimals as string/pass/preview object.json @@ -0,0 +1,14 @@ +{ + "version": "1.0.0", + "metadata": { + "title": "", + "artist": "", + "BPM": 1, + "offset": 0, + "preview": { + "start": "8346.9346", + "duration": "35.936" + } + }, + "data": {} +} \ No newline at end of file diff --git a/tests/utils.py b/tests/utils.py index 1bba4bf..338fb02 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -7,7 +7,7 @@ from jschon.jsonschema import Scope from jschon import create_catalog, JSONSchema, JSON import pytest -_catalog = create_catalog('2020-12') +_catalog = create_catalog("2020-12") SCHEMA = JSONSchema.loadf("schema.json", catalog=_catalog) def prettify_path(json_path: str) -> str: