From ab51cfd9b901dc5a42750d30fe05956b6e86573a Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Mon, 28 Nov 2022 15:21:13 +1100 Subject: [PATCH 1/2] Add contributed custom scalars announcement blog --- src/content/blog/2022-11-28-custom-scalars.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 src/content/blog/2022-11-28-custom-scalars.md diff --git a/src/content/blog/2022-11-28-custom-scalars.md b/src/content/blog/2022-11-28-custom-scalars.md new file mode 100644 index 0000000000..ece9a7b3aa --- /dev/null +++ b/src/content/blog/2022-11-28-custom-scalars.md @@ -0,0 +1,44 @@ +--- +title: GraphQL Custom Scalar specifications +tags: ["announcements"] +layout: blog +date: 2022-11-28 +byline: Andreas Marek, Donna Zhou +permalink: /blog/2022-11-28-custom-scalars +--- + +# Announcing contributed GraphQL custom scalar specifications + +We are very happy to announce the official home for contributed GraphQL [custom scalar](https://spec.graphql.org/draft/#sec-Scalars.Custom-Scalars) specifications at [scalars.graphql.org](https://scalars.graphql.org/). + +You are welcome to [contribute](https://scalars.graphql.org/new-scalar) custom scalar specifications. Once your specification is merged in, it will be hosted at `scalars.graphql.org//`. + +Our first contributed specification is for [DateTime](https://scalars.graphql.org/andimarek/date-time). You can point users to the specification's URL with the built-in `@specifiedBy` [directive](https://spec.graphql.org/draft/#sec--specifiedBy) in your GraphQL schema. + +```graphql +scalar DateTime @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time") +``` + +## Why we need custom scalar specifications +We were inspired to start this project after an incident at work caused by a difference in `DateTime` implementations in two GraphQL services. The problem was a difference in how many digits were used to represent a fraction of a second. This incident highlighted a flaw in the often cited [RFC-3339 specification](https://www.ietf.org/rfc/rfc3339.txt), which does not explicitly state the number of digits to be used to represent a fraction of a second. + +To prevent such incidents in the future, we created a [refined version](https://scalars.graphql.org/andimarek/date-time) of the RFC-3339 specification, so that `DateTime` scalars can be consistently implemented in any GraphQL service. We thought others might be interested in our `DateTime` specification too, so we created a [repository](https://github.com/graphql/graphql-scalars) to share custom scalar specifications. + +We wanted to make documentation easy and use the built-in `@specifiedBy` directive to reference specifications. We have set up a public and official GraphQL Foundation-owned domain to host specifications. Your contributed specifications will be published at `scalars.graphql.org//`. + +You can reference specifications inside a schema +```graphql +scalar DateTime @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time") +``` + +And you can reference specifications inside custom scalar implementations, for example in the `graphql-java-extended-scalars` [DateTime scalar](https://github.com/graphql-java/graphql-java-extended-scalars/blob/master/src/main/java/graphql/scalars/datetime/DateTimeScalar.java#L113). + +## How to contribute custom scalar specifications +See the [contribution guide](https://scalars.graphql.org/new-scalar) and the [implementation guide](https://scalars.graphql.org/guide). We have included a [general template](https://scalars.graphql.org/template) and a more [simplified template for String-based scalars](https://scalars.graphql.org/template-string). + +Open a pull request on the [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars) to add your custom scalar specification. Once merged, your specification will be hosted at `scalars.graphql.org//`. + +## Get involved! +If you have any comments or questions, please open an issue on the [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars). + +We hope to avoid incidents in the future by making it easier to document, standardize, and share custom scalar specifications. We are looking forward to seeing your custom scalar specifications! From 090bdc48dc3041a279a3d9d414c512f93806972e Mon Sep 17 00:00:00 2001 From: hwillson Date: Thu, 1 Dec 2022 20:33:19 -0500 Subject: [PATCH 2/2] Adjust file date; slight grammar tweak --- ...stom-scalars.md => 2022-12-01-custom-scalars.md} | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) rename src/content/blog/{2022-11-28-custom-scalars.md => 2022-12-01-custom-scalars.md} (86%) diff --git a/src/content/blog/2022-11-28-custom-scalars.md b/src/content/blog/2022-12-01-custom-scalars.md similarity index 86% rename from src/content/blog/2022-11-28-custom-scalars.md rename to src/content/blog/2022-12-01-custom-scalars.md index ece9a7b3aa..517b6c3bb2 100644 --- a/src/content/blog/2022-11-28-custom-scalars.md +++ b/src/content/blog/2022-12-01-custom-scalars.md @@ -2,9 +2,9 @@ title: GraphQL Custom Scalar specifications tags: ["announcements"] layout: blog -date: 2022-11-28 +date: 2022-12-01 byline: Andreas Marek, Donna Zhou -permalink: /blog/2022-11-28-custom-scalars +permalink: /blog/2022-12-01-custom-scalars --- # Announcing contributed GraphQL custom scalar specifications @@ -22,16 +22,17 @@ scalar DateTime @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-ti ## Why we need custom scalar specifications We were inspired to start this project after an incident at work caused by a difference in `DateTime` implementations in two GraphQL services. The problem was a difference in how many digits were used to represent a fraction of a second. This incident highlighted a flaw in the often cited [RFC-3339 specification](https://www.ietf.org/rfc/rfc3339.txt), which does not explicitly state the number of digits to be used to represent a fraction of a second. -To prevent such incidents in the future, we created a [refined version](https://scalars.graphql.org/andimarek/date-time) of the RFC-3339 specification, so that `DateTime` scalars can be consistently implemented in any GraphQL service. We thought others might be interested in our `DateTime` specification too, so we created a [repository](https://github.com/graphql/graphql-scalars) to share custom scalar specifications. +To prevent such incidents in the future, we created a [refined version](https://scalars.graphql.org/andimarek/date-time) of the RFC-3339 specification, so that `DateTime` scalars can be consistently implemented in any GraphQL service. We thought others might be interested in our `DateTime` specification too, so we created a [repository](https://github.com/graphql/graphql-scalars) to share custom scalar specifications. -We wanted to make documentation easy and use the built-in `@specifiedBy` directive to reference specifications. We have set up a public and official GraphQL Foundation-owned domain to host specifications. Your contributed specifications will be published at `scalars.graphql.org//`. +We wanted to make documentation easy and use the built-in `@specifiedBy` directive to reference specifications. We have set up a public and official GraphQL Foundation-owned domain to host specifications. Your contributed specifications will be published at `scalars.graphql.org//`. + +You can reference specifications inside a schema as follows: -You can reference specifications inside a schema ```graphql scalar DateTime @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time") ``` -And you can reference specifications inside custom scalar implementations, for example in the `graphql-java-extended-scalars` [DateTime scalar](https://github.com/graphql-java/graphql-java-extended-scalars/blob/master/src/main/java/graphql/scalars/datetime/DateTimeScalar.java#L113). +You can also reference specifications inside custom scalar implementations, for example in the `graphql-java-extended-scalars` [DateTime scalar](https://github.com/graphql-java/graphql-java-extended-scalars/blob/master/src/main/java/graphql/scalars/datetime/DateTimeScalar.java#L113). ## How to contribute custom scalar specifications See the [contribution guide](https://scalars.graphql.org/new-scalar) and the [implementation guide](https://scalars.graphql.org/guide). We have included a [general template](https://scalars.graphql.org/template) and a more [simplified template for String-based scalars](https://scalars.graphql.org/template-string).