Skip to content

Add YearMonth #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add YearMonth #25

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3725bb4
Add YearMonth scalar
ayushvora10 Jul 26, 2024
c47965f
Tidy
ayushvora10 Jul 26, 2024
e276e54
Merge branch 'main' into main
ayushvora10 Mar 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions scalars/contributed/ayushvora10/year-month.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
<!-- cspell:ignore ayushvora10 -->

# YearMonth — GraphQL Custom Scalar

Author - ayushvora10

Date - 2024-07-27

**License and Copyright**

Copyright © GraphQL contributors. This specification is licensed under
[OWFa 1.0](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0).

# Overview

This string-based scalar represents a specific month of a specific year (not just any month) following ISO 8601.
Copy link
Contributor

@martinbonnin martinbonnin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


The pattern is “YYYY-MM” with “YYYY” representing the year and “MM” the month.

This can be used for records that are monthly in nature. Eg. a monthly sales forecast.

# Name

`YearMonth`, inspired by [Java](https://docs.oracle.com/javase/8/docs/api/java/time/YearMonth.html)

Or `ISO8601YearMonth`\
Or just `Month`?\
`ISO8601Month`?
Comment on lines +21 to +28
Copy link
Contributor

@martinbonnin martinbonnin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`


# Result spec

The result must be an ISO 8601 extended format string with just the year and month: “YYYY-MM”
Comment on lines +30 to +32
Copy link
Contributor

@martinbonnin martinbonnin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
```


## 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 +46 to +56
Copy link
Contributor

@martinbonnin martinbonnin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice counter examples 👍


# Input spec

For input, _any valid ISO 8601 string_ is allowed.
Comment on lines +58 to +60
Copy link
Contributor

@martinbonnin martinbonnin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## 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 |
Comment on lines +62 to +75
Copy link
Contributor

@martinbonnin martinbonnin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 |


# References

- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
Comment on lines +77 to +79
Copy link
Contributor

@martinbonnin martinbonnin Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# References
- [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
# References
- [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)