Schema Overview

In this section we take a quick a look at the GraphQL Schema in more detail as this context can prove useful when it comes to working with the API. We’ll examine the schema from the perspective of some of the main objects, (e.g. “Advert”), and those related to them.

Note: that for the purposes of this discussion we’ll not detail out every related object as we want to keep the conversation focused on the main actors.

What You’ll Learn

By the end of this article, you’ll have learned:

  • The business context behind the main objects
  • How the objects inter-relate to one and other
  • Some additional GraphQL Queries

Our Focus

We’re going to focus on the on the following 3 objects, (and their “relatives”):

  • Advert
  • Cart (Coming Soon)
  • Order (Coming Soon)

The sequencing of which (see Figure-1) should be familiar to those of you who shop online! By taking this view, we’ll then cover some real-world Use Cases that you can use and adapt in your own applications.

Note: You can explore a full visualization of our schema using GraphQL Voyager.

Figure-1 Schema-Overview-Main-Objects

The Advert Perspective

The Advert object and its primary relations are shown in Figure-2 below.

Figure-2 Schema-Overview-Advert-Perspective

An Advert is placed by the Seller, most usually an Advert will represent a Product or Service, but in some instances it can represent an Event or Holiday. (This distinction is handled by the taxonType enumeration in the Taxon object.) In this article, the Advert can be thought of as the “top-most container”, upon which the others relate.

An Advert has the following relationships:

  • An Advert has 1 Taxon
  • An Advert has 1 Seller
  • An Advert has 1 or more Variants

Note: There is a worked example diagram further down this article, this depicts these relationships in more detail.

Taxon

A Taxon, (or Taxonomy Item), is an item within the site’s categorisation hierarchy, for instance, on an outdoor and adventure specialist web site the “Jackets” Taxon is one of the children of the “Outerwear” Taxon.

The Taxon structure is built as a tree working out from the root node. Each Taxon is a child of the Root Node or another Taxon, (as denoted by the self-referencing relationship in Figure-2).

As mentioned above, a Taxon has a taxonType which represents a high-level abstraction of what it represents: a Product, Service, Event or Holiday.

Additionally, a Taxon has a Prototype, (an example Prototype would be “Clothes”), which determines the Option Types, (think “attributes”), that an Advert with that Taxon can have.

So, for example the Clothing Prototype would allow Adverts, (in the relevant Taxon), to have: Colour and Size Option Types, but not Screen Size or Engine Capacity.

Taxon Relationships

A Taxon has the following relationships:

  • A Taxon has many Adverts
  • A Taxon can have 1 Parent (Taxon)
  • A Taxon can have many Children (Taxons)
  • A Taxon has 1 Prototype

Variant

Variants represent the ways an Advert can vary. As discussed already, an item of clothing could have both a colour and size options, (as provided by the available Option Types). It is the combination of the different Option Types that would represent the total number of Advert Variants.

For example, if we have 2 sizes (these are Option Values): Small and Large, and 2 colours: Black and White then we would have a total of 4 Variants for that Advert:

  • Small / White
  • Small / Black
  • Large / White
  • Large / Black

Note: Event if an Advert “has nothing to vary”, it will still require a Variant to represent attributes such as:

  • barcode
  • SKU (Stock Keeping Unit – basically a unique id)
  • Stock On Hand

Variant Relationships

A Variant has the following relationships:

  • A Variant belongs to 1 Advert
  • A Variant has many Option Values

Seller

A Seller (otherwise referred to as a Retailer), represents a business that sells on the Marketplacer platform. They can list Adverts add Coupons and Promotions, receive and update the status of Invoices and they may receive an enquiry.

Seller Relationships

A Seller has the following relationships:

  • A Seller can have many Adverts

Prototype

A Prototype is associated to a Taxon and defines the attributes of all Adverts within that Taxon. A Prototype defines which Option Types are applicable to the Adverts and Variants in that Taxon.

Refer to the discussion on Taxons (above) for a bit more detail on how Prototypes are used.

A Prototype has the following relationships:

  • A Prototype can belong to many Taxons
  • A Prototype can have many Option Types

Option Type

An Option Type is a custom field that is associated to an Advert or Variant. This association is performed by the Prototype, refer to the discussion on Prototypes above for further explanation. Common examples of Option Types would be:

  • Colour
  • Size
  • Capacity

An Option Type has the following relationships:

  • An Option Type has many Prototypes
  • An Option Type has many Option Values

Option Value

An Option Value is the pre-defined value of an Option Type. For example, for the colour Option Type, Option Values could include: green, red, blue etc.

An Option Value has the following relationships:

  • An Option Value has one Option Type
  • An Option Value can belong to many Variants

Worked Example

The figure below (Figure-3 ) shows a view of the above objects with some data values as reference, you should note that this is view is somewhat simplified and does not:

  • Show all relationships between the objects
  • Show all the attributes for the objects

Figure-3 Schema-Overview-Advert-Worked-Example

Example Query

Below is an example GraphQL query that you can use to query the Marketplace GraphQL API to render output similar to that found in the Worked Example.

For more information on how to get up and running with the API follow the steps here Getting Started

{
  advertSearch(attributes: { keywordQuery: "Computer" }) {
    adverts {
      edges {
        node {
          id
          title
          seller {
            businessName
          }
          taxon {
            displayName
            taxonType
            prototype {
              name
              optionTypes {
                edges {
                  node {
                    name
                    optionValues {
                      edges {
                        node {
                          name
                        }
                      }
                    }
                  }
                }
              }
            }
          }
          variants {
            edges {
              node {
                label
                barcode
                countOnHand
                sku
                barcode
                optionValues {
                  edges {
                    node {
                      displayName
                    }
                  }
                }
              } 
            }
          }
        }
      }
    }
  }
}

Further reading

The Marketplacer GraphQL API covers the queries and mutations you need to search, browse and display adverts and sellers as well as creating carts and orders. Read the full documentation to find out more, or interactively explore the schema with GraphQL Voyager.