@financial-times/cp-content-pipeline-schema 2.5.2 → 2.5.4

package/typedefs/image.graphql

@@ -1,135 +1,330 @@
 type ImageSource {
+  "The url of the image source, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String!
+
+  "The width of the image source in pixels."
   width: Int
+
+  "The device pixel ratio. DPR is calculated as DPR = Physical Pixels (pixels seen on screen) / Logical Pixels (pixel that can fit in a given space)."
   dpr: Int
 }
 
 interface Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
   width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageStandardInline implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
   width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageDesktop implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
   width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageMobile implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
   width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageStandard implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
   width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageSquare implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
-  width: Int
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
+  width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageWide implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
-  width: Int
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
+  width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageSquareFTEdit implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
-  width: Int
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
+  width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImagePortrait implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
-  width: Int
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
+  width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }
 
 type ImageLandscape implements Image {
+  "The unique identifier of the image -  a uuid or a url."
+  id: String!
+
+  "The type of the image, eg. 'graphic'."
   type: ImageType
+
+  "The format of the image, eg. 'portrait'."
   format: ImageFormat!
+
+  "An array of image sources, ie. different images to render based on input width resulting in responsive images."
   sourceSet(width: Int, maxDpr: Int): [ImageSource!]!
+
+  "The url of the image, eg. 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3Aimage%3A0e7e7b6e-4e7b-11e9-bde6-79e4b4311f90?source=next&fit=scale-down&width=700'."
   url: String
-  width: Int
+
+  "Text describing the content of the image, usually hidden from the user unless the image is not available. It is to be read by screen readers."
   altText: String
+
+  "The width of the image in pixels."
+  width: Int
+
+  "The height of the image in pixels."
   height: Int
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "Text describing the content of the image, always shown next to the image."
   caption: String
-  id: String!
 }

package/typedefs/picture.graphql

@@ -1,39 +1,92 @@
-interface Picture {
+"A wrapper for images." 
+interface Picture { 
+  "A set of images with different sizes and formats."
   images: [Image!]!
+
+  "The alt text of the image to be used for accessibility."
   alt: String!
+
+  "The caption of the image."
   caption: String
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "The layout width of the image, eg, 'standard'."
   layoutWidth: String
+
+  "The type of the image, eg. 'image' or 'graphic'."
   imageType: ImageType!
+
+  "A fallback image to be used if the 'images' are not available."
   fallbackImage: Image!
 }
 
 type PictureStandard implements Picture {
+  "A set of images with different sizes and formats."
   images: [Image!]!
+
+  "The alt text of the image to be used for accessibility."
   alt: String!
+
+  "The caption of the image."
   caption: String
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "The layout width of the image, eg, 'standard'."
   layoutWidth: String
+
+  "The type of the image, eg. 'image' or 'graphic'."
   imageType: ImageType!
+
+  "A fallback image to be used if the 'images' are not available."
   fallbackImage: Image!
 }
 
 type PictureInline implements Picture {
+  "A set of images with different sizes and formats."
   images: [Image!]!
+
+  "The alt text of the image to be used for accessibility."
   alt: String!
+
+  "The caption of the image."
   caption: String
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "The layout width of the image, eg, 'standard'."
   layoutWidth: String
+
+  "The type of the image, eg. 'image' or 'graphic'."
   imageType: ImageType!
+
+  "A fallback image to be used if the 'images' are not available."
   fallbackImage: Image!
 }
 
 type PictureFullBleed implements Picture {
+  "A set of images with different sizes and formats."
   images: [Image!]!
+
+  "The alt text of the image to be used for accessibility."
   alt: String!
+
+  "The caption of the image."
   caption: String
+
+  "The credit of the image, eg. 'Getty Images'."
   credit: String
+
+  "The layout width of the image, eg, 'standard'."
   layoutWidth: String
+
+  "The type of the image, eg. 'image' or 'graphic'."
   imageType: ImageType!
+
+  "A fallback image to be used if the 'images' are not available."
   fallbackImage: Image!
 }

package/typedefs/references/clipSet.graphql

@@ -1,19 +1,52 @@
 type ClipSet implements Reference {
+  "The unique identifier of the clip set."
+  id: String!
+
+  "The type of the clip set, eg. 'video'."
   type: String!
+
+  "Whether the clip should play automatically when loaded."
   autoplay: Boolean
+
+  "An object containing the accessibility details of the clip."
   accessibility: Accessibility
+
+  "Whether the clip should loop."
   loop: Boolean
+
+  "Whether the clip should be muted."
   muted: Boolean
+
+  "The layout of the clip set, eg. 'in-line'."
   dataLayout: String
-  id: String!
+
+  "Whether the clip set should **not** include audio."
   noAudio: Boolean
+
+  "Text describing the content of the clip, to be shown next to the clip."
   caption: String
+
+  "The credit text of the clip, eg. 'Getty Images'."
   credits: String
+
+  "The description of the clip."
   description: String
+
+  "The title to be displayed for the clip set."
   displayTitle: String
+
+  "An array of content warnings for the clip set."
   contentWarning: [String]
+
+  "The source of the clip set, eg. 'YouTube'."
   source: String
+
+  "The subtitle of the clip set."
   subtitle: String
+
+  "The date the clip set was published."
   publishedDate: String
+
+  "An array of clips in the clip set."
   clips: [Clip]
 }

package/typedefs/references/flourish.graphql

@@ -1,9 +1,17 @@
 type FlourishFallback {
+  "The url of the fallback image."
   url: String
+
+  "The width in pixels of the fallback image."
   width: Int
+
+  "The height in pixels of the fallback image."
   height: Int
 }
 type Flourish implements Reference {
+  "The type of the reference, eg. 'flourish'."
   type: String!
+
+  "The fallback image to be used if the flourish graphics cannot be loaded."
   fallbackImage: FlourishFallback
 }

package/typedefs/references/imageSet.graphql

@@ -1,9 +1,15 @@
 type ImageSet implements Reference {
+  "The type of the reference, eg. 'image-set'."
   type: String!
+
+  "A set of images with different sizes and formats."
   picture: Picture
 }
 
 type MainImage implements Reference {
+  "The type of the reference, eg. 'main-image'."
   type: String!
+
+  "A set of images with different sizes and formats."
   picture: Picture
 }

package/typedefs/references/layoutImage.graphql

@@ -1,4 +1,7 @@
 type LayoutImage implements Reference {
+  "The type of the reference, eg. 'layout-image'."
   type: String!
+
+  "A set of images with different sizes and formats."
   picture: Picture
 }

package/typedefs/references/rawImage.graphql

@@ -1,4 +1,7 @@
 type RawImage implements Reference {
+  "The type of the reference, eg. 'raw-image'."
   type: String!
+
+  "The raw image object."
   image: Image!
 }

package/typedefs/references/recommended.graphql

@@ -1,4 +1,7 @@
 type Recommended implements Reference {
+  "The type of the reference, eg. 'recommended'."
   type: String!
+
+  "Recommended references contain teaser thumbnails of related articles."
   teaser: Teaser
 }

package/typedefs/references/reference.graphql

@@ -1,3 +1,4 @@
 interface Reference {
+  "The type of the reference, eg. 'image-set'. References are additional data that cannot be loaded by content-tree. They will be appended to content-tree nodes during resolution."
   type: String!
 }

package/typedefs/references/scrollyImage.graphql

@@ -1,4 +1,7 @@
 type ScrollyImage implements Reference {
+  "The type of the reference, eg. 'scrolly-image'."
   type: String!
+
+  "A set of images with different sizes and formats."
   picture: Picture
 }

package/typedefs/references/tweet.graphql

@@ -1,4 +1,7 @@
 type Tweet implements Reference {
+  "The type of the reference, eg. 'tweet'."
   type: String!
+
+  "The raw HTML of the tweet."
   html: String
 }

package/typedefs/references/video.graphql

@@ -1,5 +1,10 @@
 type VideoReference implements Reference {
+  "The type of the reference, eg. 'video'."
   type: String!
+
+  "The unique identifier of the video -  a uuid or a url."
   id: String!
+
+  "The title of the video."
   title: String!
 }

package/typedefs/richText.graphql

@@ -1,11 +1,12 @@
-"""
-Describes the structure of content as an abstract syntax tree
-"""
+"Describes the structure of content as an abstract syntax tree."
+
 type StructuredContent {
   "bodyXML is converted to a json tree by bodyXMLtoTree(). tagMappings.ts provides the logic for node traversal."
   tree: JSON!
+
   "An array of objects containing extra information for nodes, which is fetched from external sources eg. Twitter API."
   references: [Reference!]!
+
   "The tree json as text."
   text: String
 }
@@ -13,8 +14,10 @@ type StructuredContent {
 type RichText {
   "The source format eg. bodyXML."
   source: RichTextSource!
-  "Raw string of the XML as returned from ContentAPI."
+
+  "Raw string of the XML as returned from content-api."
   raw: String
+
   "Content tree data with references."
   structured: StructuredContent!
 }

package/typedefs/teaser.graphql

@@ -1,28 +1,69 @@
 union MetaLink = Concept | ContentPackage
 
 type Teaser {
+  "The unique identifier of the teaser,  a uuid or a url."
+  id: String
+
+  "The url of the content that the teaser refers to."
   url(relative: Boolean): String!
+  
+  "The type of the teaser, eg. 'article' or 'video'."
   type: String
+
+  "The title of the teaser."
   title: String
-  id: String
+
+  "The image to be used as a thumbnail for the teaser."
   image: Image
+
+  "The date the content of the teaser was published."
   publishedDate: String
+
+  "The date the content of the teaser was first published."
   firstPublishedDate: String
+
+  "An object containing the metadata details of the teaser, eg. id, url, prefLabel."
   metaLink: MetaLink
+
+  "An object containing the metadata details of the teaser, eg. id, url, prefLabel."
   metaAltLink: MetaLink
+
+  "The text to be displayed before the metadata of the teaser."
   metaPrefixText: String
+
+  "The text to be displayed after the metadata of the teaser."
   metaSuffixText: String
+
+  "An object containing a map of indicator items to boolean values, eg. accessLevel, isOpinion."
   indicators: Indicators
+
+  "The theme to use for the teaser, eg. 'opinion' or 'news'."
   theme: String
+
+  "The introductory text of the teaser."
   standfirst: String
 }
 
+"Indicators are used to determine teaser styling."
 type Indicators {
+  "The access level of the teaser, eg. 'free' or 'premium'."
   accessLevel: AccessLevel
+
+  "Whether the teaser is an opinion piece."
   isOpinion: Boolean
+  
+  "Whether the teaser is a column, ie. has one author."
   isColumn: Boolean
+
+  "Whether the teaser is a podcast."
   isPodcast: Boolean
+
+  "Whether the teaser is an editor's choice."
   isEditorsChoice: Boolean
+
+  "Whether the teaser is exclusive."
   isExclusive: Boolean
+
+  "Whether the teaser is a scoop."
   isScoop: Boolean
 }