GraphQL for XML users

If you have integrated with XML, SOAP or JDF/JMF interfaces, the ideas behind GraphQL will feel familiar: a schema defines what is allowed, messages follow that schema, and tools validate them. This page maps the XML concepts to their GraphQL counterparts. The XML samples are generic illustrations.

XML Schema and GraphQL SDL

An XSD defines element types:

<xs:complexType name="Customer">
  <xs:sequence>
    <xs:element name="id" type="xs:string"/>
    <xs:element name="name" type="xs:string"/>
    <xs:element name="email" type="xs:string" minOccurs="0"/>
    <xs:element name="address" type="Address" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>

The GraphQL schema language (SDL) describes the same thing more compactly. This is part of the CoCoCo customer type:

type CustomerState {
  id: CustomerID!
  name: String!
  email: String
  addresses: [AddressState!]!
}

XML Schema	GraphQL SDL
xs:complexType	type (output) or input (arguments)
minOccurs="1"	! (non-null)
minOccurs="0"	no ! (nullable)
maxOccurs="unbounded"	[Type] (list)
xs:enumeration	enum
xs:simpleType with a pattern	custom scalar, such as CustomerID, ISO8601 or CurrencyISO
XML attributes	fields; GraphQL does not distinguish attributes from elements
Namespaces	one schema; names are unique, so no prefixes are needed

The WSDL-and-XSD pair becomes one document you download from GET https://<your-tenant-host>/graphql/schema.

SOAP operations and GraphQL operations

A SOAP call wraps an operation in an envelope:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetCustomer>
      <CustomerId>1001</CustomerId>
    </GetCustomer>
  </soap:Body>
</soap:Envelope>

In GraphQL the operation is the request body, and you list the fields you want back:

query Customer {
  getCustomer(id: "cus_01M0R2496SFANSZFKWPYW17V0J") {
    name
    email
  }
}

SOAP	GraphQL
WSDL operation, read-only	field on Query
WSDL operation that changes data	field on Mutation
Envelope and body	JSON body with query and variables
SOAPAction header	the operation itself
soap:Fault	top-level errors array
WS-Security header	Authorization: Bearer <API token>

Selecting only what you need

An XML response returns the full document the service defines. A GraphQL response contains only the fields you asked for, in the same nesting:

query CustomerWithAddresses {
  getCustomer(id: "cus_01M0R2496SFANSZFKWPYW17V0J") {
    name
    addresses {
      addressType
      city
      country
    }
    contacts {
      firstName
      lastName
      email
    }
  }
}

{
  "data": {
    "getCustomer": {
      "name": "Nordlicht Verlag GmbH",
      "addresses": [{ "addressType": "BOTH", "city": "Hamburg", "country": "DE" }],
      "contacts": [{ "firstName": "Anna", "lastName": "Berger", "email": null }]
    }
  }
}

Hierarchies and references

A JDF ticket nests everything inside one document: the job, its product parts, resources and process nodes. CoCoCo stores those as separate records that refer to each other by ID, and a query follows the references for you:

query JobTree {
  getJob(id: "job_01M0R249JMETNBM1Z7466MXGZD") {
    name
    components {
      name
      kind
      artworkFiles {
        usageRole
        externalUri
      }
    }
    operations {
      name
      kind
      status
      componentId
    }
  }
}

The same records can also be reached on their own (getComponent, listOperations), which an XML hierarchy does not allow without IDREFs. API overview maps JDF concepts to CoCoCo types.

Reusable parts: XSD groups and fragments

Where an XSD reuses definitions with xs:group or xs:include, a GraphQL client reuses selections with fragments:

fragment AddressLines on AddressState {
  street1
  street2
  postalCode
  city
  country
}

query CustomerAddresses {
  getCustomer(id: "cus_01M0R2496SFANSZFKWPYW17V0J") {
    name
    addresses {
      addressType
      ...AddressLines
    }
  }
}

Errors

A SOAP fault replaces the whole response. A GraphQL response can carry both data and errors. In CoCoCo, validation problems in a mutation come back in the payload as errors { path message }, where path names the input field, much like an XPath to the failing element. Authentication and permission problems come back in the top-level errors array. See Core patterns.

Tools

To explore the schema and try requests, use the GraphQL playground in the CoCoCo console (/#/graphql-playground), which has a schema explorer next to the editor. For validation while you write, the same way an XML editor checks against an XSD, point an editor plugin at your tenant's schema. GraphQL tooling covers editors, clients and code generation.

Next steps

• API overview
• Core patterns
• GraphQL introduction