From ef5bbae44c4ded8d93977033a46f4b757f525be7 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Sat, 14 Jan 2023 13:21:04 +1100 Subject: [PATCH 1/3] Add GraphQL Scalars announcement --- .../blog/2023-01-17-graphql-scalars.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 src/content/blog/2023-01-17-graphql-scalars.md diff --git a/src/content/blog/2023-01-17-graphql-scalars.md b/src/content/blog/2023-01-17-graphql-scalars.md new file mode 100644 index 0000000000..dd46f40616 --- /dev/null +++ b/src/content/blog/2023-01-17-graphql-scalars.md @@ -0,0 +1,39 @@ +--- +title: GraphQL Custom Scalar specifications +tags: ["announcements"] +layout: blog +date: 2023-01-17 +byline: Andreas Marek, Donna Zhou +permalink: /blog/2023-01-17-graphql-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 custom scalar specifications (abbreviated as "specs"). Once your spec is merged in, it will be hosted at `scalars.graphql.org//`. See how to contribute on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide.html). + +Our first contributed spec is for [DateTime](https://scalars.graphql.org/andimarek/date-time). You can point users to the spec'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") +``` + +## Elevating the GraphQL type system with custom scalars +Custom scalars have been part of the GraphQL spec since day one. They have the unique ability to extend the GraphQL type system with custom types. While custom scalars are powerful, they were more like a black box for the consumers of the API. + +Originally, it was very hard for consumers to understand custom scalars as a GraphQL schema did not provide any information apart from its name. For example, it was difficult to understand the exact format of a `DateTime` custom scalar. It was also difficult to know whether the `DateTime` custom scalar in API A was exactly the same as the `DateTime` in API B. + +We added the built-in `@specifiedBy` directive some time ago, which assigns a URL for the spec of a custom scalar. This provides a standard way to document custom scalars. The `@specifiedBy` directive is also introspectable. + +However, we have since learned that this was not enough. The burden of writing a custom scalar specs and hosting them was left for each API itself to solve. + +With the custom scalar spec project, we provide templates for writing custom scalar specs and also host the specs at a GraphQL Foundation owned domain [scalars.graphql.org](https://scalars.graphql.org/). This greatly reduces the effort to clearly document and share your custom scalar specs. + +Our hope is that this enables an ecosystem of clearly documented custom scalars and eliminates the need to reinvent popular ones again and again. Ultimately, a popular enough custom scalar will be practically indistinguishable from the built-in ones and elevate the GraphQL type system. + +## Get involved! +See how to contribute a custom scalar spec on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide.html). + +If you have any comments or questions, please open an issue on the [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars). + \ No newline at end of file From 4a0532591e0836297fefcedcaab670059a30892f Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Sat, 14 Jan 2023 13:30:25 +1100 Subject: [PATCH 2/3] Fix html typo --- src/content/blog/2023-01-17-graphql-scalars.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/content/blog/2023-01-17-graphql-scalars.md b/src/content/blog/2023-01-17-graphql-scalars.md index dd46f40616..ccef8cfbd2 100644 --- a/src/content/blog/2023-01-17-graphql-scalars.md +++ b/src/content/blog/2023-01-17-graphql-scalars.md @@ -11,15 +11,17 @@ permalink: /blog/2023-01-17-graphql-scalars 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 custom scalar specifications (abbreviated as "specs"). Once your spec is merged in, it will be hosted at `scalars.graphql.org//`. See how to contribute on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide.html). +You are welcome to contribute custom scalar specifications (abbreviated as "specs"). Once your spec is merged in, it will be hosted at `scalars.graphql.org//`. See how to contribute on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide). Our first contributed spec is for [DateTime](https://scalars.graphql.org/andimarek/date-time). You can point users to the spec'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") +scalar DateTime + @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time") ``` ## Elevating the GraphQL type system with custom scalars + Custom scalars have been part of the GraphQL spec since day one. They have the unique ability to extend the GraphQL type system with custom types. While custom scalars are powerful, they were more like a black box for the consumers of the API. Originally, it was very hard for consumers to understand custom scalars as a GraphQL schema did not provide any information apart from its name. For example, it was difficult to understand the exact format of a `DateTime` custom scalar. It was also difficult to know whether the `DateTime` custom scalar in API A was exactly the same as the `DateTime` in API B. @@ -33,7 +35,7 @@ With the custom scalar spec project, we provide templates for writing custom sca Our hope is that this enables an ecosystem of clearly documented custom scalars and eliminates the need to reinvent popular ones again and again. Ultimately, a popular enough custom scalar will be practically indistinguishable from the built-in ones and elevate the GraphQL type system. ## Get involved! -See how to contribute a custom scalar spec on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide.html). + +See how to contribute a custom scalar spec on the [contribution guide](https://scalars.graphql.org/readme-contribution-guide). If you have any comments or questions, please open an issue on the [graphql-scalars GitHub repository](https://github.com/graphql/graphql-scalars). - \ No newline at end of file From d1c0a3b32a898d6083a0ced8570eda148f9eb152 Mon Sep 17 00:00:00 2001 From: dondonz <13839920+dondonz@users.noreply.github.com> Date: Sat, 14 Jan 2023 13:33:08 +1100 Subject: [PATCH 3/3] Add today's date --- ...01-17-graphql-scalars.md => 2023-01-14-graphql-scalars.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename src/content/blog/{2023-01-17-graphql-scalars.md => 2023-01-14-graphql-scalars.md} (98%) diff --git a/src/content/blog/2023-01-17-graphql-scalars.md b/src/content/blog/2023-01-14-graphql-scalars.md similarity index 98% rename from src/content/blog/2023-01-17-graphql-scalars.md rename to src/content/blog/2023-01-14-graphql-scalars.md index ccef8cfbd2..49278abfab 100644 --- a/src/content/blog/2023-01-17-graphql-scalars.md +++ b/src/content/blog/2023-01-14-graphql-scalars.md @@ -2,9 +2,9 @@ title: GraphQL Custom Scalar specifications tags: ["announcements"] layout: blog -date: 2023-01-17 +date: 2023-01-14 byline: Andreas Marek, Donna Zhou -permalink: /blog/2023-01-17-graphql-scalars +permalink: /blog/2023-01-14-graphql-scalars --- # Announcing contributed GraphQL custom scalar specifications