Schema Generation

Documentation for Umbraco Heartcore GraphQL schema generation

The GraphQL schema is generated from the Content Types upon creation, and it is generated when a Content Type or a Data Type is changed.

The type name is the Content Type's alias in Pascal Case, e.g. if a Content Type has an alias of product it's GraphQL type name would be Product.

Table of Contents

Types

The types generated depends on how the Content Types are configured.

If a Content Type is inherited from or used as a Composition it will be generated as an interface

interface NavigationBase {
  seoMetaDescription: String
  umbracoNavihide: Boolean
}

If the Document Type is marked as an Element Type it will implement the Element interface

type Feature implements Element {
  contentTypeAlias: String!
  featureName: String
  featureDescription: String
}

All other Content Types will implement either the Content or the Media interface, they will also implement all their Composition interfaces.

type Product implements Content & NavigationBase {
  ancestors(...): ContentConnection!
  category: [String]
  children(...): ContentConnection!
  contentTypeAlias: String!
  createDate: DateTime!
  descendants(...): ContentConnection!
  description: String
  features: [Element]
  id: ID!
  level: Int!
  name: String
  parent: Content
  photos: Media
  price: Decimal
  productName: String
  sku: String
  sortOrder: Int!
  seoMetaDescription: String
  umbracoNavihide: Boolean
  updateDate: DateTime
  url: String
}

A Connection and an Edge type will also be generated, these are used when quering Content of a specific type.

type ProductConnection {
  edges: [ProductEdge]
  pageInfo: PageInfo
}

type ProductEdge {
  cursor: String!
  node: Product
}

Fields

All properties on a Content Type is generated as a field on the GraphQL type. See the Property Editors page for which types the editors are returning.

If a property is marked as Allow varying by culture, a culture argument is added to that field. The argument is optional and will fallback to the parent fields culture or the default culture if none is specified.

type Product implements Content & NavigationBase {
  ...
  productName(culture: String): String
  ...
}

Root Query

The Query type is the entry to the GraphQL API. By default it contains two fields, one to get a single Content item by ID or url and one to get all Content.

type Query {
  """
  Get Content by its unique identifier or url. Either id or url must be specified but not both.
  """
  content(
    """
    The unique identifier of the content.
    """
    id: ID,
    """
    The url of the content.
    """
    url: String,
    """
    The culture to fetch the content in. If empty the default culture will be used.
    """
    culture: String
    """
    Specifies if draft content should be returned. Requires the request to be authenticated.
    """
    preview: Boolean
  ): Content
  """
  Get all Content.
  """
  allContent(
    """
    Specifies the number of edges to return starting from `after` or the first entry if `after` is not specified.
    """
    first: Int,
    """
    Only look at connected edges with cursors greater than the value of `after`.
    """
    after: String,
    """
    Specifies the number of edges to return counting reversely from `before`, or the last entry if `before` is not specified.
    """
    last: Int,
    """
    Only look at connected edges with cursors smaller than the value of `before`.
    """
    before: String,
    """
    The culture to fetch the value in. If empty the default culture will be used.
    """
    culture: String,
    """
    Specifies if draft content should be returned. Requires the request to be authenticated.
    """
    preview: Boolean
    """
    Filter the returned data.
    """
    where: ContentFilterInput,
    """
    Sort the returned data.
    """
    orderBy: [ContentOrderByInput]
  ): ContentConnection!
}

For each Document Type that is not used as a Composition or marked as an Element Type, two fields will be generated on the Query type. One for getting a single Content item by either it's ID or url and a field for getting all Content of that specific type.

type Query {
  ...
  allProduct(first: Int, after: String, last: Int, before: String, culture: String, preview: Boolean, where: ProductFilterInput, orderBy: [ProductOrderByInput]): ProductConnection!
  product(culture: String, id: ID, url: String, preview: Boolean): Product
  ...
}

Reserved Type Names and Property Aliases

GraphQL requires that type names are unique. If a Content Type will collide with one of the reserved names the type will be excluded from generation.

The same applies to Properties. If a Property alias is a reserved one it will also be excluded from generation.

Reserved Type Names

List of reserved type names, these cannot be used as an alias for Content Types.

The GraphQL type name is the Content Type alias converted to Pascal Case.

  • BigInt

  • BlockGrid

  • BlockGridArea

  • BlockGridItem

  • BlockListItem

  • Byte

  • Content

  • Date

  • DateTime

  • DateTimeOffset

  • Decimal

  • DecimalRange

  • Element

  • Guid

  • HTML

  • ImageCropAnchor

  • ImageCropFormat

  • ImageCropMode

  • ImageCropper

  • ImageCropperCrop

  • ImageCropperCropCoordinates

  • ImageCropperFocalPoint

  • ImageCropRatioMode

  • JSON

  • Link

  • LinkType

  • Long

  • Media

  • MediaConnection

  • MediaEdge

  • Milliseconds

  • OurUmbracoGMaps

  • OurUmbracoGMapsAddress

  • OurUmbracoGMapsCoordinate

  • OurUmbracoGMapsMapConfig

  • OurUmbracoGMapsMapType

  • PageInfo

  • PickedColor

  • Query

  • SByte

  • Seconds

  • Short

  • UInt

  • ULong

  • Uri

  • UShort

Reserved Element Type Property Names

List of reserved Element Type Property names, these cannot be used as a Property alias on an Element Type.

  • contentTypeAlias

Reserved Content Type Property Names

List of reserved Content Type Property names, these cannot be used as a Property alias on a Content Type.

  • ancestors

  • children

  • contentTypeAlias

  • createDate

  • descendants

  • id

  • level

  • name

  • parent

  • content

  • parentId

  • sortOrder

  • updateDate

  • url

Reserved Media Type Property Names

List of reserved Media Type Property names, these cannot be used as a Property alias on a Media Type.

  • ancestors

  • children

  • createDate

  • descendants

  • id

  • level

  • mediaTypeAlias

  • name

  • parent

  • sortOrder

  • updateDate

  • url

Built-in Custom Types

The Umbraco Heartcore GraphQL schema contains some default types, below you can find a list of these types.

The Property Editors page contains a list of all the Property Editors and which GraphQL types they return.

Block Grid

type BlockGrid {
    """
    Items in the grid.
    """
    items: [BlockGridItem]!

    """
    Number of columns in the grid.
    """
    gridColumns: Int!
}

Query

{
  contentPage {
    blocks {
      gridColumns
    }
  }
}

Output

{
  "data": {
    "contentPage": {
      "blocks": {
        "gridColumns": 12
      }
    }
  }
}

Block Grid Area

type BlockGridArea {
    """
    Name of the area.
    """
    alias: String!

    """
    Items in the area.
    """
    items: [BlockGridItem]!

    """
    Number of rows spanned by the area.
    """
    rowSpan: Int!

    """
    Number of columns spanned by the area.
    """
    columnSpan: Int!
}

Query

{
  contentPage {
    blocks {
      items {
        areas: {
          alias
          columnSpan
          items {
            title
          }
        }
      }
    }
  }
}

Output

{
  "data": {
    "contentPage": {
      "blocks": {
        "items": [{
          "areas": [{
            "alias": "mainArea",
            "columnSpan": 12,
            "items": [{
              "title": "Essential Heartcore Tips: Volume 4"
            }]
          }]
        }]
      }
    }
  }
}

Block Grid Item

type BlockGridItem {
    """
    The content.
    """
    content: Element!

    """
    The settings.
    """
    settings: Element

    """
    Number of rows spanned by the item.
    """
    rowSpan: Int!

    """
    Number of columns spanned by the item.
    """
    columSpan: Int!

    """
    Number of columns in child areas.
    """
    areaGridColumns: Int!

    """
    Number of columns in child areas.
    """
    areas: [BlockGridArea]
}

Query

{
  contentPage {
    blocks {
      items: {
        content: {
          title
        }
        settings: {
          openLinkInNewTab
        }
        rowSpan
        columnSpan
      }
    }
  }
}

Output

{
  "data": {
    "contentPage": {
      "blocks": {
        "items": [{
          "content": {
            "title": "Essential Heartcore Tips: Volume 7"
          },
          "settings": {
            "openLinkInNewTab": false
          },
          "rowSpan": 1,
          "columnSpan": 4
        }]
      }
    }
  }
}

Block List Item

type BlockListItem {
    """
    The content.
    """
    content: Element!

    """
    The settings.
    """
    settings: Element
}

Query

{
  textPage {
    elements {
      content {
        title
      }
      settings {
        showLargeImage
      }
    }
  }
}

Output:

{
  "data": {
    "textPage": {
      "elements": [{
        "content": {
          "title": "Why use Umbraco Heartcore?"
        },
        "settings" {
          "showLargeImage": true
        }
      }]
    }
  }
}

Decimal Range

# Represents a range of decimals.
type DecimalRange {
  """
  Maximum value of the range.
  """
  maximum: Decimal!
  """
  Minimum value of the range.
  """
  minimum: Decimal!
}

Query:

{
  product {
    durability {
      minimum
      maximum
    }
  }
}

Output:

{
  "data": {
    "product": {
      "durability": {
        "minimum": 7,
        "maximum": 10
      }
    }
  }
}

HTML

"""
A string containing HTML code.
"""
scalar HTML

Query:

{
  product {
    description
  }
}

Output:

{
  "data": {
    "product": {
      "description": "<p>A nice leather jacket.</p>"
    }
  }
}

Image Cropper

type ImageCropper {
  """
  The predefined crops.
  """
  crops: [ImageCropperCrop]!
  """
  The image url with crop parameters.
  """
  cropUrl(
    """
    The crop alias.
    """
    alias: String
    """
    Change background color of the image.
    """
    backgroundColor: String
    """
    The width of the output image.
    """
    width: Int
    """
    The height of the output image.
    """
    height: Int
    """
    Quality percentage of the output image.
    """
    quality: Int
    """
    The image crop mode.
    """
    cropMode: ImageCropMode
    """
    The image crop anchor.
    """
    cropAnchor: ImageCropAnchor
    """
    Use a dimension as a ratio.
    """
    ratioMode: ImageCropRatioMode
    """
    The format of the output image.
    """
    format: ImageCropFormat
    """
    Use focal point to generate an output image using the focal point instead of the predefined crop if there is one.
    """
    preferFocalPoint: Boolean = false
    """
    If the image should be upscaled to requested dimensions.
    """
    upscale: Boolean = false
  ): String
  """
  The focal point position.
  """
  focalPoint: ImageCropperFocalPoint!
  """
  The focal point url template.
   """
  focalPointUrlTemplate: String!
  """
  The image url.
  """
  url: String!
}

Query:

{
  product {
    photo {
      cropUrl(width: 1980, height: 430)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&width=1980&height=430&upscale=false"
      }
    }
  }
}

Image Crop Anchor

enum ImageCropAnchor {
  """
  Anchors the position of the image to the bottom of it's bounding container.
  """
  BOTTOM
  """
  Anchors the position of the image to the bottom left side of it's bounding container.
  """
  BOTTOM_LEFT
  """
  Anchors the position of the image to the bottom right side of it's bounding container.
  """
  BOTTOM_RIGHT
  """
  Anchors the position of the image to the center of it's bounding container.
  """
  CENTER
  """
  Anchors the position of the image to the left of it's bounding container.
  """
  LEFT
  """
  Anchors the position of the image to the right of it's bounding container.
  """
  RIGHT
  """
  Anchors the position of the image to the top of it's bounding container.
  """
  TOP
  """
  Anchors the position of the image to the top left side of it's bounding container.
  """
  TOP_LEFT
  """
  Anchors the position of the image to the top right side of it's bounding container.
  """
  TOP_RIGHT
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, cropAnchor: TOP_LEFT)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=topleft&mode=crop&width=1980&height=430&upscale=false"
      }
    }
  }
}

Image Crop Format

enum ImageCropFormat {
  PNG
  JPG
  GIF
  WEBP
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, format: WEBP)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&width=1980&height=430&upscale=false&format=webp"
      }
    }
  }
}

Image Crop Mode

enum ImageCropMode {
  """
  When upscaling an image the image pixels themselves are not resized, rather the image is padded to fit the given dimensions.
  """
  BOX_PAD
  """
  Resizes the image to the given dimensions. If the set dimensions do not match the aspect ratio of the original image then the output is cropped to match the new aspect ratio.
  """
  CROP
  """
  Resizes the image to the given dimensions. If the set dimensions do not match the aspect ratio of the original image then the output is resized to the maximum possible value in each direction while maintaining the original aspect ratio.
  """
  MAX
  """
  Resizes the image until the shortest side reaches the set given dimension. This will maintain the aspect ratio of the original image. Upscaling is disabled in this mode and the original image will be returned if attempted.
  """
  MIN
  """
  Passing a single dimension will automatically preserve the aspect ratio of the original image. If the requested aspect ratio is different then the image will be padded to fit.
  """
  PAD
  """
  Resizes the image to the given dimensions. If the set dimensions do not match the aspect ratio of the original image then the output is stretched to match the new aspect ratio.
  """
  STRETCH
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, cropMode: PAD)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=pad&width=1980&height=430&upscale=false"
      }
    }
  }
}

Image Crop Ratio Mode

enum ImageCropRatioMode {
  """
  Calculate the image ratio based on the height.
  """
  HEIGHT
  """
  Calculate the image ratio based on the width.
  """
  WIDTH
}

Query:

{
  product {
    photo {
      cropUrl(width:1980, height: 430, ratioMode: WIDTH)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&height=430&widthratio=4.6046511627906976744186046512&upscale=false"
      }
    }
  }
}

Image Cropper Crop

type ImageCropperCrop {
  """
  The crop alias.
  """
  alias: String!
  """
  The crop coordinates.
  """
  coordinates: ImageCropperCropCoordinates
  """
  The crop height.
  """
  height: Int!
  """
  The crop width.
  """
  width: Int!
}

Query:

{
  product {
    photo {
      crops {
        alias
        height
        width
      }
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "crops": {
          "alias": "Hero",
          "height": 600,
          "width": 1580
        }
      }
    }
  }
}

Image Cropper Crop Coordinates

type ImageCropperCropCoordinates {
  x1: Decimal!
  x2: Decimal!
  y1: Decimal!
  y2: Decimal!
}

Query:

{
  product {
    photo {
      crops {
        coordinates {
          x1
          x2
          y1
          y2
        }
      }
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "crops": {
          "coordinates": {
            "x1": 0.08901424149934925,
            "x2": 0.055992598445931165,
            "y1": 0.3183501211863771,
            "y2": 0.4660414375419126
          }
        }
      }
    }
  }
}

Image Cropper Focal Point

type ImageCropperFocalPoint {
  """
  The left position.
  """
  left: Decimal!
  """
  The top position.
  """
  top: Decimal!
}

Query:

{
  product {
    photo {
      focalPoint {
        left
        top
      }
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "focalPoint": {
          "left": 0.5,
          "top": 0.5
        }
      }
    }
  }
}

JSON

"""
The `JSON` scalar type represents JSON values as specified by [ECMA-404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).
"""
scalar JSON

Query:

{
  product {
    data
  }
}

Output:

{
  "data": {
    "product": {
      "data": {
        "size": "100x100x100 mm",
        "weight": "300 g"
      }
    }
  }
}
type Link {
  """
  The name of the Link.
  """
  name: String!
  """
  The link target.
  """
  target: String
  """
  The link type.
  """
  type: LintType!
  """
  The link udi if type is CONTENT or MEDIA.
  """
  udi: String
  """
  The url.
  """
  url: String!
}

Query:

{
  product {
    link {
      name
      target
      type
      udi
      url
    }
  }
}

Output:

{
  "data": {
    "product": {
      "link": {
        "name": "Umbraco",
        "target": "_blank",
        "type": "EXTERNAL",
        "udi": null,
        "url": "https://umbraco.com/"
      }
    }
  }
}
enum LintType {
  """
  The link is a Content link.
  """
  CONTENT
  """
  The link is an external link.
  """
  EXTERNAL
  """
  The link is a media link.
  """
  MEDIA
}

Query:

{
  product {
    link {
      type
    }
  }
}

Output:

{
  "data": {
    "product": {
      "link": {
        "type": "CONTENT"
      }
    }
  }
}

Media With Crops

type MediaWithCrops {
  """
  The predefined crops.
  """
  crops: [ImageCropperCrop]!
  """
  The image url with crop parameters.
  """
  cropUrl(
    """
    The crop alias.
    """
    alias: String
    """
    Change background color of the image.
    """
    backgroundColor: String
    """
    The width of the output image.
    """
    width: Int
    """
    The height of the output image.
    """
    height: Int
    """
    Quality percentage of the output image.
    """
    quality: Int
    """
    The image crop mode.
    """
    cropMode: ImageCropMode
    """
    The image crop anchor.
    """
    cropAnchor: ImageCropAnchor
    """
    Use a dimension as a ratio.
    """
    ratioMode: ImageCropRatioMode
    """
    The format of the output image.
    """
    format: ImageCropFormat
    """
    Use focal point to generate an output image using the focal point instead of the predefined crop if there is one.
    """
    preferFocalPoint: Boolean = false
    """
    If the image should be upscaled to requested dimensions.
    """
    upscale: Boolean = false
  ): String
  """
  The focal point position.
  """
  focalPoint: ImageCropperFocalPoint!
  """
  The focal point url template.
  """
  focalPointUrlTemplate: String!
  """
  The media
  """
  media: Media!
  """
  The image url.
  """
  url: String!
}

Query:

{
  product {
    photo {
      cropUrl(width: 1980, height: 430)
    }
  }
}

Output:

{
  "data": {
    "product": {
      "photo": {
        "cropUrl": "https://media.umbraco.io/demo-headless/8d76d2e84a24637/new-color-umbraco-stickers-1.jpg?anchor=center&mode=crop&width=1980&height=430&upscale=false"
      }
    }
  }
}

Our Umbraco GMaps

type OurUmbracoGMaps {
  address: OurUmbracoGMapsAddress
  mapconfig: OurUmbracoGMapsMapConfig
}

Query:

{
  frontpage {
    location {
      address {
        coordinates {
          lat
          lng
        }
      }
      mapconfig {
        zoom
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "address": {
          "lat": 55.4063759,
          "lng": 10.3887197
        },
        "mapconfig": {
          "zoom": 19
        }
      }
    }
  }
}

Our Umbraco GMaps Address

type OurUmbracoGMapsAddress {
  coordinates: OurUmbracoGMapsCoordinate
}

Query:

{
  frontpage {
    location {
      address {
        coordinates {
          lat
          lng
        }
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "address": {
          "lat": 55.4063759,
          "lng": 10.3887197
        }
      }
    }
  }
}

Our Umbraco GMaps Config

type OurUmbracoGMapsMapConfig {
  apikey: String
  zoom: Int
  centerCoordinates: OurUmbracoGMapsCoordinate
  maptype: OurUmbracoGMapsMapType
  mapstyle: JSON
}

Query:

{
  frontpage {
    location {
      mapconfig {
        apikey
        zoom
        centerCoordinates {
          lat
          lng
        }
        maptype
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "mapconfig": {
          "apikey": "my-api-key",
          "zoom": 19,
          "centerCoordinates": {
            "lat": 55.4063759,
            "lng": 10.3887197
          },
          "maptype": "satellite"
        }
      }
    }
  }
}

Our Umbraco GMaps Coordinate

type OurUmbracoGMapsCoordinate {
  coordinates: String
  lat: Decimal
  lng: Decimal
  isEmpty: Boolean
}

Query:

{
  frontpage {
    location {
      address {
        coordinates {
          coordinates
          lat
          lng
          isEmpty
        }
      }
    }
  }
}

Output:

{
  "data": {
    "frontpage": {
      "location": {
        "address": {
          "coordinates": "55.4063759,10.3887197",
          "lat": 55.4063759,
          "lng": 10.3887197,
          "isEmpty": false
        }
      }
    }
  }
}

Our Umbraco GMaps Map Type

enum OurUmbracoGMapsMapType {
  roadmap
  satellite
  hybrid
  terrain
  styled_map
}

Page Info

"""
Information about pagination in a connection.