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

package/typedefs/content.graphql

@@ -1,248 +1,653 @@
-interface Content {
-  title: String!
-  id: ID!
-  type: ContentType!
-  standfirst: String
-  topper: Topper
-  body: RichText
-  bodyXML: String
-  url(vanity: Boolean, relative: Boolean): String!
-  publishedDate: String!
-  firstPublishedDate: String!
-  mainImage: Image
-  altTitle: AltTitle
-  altStandfirst: AltStandfirst
-  byline(vanity: Boolean): StructuredContent
-  teaser: Teaser
-  annotations: [Concept]
-  editorialDesk: String
-  accessLevel: AccessLevel
-  instantAlertConcept: Concept
-  canBeSyndicated: CanBeSyndicated
-  originatingParty: String
-  commentsEnabled: Boolean
-  design: Design
-}
-
 type Design {
+  "A scalar representing the theme of the design, eg. 'extra-wide'."
   theme: PackageDesign
+
+  "The layout, eg. 'default'."
   layout: String
 }
 
 type AltTitle {
+  "A promotional title of the article."
   promotionalTitle: String
 }
 
 type AltStandfirst {
+  "An introductory paragraph of the article."
   promotionalStandfirst: String
 }
 
 type Media {
+  "The url of the media, eg. 'https://next-media-api.ft.com/renditions/16868569859480/0x0.mp3'."
   url: String
+
+  "The duration of the media in milliseconds."
   duration: Int
+
+  "The filesize of the media in bytes."
+  
   filesize: Int
+
+  "The media type eg. video/mp4."
   mediaType: String
 }
 
 type TableOfContents {
+  "The formatting of the label, eg. 'part-number'."
   labelType: String
+
+  "The ordering, eg. 'exact-order'."
   sequence: String
 }
 
+type Indicators {
+  "Whether the content is an opinion piece."
+  isOpinion: Boolean
+}
+
+interface Content {
+  "The unique identifier of the article -  a uuid or a url."
+  id: ID!
+
+  "The title of the article."
+  title: String!
+
+  "The type of the article, eg. 'Article' or 'Video'."
+  type: ContentType!
+
+  "An introductory paragraph of the article."
+  standfirst: String
+
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
+  topper: Topper
+
+  "An abstract syntax tree of the article content."
+  body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
+  bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
+  url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
+  publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
+  firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
+  mainImage: Image
+
+  "An alternative title of the article."
+  altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
+  altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
+  byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
+  teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
+  annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
+  editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
+  accessLevel: AccessLevel
+
+  "The concept to use for instant alert CTAs."
+  instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
+  originatingParty: String
+
+  "Whether comments are enabled on the article."
+  commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
+  design: Design
+}
+
 type Article implements Content {
+  "The title of the article."
   title: String!
+
+  "The unique identifier of the article -  a uuid or a url."
   id: ID!
+
+  "The type of the article, eg. 'Article' or 'Video'."
   type: ContentType!
+
+  "An introductory paragraph of the article."
   standfirst: String
+  
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
   topper: Topper
+
+  "An abstract syntax tree of the article content."
   body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
   bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
   url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
   mainImage: Image
+
+  "An alternative title of the article."
   altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
   altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
   byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
   teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
+  
   annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
   editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
   accessLevel: AccessLevel
-  canBeSyndicated: CanBeSyndicated
+
+  "The concept to use for instant alert CTAs."
   instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
   originatingParty: String
+
+  "Whether comments are enabled on the article."
+  
   commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
   design: Design
+
+  "The parent article, indicating this article is a part of a series or package."
   containedIn: Content
 }
 
 type Placeholder implements Content {
+  "The title of the article."
   title: String!
+
+  "The unique identifier of the article -  a uuid or a url."
   id: ID!
+
+  "The type of the article, eg. 'Article' or 'Video'."
   type: ContentType!
+
+  "An introductory paragraph of the article."
   standfirst: String
+  
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
   topper: Topper
+
+  "An abstract syntax tree of the article content."
   body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
   bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
   url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
   mainImage: Image
+
+  "An alternative title of the article."
   altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
   altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
   byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
   teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
   annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
   editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
   accessLevel: AccessLevel
-  canBeSyndicated: CanBeSyndicated
+
+  "The concept to use for instant alert CTAs."
   instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
   originatingParty: String
+
+  "Whether comments are enabled on the article."
   commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
   design: Design
+
+  "The parent article, indicating this article is a part of a series or package."
   containedIn: Content
 }
 
 type LiveBlogPackage implements Content {
+  "The title of the article."
   title: String!
+
+  "The unique identifier of the article -  a uuid or a url."
   id: ID!
+
+  "The type of the article, eg. 'Article' or 'Video'."
   type: ContentType!
+
+  "An introductory paragraph of the article."
   standfirst: String
+  
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
   topper: Topper
+
+  "An abstract syntax tree of the article content."
   body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
   bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
   url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
   mainImage: Image
+
+  "An alternative title of the article."
   altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
   altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
   byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
   teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
   annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
   editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
   accessLevel: AccessLevel
-  canBeSyndicated: CanBeSyndicated
+
+  "The concept to use for instant alert CTAs."
   instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
   originatingParty: String
+
+  "Whether comments are enabled on the article."
   commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
   design: Design
+
+  "The child articles of this live blog package."
   liveBlogPosts(includePinned: Boolean @deprecated(reason: "avoiding breaking change, will remove argument on next major release")): [Content]
+  
+  "The pinned article of this live blog package."
   pinnedPost: Content
+
+  "Whether the live blog package should be updated in real time."
   realtime: Boolean
 }
 
 type LiveBlogPost implements Content {
+  "The title of the article."
   title: String!
+
+  "The unique identifier of the article -  a uuid or a url."
   id: ID!
+
+  "The type of the article, eg. 'Article' or 'Video'."
   type: ContentType!
+
+  "An introductory paragraph of the article."
   standfirst: String
+  
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
   topper: Topper
+
+  "An abstract syntax tree of the article content."
   body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
   bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
   url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
   mainImage: Image
+
+  "An alternative title of the article."
   altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
   altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
   byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
   teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
   annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
   editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
   accessLevel: AccessLevel
-  canBeSyndicated: CanBeSyndicated
+
+  "The concept to use for instant alert CTAs."
   instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
   originatingParty: String
+
+  "Whether comments are enabled on the article."
   commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
   design: Design
+
+  "The parent article, indicating this article is a part of a series or package."
   containedIn: Content
+
+  "An object indicating whether the article is an opinion piece."
   indicators: Indicators
+
+  "Whether the live-blog-post should be pinned."
   isPinned: Boolean
 }
 
 type Audio implements Content {
+  "The title of the article."
   title: String!
+
+  "The unique identifier of the article -  a uuid or a url."
   id: ID!
+
+  "The type of the article, eg. 'Article' or 'Video'."
   type: ContentType!
+
+  "An introductory paragraph of the article."
   standfirst: String
+  
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
   topper: Topper
+
+  "An abstract syntax tree of the article content."
   body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
   bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
   url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
   mainImage: Image
+
+  "An alternative title of the article."
   altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
   altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
   byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
   teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
   annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
   editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
   accessLevel: AccessLevel
-  canBeSyndicated: CanBeSyndicated
+
+  "The concept to use for instant alert CTAs."
   instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
   originatingParty: String
+
+  "Whether comments are enabled on the article."
   commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
   design: Design
+
+  "An array of media objects containing the url, the duration, the filesize and the media type."
   media: [Media]
 }
 
 type Video implements Content {
+  "The title of the article."
   title: String!
+
+  "The unique identifier of the article -  a uuid or a url."
   id: ID!
+
+  "The type of the article, eg. 'Article' or 'Video'."
   type: ContentType!
+
+  "An introductory paragraph of the article."
   standfirst: String
+  
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
   topper: Topper
+
+  "An abstract syntax tree of the article content."
   body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
   bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
   url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
   mainImage: Image
+
+  "An alternative title of the article."
   altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
   altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
   byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
   teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
   annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
   editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
   accessLevel: AccessLevel
-  canBeSyndicated: CanBeSyndicated
+
+  "The concept to use for instant alert CTAs."
   instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
   originatingParty: String
+
+  "Whether comments are enabled on the article."
   commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
   design: Design
 }
 
 type ContentPackage implements Content {
+  "The title of the article."
   title: String!
+
+  "The unique identifier of the article -  a uuid or a url."
   id: ID!
+
+  "The type of the article, eg. 'Article' or 'Video'."
   type: ContentType!
+
+  "An introductory paragraph of the article."
   standfirst: String
+  
+  "A banner located usually at the top of articles containing the title, the standfirst and any images."
   topper: Topper
+
+  "An abstract syntax tree of the article content."
   body: RichText
+
+  "The raw string of the XML as returned from ContentAPI."
   bodyXML: String
+
+  "The url of the concept. Vanity urls replace long, randomly generated urls - they are more user friendly and concise. Relative urls are relative to the current domain."
   url(vanity: Boolean, relative: Boolean): String!
+
+  "The ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   publishedDate: String!
+
+  "The first ISO string date the article was published, eg. '2024-04-03T10:35:52.443Z'."
   firstPublishedDate: String!
+
+  "An image object containing the url and the caption, to be displayed usually before the article content."
   mainImage: Image
+
+  "An alternative title of the article."
   altTitle: AltTitle
+
+  "An alternative introductory paragraph of the article."
   altStandfirst: AltStandfirst
+
+  "An abstract syntax tree of the authors of the article."
   byline(vanity: Boolean): StructuredContent
+
+  "A promotional thumbnail / snapshot of the article."
   teaser: Teaser
+
+  "An array of concepts related to the article, eg. organisations or topics."
   annotations: [Concept]
+
+  "The editorial division the article belongs to, eg. 'FT-SpecialReports'."
   editorialDesk: String
+
+  "A scalar representing the access level of the article, eg. 'free'."
   accessLevel: AccessLevel
-  canBeSyndicated: CanBeSyndicated
+
+  "The concept to use for instant alert CTAs."
   instantAlertConcept: Concept
+
+  "A scalar representing whether the article can be syndicated, ie. published by a third party site."
+  canBeSyndicated: CanBeSyndicated
+
+  "The party that originated the article, eg. 'FT'."
   originatingParty: String
+
+  "Whether comments are enabled on the article."
   commentsEnabled: Boolean
+
+  "A design object containing the theme and layout of the article."
   design: Design
+
+  "The child articles of this content package."
   contains(fromId: String, surroundingArticles: Int): [Teaser]
+
+  "The number of child articles in this content package."
   containsLength: Int
+
+  "The optional table of contents for this content package."
   tableOfContents: TableOfContents
 }
 
-type Indicators {
-  isOpinion: Boolean
-}
+

package/typedefs/core.graphql

@@ -1,11 +1,17 @@
 scalar JSON
 
 type Query {
+  "The version of the schema, eg. 2.0.0."
   version: String!
+
+  "The resolved article content for given uuid."
   content(uuid: String!): Content!
+
+  "The article content as resolved from passed-in content-api json data."
   contentFromJSON(content: JSON!): Content!
 }
 
 type Mutation {
+  "A mutation to invalidate the redis cache for content-api responses for a given uuid."
   invalidateRedisCache(uuid: String!): String
 }