# GraphQL Schemas

A GraphQL service accepts its schema in either of two shapes. Both lead to the same documentation, so use whichever fits your pipeline.

## Prerequisites

- A registered service and its upload token. See [Publishing a Specification](/documentation/publishing-specifications).

## Option 1: SDL text

Publish the `.graphql` or `.gql` schema file that already lives next to your service source:

```bash
curl -X POST https://docs.example.com/api/v1/services/billing-api/spec \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  --data-binary @schema.graphql
```

## Option 2: introspection result

If your pipeline queries a live GraphQL endpoint instead, publish the introspection result as JSON. Both the full `{"data": {"__schema": ...}}` envelope and an already-unwrapped `{"__schema": ...}` work. When piping one `curl` into another, use `--data-binary @-` so the JSON is not re-encoded:

```bash
curl -sS https://billing.internal/graphql \
  -H "Content-Type: application/json" \
  -d @introspection-query.json \
  | curl -X POST https://docs.example.com/api/v1/services/billing-api/spec \
      -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @-
```

`introspection-query.json` holds the standard `{"query": "query IntrospectionQuery { ... }"}` body. GraphQL tooling, such as the `graphql` npm package's `getIntrospectionQuery()`, can generate the query text.

## The service name

SDL has no `info.title`, so the display name comes from the description directly above a `schema { ... }` block if there is one, otherwise from the description of the `Query` type:

```graphql
"""Billing API"""
type Query {
  invoice(id: ID!): Invoice
}
```

An introspection publish resolves the name the same way: `__schema.description` if the server sets it (most do not), otherwise the `Query` type's description. If neither exists, publishing to a service that has never had a version is rejected with `info.title is required`. A service that already has a name keeps it.

## What you see

Fields of the schema appear in the left menu and on their own pages with arguments and return types. Versions, the [Change Log](/documentation/change-log) and overlays work as for other formats. A changed GraphQL return type is a breaking change, except when it becomes non-null.

In exports, GraphQL fields are documented with their arguments and return type, without examples or curl commands. See [Export Wizard](/documentation/export-wizard).

## Next steps

- [Publishing a Specification](/documentation/publishing-specifications)
- [Versions and Branches](/documentation/versions-and-branches)

---
Source: https://selfdochub.com/documentation/graphql-schemas
