►
Description
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. Get Started Here: https://graphql.org/
Schema Metadata: A Growing Need - Benjie Gillam, Graphile
JW Marriott Austin, Room 402/403
Speakers: Benjie Gillam
GraphQL's introspection system is one of its key features, enabling much of the powerful tooling we use throughout the GraphQL ecosystem. However, currently the GraphQL specification doesn't give an official way to add custom metadata to schemas. From complex challenges such as federating schemas to simply indicating pagination limits, our needs for this metadata are growing. This talk will surface some of the use cases for schema metadata, look over some of the workarounds that are in use, and briefly explore some proposed solutions.
C
A
That's
awesome
I
feel,
like
I
don't
know
if
you
can
hear
that
from
my
from
the
mic
on
the
computer
in
in
the
audience
you
heard,
clapping
people
are
excited
specifically
clapping
from
from
matt
mahoney,
very,
very
excited
to
have
the
audio
spark
notes.
I
was
gonna
say
I
in
every
board
meeting
I
report
back
to
the
board
all
remember
companies
to
the
foundation.
They
ask.
How
was
the
last
working
group?
What
did
you
guys
talk
about
and
I
do
like
a
report
or
I
just
ramble
and
it's
usually
five
to
eight
minutes.
A
A
A
B
A
It's
like
kind
of
a
line
by
line
of
what
everyone
said,
which
is
very
helpful
when
we
want
to
look
back.
What
did
we
say
about
that?
Exactly
it's
like
well,
lee
said
this
and
then
matt
said
that
and
then
you
said
this
is
like.
Oh
okay
and
the
youtube
are
of
course,
two
hours
long,
because
that's
how
long
our
meetings
are,
and
it's
painful
enough
to
sit
through
a
live
two-hour
meeting,
let
alone
like
watch
the
recorded
version.
A
A
All
right
benji!
Well,
we
miss
you.
Thank
you
for
joining
us
virtually
here
for
a
few
minutes,
so
everyone
can
see.
In
fact
you
are
an
alive
human
and
not
just
a
pre-recorded
video.
So
thanks
for
for
being
part
of
the
live
event,
and
thank
you
for
recording
and
talk
and
everything
else,
you
do
bye-bye
benji.
A
C
Hello,
everyone,
my
name
is
benji.
You
may
know
me
as
a
member
of
the
graphql
technical
steering
committee
as
one
of
the
people
that
takes
the
notes
at
the
graphql
working
group
or
as
the
maintainer
of
postgraph
file.
I'm
incredibly
disappointed
to
not
be
able
to
join
you
today
at
the
first
official
graphql
conference.
C
C
Now,
let's
start
by
looking
at
some
use
cases
in
your
application,
you
may
well
allow
users
to
order
data
by
some
custom
criteria
and
if
you
do
it's
quite
likely
that
you
use
an
enum
such
as
this
one
to
allow
that
now.
The
values
that
you
use
in
that
enum
and
the
values
that
you
put
in
your
sorting
drop
down,
for
example,
are
unlikely
to
be
the
same
text
likely.
You
are
using
a
friendly
label
for
the
actual
options
that
you
display
to
the
user.
C
Our
graphql
schema
could
represent
this
by
attaching
label
metadata
to
the
enum
values
themselves.
If
we
were
to
do
this,
then,
as
we
add
more
sort
options
to
the
graphql
api,
the
client
can
automatically
represent
them
in
the
dropdown
displaying
everything
it
needs
to.
We
could
even
add
translations
for
all
the
different
languages.
This
would
be
incredibly
useful.
C
C
Speaking
of
tooling
picking
up
on
things-
wouldn't
it
be
great
if,
when
we
looked
at
a
field
in
graphical
graphical,
gave
us
a
customized
query
that
we
could
use
to
query
this
field
to
demonstrate
to
users
that
are
new
to
our
api,
how
to
use
this
field.
I
think
this
would
be
an
incredibly
helpful
way
to
help
users
get
on
board
with
your
api,
especially
if
they're
not
already
familiar
with
graphql.
C
Another
thing
is,
as
you
add
things
to
your
graphql
api,
you
may
well
want
to
leave
yourself
space
to
change
them
when
you're
not
really
certain
that
this
is
what
you
want
to
end
up
with.
Once
you
add
something
permanently
to
your
api,
you
want
it
to
be
stable
for
a
long
time,
but
you
still
want
to
be
able
to
do
experiments
on
new
features.
C
C
What
this
means
is
that
we
can
rely
on
the
facts
that
are
in
the
specification
that
any
schema
any
api
that
implements
the
graphql
specification
supports
all
of
these
things,
and
so
we
can
use
all
of
this
powerful,
tooling,
the
code
generation,
the
linting,
the
ide
integration,
the
graphical
tool
for
exploring
it.
We
can
use
all
of
these
things
with
any
graphql
api,
and
I
think
that
is
incredible.
C
C
C
All
of
this,
combined
to
enable
tooling
such
as
graphical
to
indicate
details
about
our
graph
cure
schema
and
to
expose
the
documentation
that
you
see
above
and
to
allow
us
to
write,
queries
and
see
the
results
of
those
on
the
side.
We
can
even
click
around
and
browse
through
our
documentation
and
basically
see
everything
that
we
need
in
order
to
understand
our
schema.
C
C
C
If
we
look
at
graphql
ruby,
for
example,
it
allows
us
to
extend
the
schema
type,
the
double
underscore
schema
type
by
just
extending
it
like
any
other
class
in
ruby.
We
just
add
extra
fields
to
it.
Similarly,
in
hot
chocolate,
here's
an
example
that
I
pulled
off
of
stack
overflow.
That
shows
how
to
add
the
additional
info
field
to
an
enum
value.
C
Now,
extending
the
schema
in
this
way
does
have
a
number
of
trade-offs.
One
is
that
it
might
require
three-phase
introspection.
First
of
all,
finding
out
what
features
the
schema
supports,
then
finding
out
what
types
and
fields
the
schema
has
and
finally
issuing
another
query
that
introspects
that
gets
the
result
of
these
extended
introspection
fields.
C
But
finally,
one
of
the
issues
with
it
is
that
it
has
the
potential
for
introducing
breaking
changes.
For
example,
if
you
were
to
add
a
field
to
the
introspection
for
the
double
underscore
type
type,
and
then
we
as
the
graph
cure
specification,
will
also
to
add
that
field.
Maybe
it
has
a
different
type.
Maybe
it
accepts
different
arguments,
then
that
would
result
in
a
conflict.
C
C
Another
solution
that
we
see
out
there
in
the
graphql
ecosystem
is
the
sdl
field.
Most
typically,
we
see
this
used
with
apollo
federation
now,
keep
in
mind
that
apollo
federation
has
a
very
specific
use
case,
but
I'd
like
to
analyze
this
sdl
field
and
see
if
it's
useful
for
the
generic
representation
of
metadata.
In
our
schema
in
apollo
federation,
they
add
an
underscore
service
field
at
the
root
of
the
query
type
and
then,
within
that
they
add
an
sdl
field,
and
that
contains
a
string.
C
Now,
one
of
the
trade-offs
of
this
approach
is
that
it
breaks
the
equivalence
between
introspection
and
sdl.
Normally,
everything
that
you
need
to
know
about
your
graphql
schema
is
represented
through
introspection,
but
here
we
would
need
to
actually
request
the
sdl
field
and
extract
from
that
these
additional
directives
that
aren't
represented
through
introspection.
C
C
C
It
also
is
a
very
all
or
nothing
approach.
The
sdl
describes
the
entire
graphql
schema
and
has
all
of
the
information
in
it.
So
there's
no
way
to
specifically
say
I'd
like
to
know
just
the
directives
for
this
particular
type.
Please
in
introspection.
We
can
do
that
with
the
double
underscore
type
field
in
the
root
of
the
query,
but
with
the
sdl
field,
we
could
not
do
that.
C
It's
also
somewhat
redundant.
Most
of
the
things
in
the
sdl
field
are
already
there
in
introspection
all
the
types
all
the
fields,
all
the
arguments,
all
the
descriptions,
the
only
thing
it's
adding
is
those
directives,
and
yet
it's
adding
an
entire
new
piece
of
complexity
to
the
graphql
schema
for
it.
C
And
finally,
it
also
pollutes
that
main
schema
with
fields
that
our
typical
users
don't
want
to
be
querying.
We
don't
want
to
have
that
stuff
show
up
in
the
graphical
sidebar,
for
example.
This
is
stuff
that
only
tooling
should
be
worried
about
another
solution
that
we
see
out
there
in
the
wild
is
putting
markup
into
the
description
that
represents
our
additional
metadata.
C
C
C
C
Another
potential
solution
would
be
to
indicate
what
metadata
there
is
in
the
schema
using
user
space
fields
and
types.
So
there's
a
lot
of
different
ways
that
you
might
build
this.
Here's
one,
you
could
add
an
introspection
metadata
field
to
your
query
type
and
have
that
represent
a
list
of
introspection
metadata.
C
Maybe
that
indicates
which
thing
the
metadata
is
attached
to
via
a
schema
coordinate
you
can
read
more
about
schema,
coordinates
in
spec
issue
735,
and
then
you
can
indicate
metadata
and
that
metadata
could
be
with
a
union
or
an
interface
or
whatever
you
need
to
represent
what
you
have
now.
One
of
the
biggest
issues
about
having
this
users-based
metadata
is
that
it's
in
user
space,
which
means
users,
can
define
it.
However,
they
want
tooling,
can't
necessarily
rely
on
it.
Just
because
it
has
this
field
doesn't
mean
it
fully
implements.
C
But
one
of
the
bigger
issues
for
me
is
that
it
requires
reassembly.
We
have
the
schema
introspection
data
here
and
we
have
the
metadata
here
once
we
fetch
them.
Both
we
have
to
mush
them
back
together,
again
ourself,
which
is
something
that
we
shouldn't
really
have.
Clients
need
to
do
most
of
the
rest
of
graphql
is
self-consistent,
and
you
can
just
explore
any
an
existing
object
directly.
C
C
Now,
suggestions
of
what
it
should
look
like
do
differ,
but
here's
an
example:
we
can
extend
all
of
the
double
underscore
types
in
the
graphql
schema,
so
double
underscore
field,
double
underscore
type,
double
underscore:
enum
value,
etc
and
give
them
all
the
applied
directives
field.
This
would
take
a
list
of
all
of
the
directives
that
have
been
applied
and
we
indicate
for
those
what
the
name
of
the
directive
is,
or
maybe
the
directive
reference
itself
and
the
arguments
to
that
directive.
C
C
This
is
something
that
we've
already
solved
with
default
value
in
which
we
use
a
string,
but
we
might
also
want
to
consider
using
something
like
json
or
something
like
one
of,
but
maybe
these
things
aren't
ideal
if
we
were
to
use
string,
which
is
what
all
the
current
implementations
do,
then
we're
going
to
require
that
client-side
passing
again
and
what
that
means
is
again.
If
we
introduce
new
syntax,
it
could
break
existing
clients
that
are
just
requesting
this
regular
string
field.
C
Normally,
when
we
introduce
functionality
in
graphql,
we
add
new
fields
for
it,
so
that
existing
clients
are
unaffected.
This
breaks
that
pattern
now,
of
course,
we
do
have
that
same
issue
with
default
value
already,
but
it's
very
rare
for
a
client
to
actually
introspect
the
default
value
figure
out
what
it
means
and
use
that
information
normally.
A
C
Another
issue
is
because
we're
using
directives
we're
using
input
types
and
at
the
moment
we
don't
have
any
forms
of
input
polymorphism.
Now
we
might
get
them,
maybe
with
the
one-off
directive.
That's
currently
rfc2,
maybe
with
other
input
unions
in
the
future.
But
for
now
we
don't
support
polymorphism
on
input
and
another
issue:
is
it
again
does
not
support
this
sub
selection
if
you've
got
large
amounts
of
metadata
all
these
different
translations,
for
example,
you
can't
just
pull
down
the
english
translation.
C
C
C
Another
option
would
be
to
estee
the
word
directive
altogether
and
replace
it
with
something
like
directive,
maybe
use
a
different
symbol
for
directive
like
a
plus
rather
than
an
act.
It
might
work
broadly
the
same
way,
but
by
using
a
different
keyword
and
representing
it.
In
a
different
way,
it's
clear
that
this
differs
from
regular
directives,
but
are
directives
even
the
right
approach
anyway,
one
thing
is
that
metadata
is
informational
rather
than
instructive.
Directives.
Tell
you
to
do
something,
whereas
metadata
describes
something
they're
different
things
really.
C
C
Another
thing
is
the
directives
are
optional:
they
don't
have
to
be
applied
anywhere,
so
there's
not
really
an
easy
way
to
indicate
to
a
client
that
you
guarantee
that
a
directive
will
be
applied
to
every
single
enum
value
or
every
single
input
field,
and
that
means
that
you
have
to
put
a
little
bit
more
effort
into
how
you
build
that
tooling.
That
relies
on
that
information.
C
C
Do
we
need
to
be
able
to
do
sub
selections
on
our
metadata
rather
than
pulling
down
the
whole
thing
all
at
once?
Maybe
we
need
to
apply
metadata
to
places
where
directives
don't
support
now.
This
isn't
necessarily
a
big
problem,
because
we
can
just
support
directives
in
more
locations,
but
it
does
warrant
thinking
about,
and
another
question
is:
do
we
want
to
be
able
to
attach
metadata
to
built-ins
like
the
id
built-in?
We
might
want
to
indicate
through
metadata
that
it
will
always
be
in
uuid
format.
C
C
Here's
some
use
cases
in
a
client,
it's
very
common,
especially
a
single
page
application
to
want
to
be
able
to
validate
data
on
the
client
side
before
sending
it
to
the
server
having
this
kind
of
shared
validation.
That
is
run
on
the
client
and
then
later
run
again
on.
The
server
is
a
common
need
and
it
allows
us
to
give
the
user
the
absolute
best
experience
by
telling
them
whether
their
data
is
valid
or
not
before
they
even
submit
any
forms.
C
Another
thing
to
consider
is
when
we
want
to
actually
browse
more
and
more
information
about
something
say.
For
example,
we
wanted
to
know
about
the
history
of
a
particular
type
in
our
graphql
schema.
We
might
want
to
know
which
git
commit
it
was
introduced
with
or
which
pull
request
it
was
introduced
with.
We
might
want
to
know
when
it
was
elevated
from
experimental
to
full
published
status.
C
We
might
want
to
know
who
was
the
person
who
last
touched
it,
and
what
other
things
have
they
changed
recently
and
in
this
way
we
may
want
to
recurse
through
the
data
that's
available
to
us.
This
is
not
something
that
we
can
do
if
we
use
input
types
now.
I've
been
thinking
about
this
problem
for
quite
a
long
time,
and
I
don't
have
a
concrete
solution
right
now,
but
the
closest
that
I've
got
is
the
user
extendable
meta
types
which
I'd
like
to
tell
you
about
now.
C
So
in
this
we
would
change
the
graphql
specification
itself
and
we
would
add
a
meta
field
to
all
these
introspection
types.
The
double
underscore
type
double
underscore
field,
double
underscore
enum
value
and
so
on,
and
they
would
all
have
a
meta
field
which
would
be
of
a
particular
type
that
we
would
be
able
to
extend.
C
Then
in
our
application
code
in
our
graphql
schema
code,
we
would
extend
these
meta
types
and
we
would
add
our
own
fields
to
them.
Things
like
the
is
experimental
or
the
validations
that
I
was
just
talking
about,
and
this
allows
us
to
indicate
that
these
fields
are
present
will
always
be
present
with
the
not
null
and
so
on.
C
C
Another
thing
is
the
not
null
allows
us
to
guarantee
the
presence
of
metadata
which
simplifies
building
our
tooling,
because
we
no
longer
need
to
check
for
nullability
or
handle
that
situation,
and
because
this
is
all
part
of
the
introspection
schema.
It's
not
going
to
pollute
that
public
schema.
It's
not
going
to
show
up
unexpectedly
in
the
sidebar
of
graphical
and
confuse
our
users.
C
C
Another
drawback
is
one
of
the
benefits
which
is
allowing
this
recursion.
Now.
If
we
allow
this
recursion,
then
it
may
be
impossible
for
us
to
fully
represent
our
graphql
schema
via
schema
definition,
language
and
further.
It
means
that
tools
like
graphical
can't
necessarily
fully
explore
this
metadata
themselves.
C
C
Another
issue
is
that
extending
introspection
types
just
doesn't
feel
right.
It's
something
that
we
have
been
telling
users
they're
not
allowed
to
do
for
a
long
time,
and
if
we
change
that
rule,
we
must
be
careful
in
how
we
do
so.
We
must
be
very
careful
with
how
we
communicate
it.
Just
doesn't
quite
feel
right
to
me,
but
the
biggest
issue,
I
think,
is
that
it
breaks
that
schema
definition,
language
and
introspection
equivalence.
C
Now
we
can
potentially
work
around
a
number
of
these
issues
by
adding
validation
rules.
For
example,
we
could
add
a
validation
rule
that
forbids
recursion.
We
could
add
a
validation
rule
that
forget
forbids
arguments
and
that
may
solve
a
number
of
these
issues,
but
I've
not
yet
thought
thought
fully
through
these
problems.
So
this
is
something
I'll
continue
to
explore
over
the
coming
weeks
and
months.
C
C
What
we
need
to
do
next
is
raise
this
to
be
rfc
one
to
do
so,
we
need
to
identify
a
champion.
We
need
a
clear
explanation
of
the
problem
and
the
solution.
We
need
illustrative
examples.
We
need
some
spec
edits
that
represent
what
should
be
happening.
They
don't
have
to
be
final,
but
we
need
to
at
least
the
beginnings
of
them
and
we
need
to
identify
the
concerns,
the
challenges
and
the
drawbacks.
C
C
So,
if
you
can
submit
there
your
use
cases,
what
metadata
do
you
need
to
represent
in
there
if
you
can
submit
what
you
think,
a
good
solution
to
this
problem
would
be,
and
also,
if
you
look
at
the
solutions
that
have
been
raised
in
that
issue
and
the
solutions
that
I've
outlined
in
this
presentation
and
say
what
concerns
you
have
with
them,
what
challenges
and
drawbacks
you
see
with
them?
That
would
be
incredibly
valuable.