Skip to content

Schema Definition

Jump to bottom
mweikard edited this page Nov 5, 2018 · 7 revisions

Schema Definition

The GraphQL schemas used by CaaS are created from YAML definition files. Each file describes a GraphQL interface or object type with its inheritance and fields. It is best practice to define an interface and object type for each used CoreMedia content type and only define fields within the interface type (this is automatically done when using the Schema Generator).

Interface Types

Type Descriptor: !InterfaceType

Properties:

  • name: The type's name.
  • parents: The type's parent interface type.
  • fields: A list of defined fields.

Example:

!InterfaceType
name: CMLocalized
parents:
  - CMObject
fields:
  - !ContentProperty
    name: languageId
    sourceName: (locale)
    typeName: String

Object Types

Type Descriptor: !ObjectType

Properties:

  • name: The type's name.
  • parent: The type's parent object type.
  • interfaces: A list of interfaces the type implements.
  • fields: A list of defined fields.

Example:

!ObjectType
name: CMLocalizedImpl
parent: CMObjectImpl
interfaces:
  - CMLocalized

Fields

Fields are split into generic accessors to (scalar) UAPI content properties and methods and specialized accessors for more complex types, i.e. richtext or link lists.

Constant

Type Descriptor: !Constant

Properties:

  • name: The field's name.
  • value: A special SpEL expression defining the value. Expressions encapsulated with #{<expr>} are evaluated at schema loading time. Expressions encapsulated with ${<expr>} are evaluated at runtime. If no value expression is given null is returned.
  • typeName: The returned value's type.
  • nonNull: Optional constraint for the returned value.

Example:

- !Constant
  name: tag
  value: "#{'ROOT'}"
  typeName: String

A field with a constant scalar value.

Bean Property

Type Descriptor: !Property

Properties:

  • name: The fields's name.
  • sourceName: Optional SpEL expression for retrieving the value from the source object. The field's name is used as expression value if this property is not set.
  • typeName: The returned value's type.
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !Property
  name: _name
  sourceName: "name"
  typeName: String
  nonNull: true

Content Property

Type Descriptor: !ContentProperty

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for retrieving the value from the source object.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • typeName: The returned value's type.
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !ContentProperty
  name: title
  sourceName: "title"
  typeName: String

Blob

Type Descriptor: !Blob

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for retrieving the value from the source object.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !Blob
  name: data
  sourceName: "data"

The GraphQL object type of a blob is fixed and contains the following attributes:

  • contentType: The blob's MIME type.
  • size: The blob's size in bytes.

Richtext

Type Descriptor: !Richtext

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for retrieving the value from the source object.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • typeName: Must be set to String or RichtextTree (see Richtext).
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !Richtext
  name: detailText
  sourceName: "detailText"
  typeName: String

See Richtext for processing CoreMedia richtext properties.

Link

Type Descriptor: !Link

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for retrieving the link list property value from the source object. The first element (if any) from the list that matches the field's type is returned.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • typeName: The returned value's type.
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !Link
  name: picture
  sourceName: "pictures"
  typeName: CMPicture

Link List

Type Descriptor: !Linklist

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for the retrieving the link list property value from the source object.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • typeName: The returned value's list type (the interface/object type prefixed with List:).
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !Linklist
  name: pictures
  sourceName: "pictures"
  typeName: List:CMPicture

Extended Link List

Type Descriptor: !ExtendedLinklist

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for the retrieving the extended link list property value from the source object.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • typeName: The returned value's list type (the interface/object type prefixed with List:).
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

  - !ExtendedLinklist
    name: teaserTargets
    sourceName: "targets?.links"
    typeName: List:ExtendedTeaserTarget

Struct

Type Descriptor: !Struct

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for retrieving the struct value from the source object.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • typeName: The type name of the static object model that applies to the struct value.
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !Struct
  name: timeLine
  sourceName: "timeLine"
  typeName: TimeLine

If the return type of a Struct Field is a Struct itself, a static object type must be defined for accessing it's values. See the TimeLine and TimeLineEntry types in the sample schema for the returned object types.

URI Property

Type Descriptor: !Uri

Properties:

  • name: The field's name.
  • sourceName: SpEL expression for retrieving the value from the source object.
  • fallbackSources: Optional list of SpEL expressions which are evaluated if the original source expression yields null or an empty result.
  • typeName: The returned value's type (a string if using the example Link Builder).
  • nonNull: Optional constraint for the returned value.
  • directives: Optional list of directives to apply.

Example:

- !Uri
  name: link
  sourceName: "this"
  typeName: String

Bean

Type Descriptor: !Bean

Properties:

  • name: The field's name.
  • sourceName: The Spring bean's name.
  • fallbackSources: Optional list of source names passed to the bean.
  • typeName: The returned value's type.
  • nonNull: Optional constraint for the returned value.

Example:

- !Bean
  name: subject
  sourceName: "subjectBean"
  typeName: String

A bean field uses a generic data fetcher which delegates value retrieval to a named bean defined in the Spring context.

The bean must be a subclass of DataFetcherDelegateBean:

package com.coremedia.caas.schema.datafetcher.delegate;

//...

public interface DataFetcherDelegateBean {

  Object get(ContentProxy source, String sourceName, List<String> fallbackSourceNames, String typeName, DataFetchingEnvironment environment) throws Exception;
}

Metadata

Type Descriptor: !Meta

Properties:

  • name: The field's name.
  • typeName: Matching type for the selected field.
  • nonNull: Optional constraint for the returned value.

A metadata field returns internal schema information. Valid field names are:

  • __interfaces: List of all interface types implemented by the source object. Set typeName to List:String.
  • __baseinterface: The object's primary interface, e.g. CMLinkable for object type CMLinkableImpl. Set typeName to String.

Example:

- !Meta
  name: __baseinterface
  typeName: String
  nonNull: true

Types

Scalars

All scalar types of the graphql-java library are supported:

  • Boolean
  • BigDecimal
  • BigInteger
  • Byte
  • Char
  • Float
  • ID
  • Integer
  • Long
  • Short
  • String

Interface/Object Types

Interface types for content objects are named like their name in the document type model, e.g. CMLinkable.
Object types append Impl to their interface name, e.g. CMLinkableImpl.

Lists

List types are defined by using the base scalar or interface/object type prefixed with List:, e.g. List:String, List:CMLinkable.

Type Conversion

Limited type conversion is performed on scalar types using the default Spring type converters.

Source and Fallback Expressions

Unless otherwise noted SpEL is used for all for source and fallback expressions. See Spring Expression Language (SpEL) for more details.

Example fetching the view type name from a CMLinkable:

sourceName: "getLink('viewtype')?.layout"

If navigating through the object graph pay attention to the Safe Navigation operator to avoid NullPointerExceptions.

this

The special path expression this refers to the current object. It's used e.g. for generating links:

- !Uri
  name: link
  sourceName: "this"
  typeName: String

Directives

The schema supports the two directives if and filter which are the same as the ones applied to the queries. Directives in the schema always take precedence over directives defined in the queries.

Example:

- !Struct
  name: timeLine
  sourceName: (timeLine)
  typeName: TimeLine
  directives:
    - !Directive
      name: if
      arguments:
        test: "getLink('viewtype')?.layout == 'shoppable'"

Content Models

With the introduction of SpEL the specialized data fetchers for e.g. navigation and page grid access have been removed with with special model objects that are directly used in the SpEL expressions:

- !CustomField
  name: children
  sourceName: "$navigation().children"
  targetType: List:CMLinkable
  dataFetcher: ContentProperty
- !CustomField
  name: grid
  sourceName: "$pageGrid('placement')"
  targetType: PageGrid
  dataFetcher: ContentProperty

A model accessor looks like a regular method call with the method name prefixed with $. The following models are provided out of the box:

Navigation

$navigation()

Provides access to navigation related properties. Uses TreeRelation and ContextStrategy implementations from Blueprint Base.

Available methods on the returned model are:

  • isHidden: Hidden in navigation flag from the Blueprint model.
  • isHiddenInSitemap: Hidden in navigation and sitemap flag from the Blueprint model.
  • getContext: Navigational context.
  • getChildren: Navigational children.
  • getPathToRoot: Path to root page.

PageGrid

$pageGrid('<placement property name>')

Provides access to a page grid and it's placement.

Available methods on the returned model are:

  • getCssClassName: The class name store with the grid.
  • getPlacements: The list of placement models.

Placement models implement the following methods:

  • getName: The placement's name.
  • getViewtype: The placement's viewtype.
  • getItems: The items stored in the placement.

Settings

$settings()

Provides access to the SettingsService.

Available methods on the returned model are:

  • get(String propertyPath): Retrieves a setting with the given path.
  • get(String propertyPath, Object defaultValue): Retrieves a setting with the given path. Returns the default value if retrieved value is null.

The path segments in the given property path must be separated by /. A leading / is optional.

Example:

$settings().get('callToActionDisabled', false)

Extended Link List

$extendedLinks('<extended linklist property name>', '<legacy linklist property name>')

Provides access to the link target(s) of an extended link list or the legacy link list if the new property has not been written to yet.

Available methods on the returned model are:

  • target: The singleton or first valid target of the link list.
  • targets: All valid target of the link list.

This model is typically only required if you need to access properties from the target objects and not the link list itself. See the CMTeaserImpl type from the Sample Schema.

Clone this wiki locally