Anatomy of a Component Schema

Description

Every component can (and should) have a root-level _description in its schema, which contains markdown-formatted text describing the purpose and use of the component. Descriptions look like this:

_description: |
  A short description of the component.

  A more detailed overview of functionality and business use cases, intended
  for an audience of writers, editors, and other CMS end users. It may include:

  * plain english descriptions of any non-obvious functionality
  * suggested workflows and advanced features
  * non-obvious interactions with other components

Descriptions will appear in Kiln when users click/tap the info icon in components' mini-selector.

Developer Description

If the component has information that's useful for developers, but not end users, add a root-level _devDescription. It works the same as _description, but will not display in Kiln (only in component README files).

_description: |
  A more detailed overview of functionality, maintenance information, and 
  developer/designer use cases, intended for an audience of devs, designers, 
  and product managers. It may include:

  * lists of workflows, functional requirements, business justifications
  * intentions of the author and situations that are explicitly unsupported
  * developer-focused information on certain fields that's not appropriate for user-facing field descriptions

Versioning

Components should also have a root-level _version that allows their data to be updated.

Example Layout Schema

_description: |
  A two column layout with styling for our articles. Used for:

  * regular article pages
  * sponsored posts
  * featured articles

head:
  _componentList:
    page: true
    include:
      - meta-title
      - meta-url
      - meta-description
      - meta-authors
      - meta-image
pageHeader:
  _componentList:
    include:
      - simple-header (not:di)
      - di-header (di)
      - top-stories
main:
  _componentList:
    page: true
    include:
      - article
      - video-promo-for-articles
belowMain:
  _componentList:
    include:
      - comments
      - latest-news
sidebar:
  _componentList:
    include:
      - ad
      - greatest-hits
      - masthead
      - newsletter-signup
bottom:
  _componentList:
    include:
      - ad
      - global-footer
foot:
  _componentList:
    invisible: true
    include:
      - omniture
      - mixpanel
      - affiliate-links
      - facebook-pixel
kilnInternals:
  _componentList:
    internals: true
    include:
      - clay-kiln
      - clay-space-edit

Example Twitter Embed Schema

_description: |
  Embeds a tweet via the tweet’s URL.

url:
  _label: Tweet Url
  _display: inline
  _placeholder:
    height: 50
    text: Tweet Embed
  _has:
    - label
    -
      fn: text
      type: url
      placeholder: https://twitter.com/username/status/id
showThread:
  _label: Show Thread
  _display: settings
  _has:
    - label
    -
      fn: description
      value: Show or collapse the thread of tweets, if this tweet is a reply to a thread. (shows by default)
    -
      fn: checkbox
      label: Show thread of tweets
showMedia:
  _label: Show Media
  _display: settings
  _has:
    - label
    -
      fn: description
      value: Show or hide embedded media in the tweet. (shows by default)
    -
      fn: checkbox
      label: Show media in tweet