Edit online

How to Generate Google Structured Data

It is possible to generate Google Structured Data (<script> elements that contain a JSON-LD object) in the DITA WebHelp Responsive output. Google uses this JSON-LD object to better understand the contents of the page and display special search results in a Google Search.
Tip: For more details, see Google Search Central: Understand how structured data works.
To generate Google Structured Data in WebHelp output, use the following transformation parameter:
google.structured.data
Specifies whether or not Google Structured Data will be generated in the output. If set to yes, the transformation automatically generates Google Structured Data for Questions and Answers topics, DITA Task topics, and from <data> elements found inside a topic that has the @name="oxy:question" construct. If set to no (default value), the transformation will not generate Google Structured Data.

Generating Google Structured Data for DITA Tasks Topics

When Google Structured Data is enabled, the DITA Task <title>, <shordesc>, and <step> elements are mapped to the HowTo JSON-LD object. For example, the following DITA Task topic:
<task id="task_id">
  <title>My task</title>
  <shortdesc>Task description</shortdesc>
  <steps>
    <step>
      <cmd>Step 1 content.</cmd>
    </step>
    <step>
      <cmd>Step 2 content.</cmd>
    </step>
  </steps>
</task>
will generate the following structure in the output:
<script type="application/ld+json" id="jsonld-howto">
  {
    "@context": "https://schema.org",
    "@type": "HowTo",
    "name": "My task",
    "description": "Task description",
    "supply": [],
    "tool": [],
    "step":[
      {
        "@type": "HowToStep",
        "text": "<span class=\"topic/ph task/cmd ph cmd\">Step 1 content.</span>"
      }
      ,
      {
        "@type": "HowToStep",
        "text": "<span class=\"topic/ph task/cmd ph cmd\">Step 2 content.</span>"
      }
    ]
  }
</script>

Generating for Questions and Answers Topics

When Google Structured Data is enabled, the QA topic <qagroup> elements are mapped to the FAQPage JSON-LD object. For example, the following QA topic:
<qatopic id="qa_id">
  <title>Faq Page 1</title>
  <qabody>
    <qagroup>
      <question>What is a car engine?</question>
      <answer>The car engine is a device that uses fuel to create mechanical power that can
              turn the car's wheels.</answer>
    </qagroup>
  </qabody>
</qatopic>
will generate the following structure in the output:
<script type="application/ld+json" id="jsonld-faq">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "What is a car engine?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "<div class=\"- topic/div qatopic/answer div answer\">The car engine is a 
device that uses fuel to create mechanical power that can turn the car's wheels.</div>"
        }
      }
    ]
  }
</script>

Generating from data elements found inside a topic

When Google Structured Data is enabled, the WebHelp Responsive transformation will map the <data> elements found inside a topic to a FAQPage JSON-LD object. There are 2 different use cases depending on where the <data> element is found in the document:
  • In the <prolog> element. For example, this content:
    <concept id="lawnmowerconcept">
  <title>Lawnmower</title>
  <shortdesc>The lawnmower is a machine used to cut grass in the yard.</shortdesc>
  <prolog>
    <metadata>
      <data name="oxy:question">What tools are necessary to cut the grass?</data>
    </metadata>
  </prolog>
  <conbody>
    <p>Lawnmowers can be electric, gas-powered, or manual.</p>
  </conbody>
</concept>
    will generate the following structure in the output:
    <script type="application/ld+json" id="jsonld-faq">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "What tools are necessary to cut the grass?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "<div class=\"- topic/body concept/conbody body conbody\">
                     <p class=\"- topic/shortdesc shortdesc\">The lawnmower is a machine 
used to cut grass in the yard.</p> <p class=\"- topic/p p\">Lawnmowers can be electric, 
gas-powered, or manual.</p> </div>"
        }
      }
    ]
  }
</script>
    Important: The answer represents the HTML result of the entire content inside the topic.
  • Inside the topic body elements. For example, content:
    <topic id="concept-id">
  <title>Morning</title>
  <shortdesc>In the morning we have breakfast.</shortdesc>
  <body>
    <ul>
      <data name="oxy:question">What do people drink in the morning?</data>
      <li>Tea</li>
      <li>Milk</li>
    </ul>
  </body>
</topic>
    will generate the following structure in the output:
    <script type="application/ld+json" id="jsonld-faq">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "What do people drink in the morning?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "<div class=\"- topic/body body\"><ul class=\"- topic/ul ul\"></ul> 
<li class=\"- topic/li li\">Tea</li> <li class=\"- topic/li li\">Milk</li> </div>"
        }
      }
    ]
  }
</script>
    Important: The answer represents the HTML result of the entire block where the <data> element is located inside.