Add YearMonth #25
Open
Add YearMonth #25
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Contributor
martinbonnin left a comment
martinbonnin left a comment There was a problem hiding this comment.
Apologies for the huuuuuge delay. Left a few comments if you're still around. Let me know what you think!
| | ||
| # Overview | ||
| | ||
| This string-based scalar represents a specific month of a specific year (not just any month) following ISO 8601. |
Contributor
There was a problem hiding this comment.
Like @andimarek is suggesting here, RFC3339 is a more transparent standard:
Suggested change
| This string-based scalar represents a specific month of a specific year (not just any month) following ISO 8601. | |
| This string-based scalar represents a specific month of a specific year (not just any month) following RFC 3339. |
Comment on lines +21 to +28
| | ||
| # Name | ||
| | ||
| `YearMonth`, inspired by [Java](https://docs.oracle.com/javase/8/docs/api/java/time/YearMonth.html) | ||
| | ||
| Or `ISO8601YearMonth`\ | ||
| Or just `Month`?\ | ||
| `ISO8601Month`? |
Contributor
There was a problem hiding this comment.
Let's keep things simple?
Suggested change
| # Name | |
| `YearMonth`, inspired by [Java](https://docs.oracle.com/javase/8/docs/api/java/time/YearMonth.html) | |
| Or `ISO8601YearMonth`\ | |
| Or just `Month`?\ | |
| `ISO8601Month`? | |
| # Recommended name | |
| The recommended name is `YearMonth` |
Comment on lines +30 to +32
| # Result spec | ||
| | ||
| The result must be an ISO 8601 extended format string with just the year and month: “YYYY-MM” |
Contributor
There was a problem hiding this comment.
Suggested change
| # Result spec | |
| The result must be an ISO 8601 extended format string with just the year and month: “YYYY-MM” | |
| # Result coercion | |
| The result must be a string with just the year and month using the “YYYY-MM” pattern. | |
| Using the RFC 3339 description, this is equivalent to: | |
| ``` | |
| year-month = date-fullyear "-" date-month | |
| ``` |
Comment on lines +46 to +56
| | `2024-7` | Zero-padding missing on the month, should be 2024-07 | | ||
| | `24-07` | Truncated representations on year (YY instead of YYYY) are not recommended by ISO and can be confusing | | ||
| | `2024-07-01` | Full date is not expected, precision must only be up to month | | ||
| | `2024-07-01T00:00:00Z` | Full date-time is not expected, precision must only be up to month | | ||
| | `07-2024` | Should be YYYY-MM, not the other way | | ||
| | `2024-00` | Month must be 1-indexed, not 0-indexed: Jan is 01, Dec is 12 | | ||
| | `202407` | Hyphen missing; ISO recommends the “basic format (one without hyphens) should be avoided in plain text” | | ||
| | `2024/07` | Slash instead of hyphen | | ||
| | `2024` | Incomplete - month missing | | ||
| | `2024-Jul` | No strings allowed | | ||
| | `+2024-07` | No prefix (or postfix) symbols or characters allowed | |
Contributor
There was a problem hiding this comment.
Nice counter examples 👍
Comment on lines +58 to +60
| # Input spec | ||
| | ||
| For input, _any valid ISO 8601 string_ is allowed. |
Contributor
There was a problem hiding this comment.
I don't think we want to allow anything that would cause loss of information. I would use the same thing as for result coercion:
Suggested change
| # Input spec | |
| For input, _any valid ISO 8601 string_ is allowed. | |
| # Input coercion | |
| Inputs must be strings using the “YYYY-MM” pattern. | |
| Using the RFC 3339 description, this is equivalent to: |
year-month = date-fullyear "-" date-month
Comment on lines +62 to +75
| ## Valid examples | ||
| | ||
| | String | Explanation | | ||
| | -------- | ------- | | ||
| | `2024-07` | Representing July 2024 | | ||
| | `2024-07-13` | Still representing July 2024 - the implementation can ignore the date as needed | | ||
| | `2024-07-13T16:23:58Z` | Still representing July 2024 - the implementation can ignore everything beyond month as needed | | ||
| | `2024` | Just year is valid ISO and must be treated as January of that year | | ||
| | ||
| ## Invalid examples | ||
| | ||
| | String | Explanation | | ||
| | -------- | ------- | | ||
| | `2024-July` | Invalid ISO | |
Contributor
There was a problem hiding this comment.
Suggested change
| ## Valid examples | |
| | String | Explanation | | |
| | -------- | ------- | | |
| | `2024-07` | Representing July 2024 | | |
| | `2024-07-13` | Still representing July 2024 - the implementation can ignore the date as needed | | |
| | `2024-07-13T16:23:58Z` | Still representing July 2024 - the implementation can ignore everything beyond month as needed | | |
| | `2024` | Just year is valid ISO and must be treated as January of that year | | |
| ## Invalid examples | |
| | String | Explanation | | |
| | -------- | ------- | | |
| | `2024-July` | Invalid ISO | | |
| ## Valid examples | |
| | String | Explanation | | |
| | -------- | ------- | | |
| | `2024-07` | Representing July 2024 | | |
| | `2024-12` | Representing December 2024 | | |
| | `0999-01` | Representing January of the year 999 | | |
| ## Invalid examples | |
| | String | Explanation | | |
| | -------- | ------- | | |
| | `2024-7` | Zero-padding missing on the month, should be 2024-07 | | |
| | `24-07` | Truncated representations on year (YY instead of YYYY) are not recommended by ISO and can be confusing | | |
| | `2024-07-01` | Full date is not expected, precision must only be up to month | | |
| | `2024-07-01T00:00:00Z` | Full date-time is not expected, precision must only be up to month | | |
| | `07-2024` | Should be YYYY-MM, not the other way | | |
| | `2024-00` | Month must be 1-indexed, not 0-indexed: Jan is 01, Dec is 12 | | |
| | `202407` | Hyphen missing; ISO recommends the “basic format (one without hyphens) should be avoided in plain text” | | |
| | `2024/07` | Slash instead of hyphen | | |
| | `2024` | Incomplete - month missing | | |
| | `2024-Jul` | No strings allowed | | |
| | `+2024-07` | No prefix (or postfix) symbols or characters allowed | |
Comment on lines +77 to +79
| # References | ||
| | ||
| - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) |
Contributor
There was a problem hiding this comment.
Suggested change
| # References | |
| - [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) | |
| # References | |
| - [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) |
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.
Adding a month (YearMonth) scalar
"2024-07", "1991-03", etc.