.. include:: /Includes.rst.txt

.. _introduction:

============
Introduction
============

.. contents:: Table of Contents
   :depth: 1
   :local:

.. _what-it-does:

What does it do?
================

Structured data is essential for search engine optimisation nowadays. This
extension allows the easy integration of structured data based on the
`schema.org vocabulary <https://schema.org/>`_ on a TYPO3 website. A good
introduction to the topic is provided by Google:
`Understand how structured data works <https://developers.google.com/search/docs/guides/intro-structured-data>`_.

The defined structured data is embedded on a web page in
`JSON-LD <https://json-ld.org/>`_ markup and can be checked with Google's
`Structured Data Testing Tool <https://search.google.com/structured-data/testing-tool>`_
and `Rich Results Test <https://search.google.com/test/rich-results>`_.

There are also browser extensions available which ease the testing of the
markup, e.g.
`Structured Data Testing Tool <https://chrome.google.com/webstore/detail/structured-data-testing-t/kfdjeigpgagildmolfanniafmplnplpl>`_
for Chrome.

For the differences between the versions have a look at the
`change log <https://github.com/brotkrueml/schema/blob/master/CHANGELOG.md>`_.

.. tip::

   There is a Slack channel #ext-schema on `typo3.slack.com
   <https://typo3.slack.com/>`_ for questions, suggestions, feedback, etc.


.. _vocabulary:

The schema.org vocabulary
=========================

Schema.org is a set of extensible schemas that enables webmasters to embed
structured data on their web pages for use by search engines and other
applications. The vocabulary is divided into different sections:

- The **core** vocabulary provides all default types and properties, like
  ``Person`` or ``Organization``.
- The **pending** section is a staging area for work-in-progress terms which
  have yet to be accepted into the core vocabulary.
  `Pending terms <https://schema.org/docs/pending.home.html>`_ are subject
  to change and should be used with caution. On the schema.org website they
  are displayed in a blue colour.
- The **auto** section provides additional terms related to
  `auto <https://schema.org/docs/auto.home.html>`_.
- The **bib** section provides additional terms related to
  `bibliography <https://schema.org/docs/bib.home.html>`_.
- The **health-lifesci** section provides additional terms related to
  `health and lifesciences <https://schema.org/docs/health-lifesci.home.html>`_.

.. note::
   This TYPO3 schema extension provides the terms for the core vocabulary. To
   use terms from other sections you can extend the vocabulary on your own as
   described in the :ref:`according chapter <extending-vocabulary>` or use one
   of the additional TYPO3 extensions provided by the author of this extension:

   - `schema_auto <https://extensions.typo3.org/extension/schema_auto>`_
   - `schema_bib <https://extensions.typo3.org/extension/schema_bib>`_
   - `schema_health <https://extensions.typo3.org/extension/schema_health>`_
   - `schema_pending <https://extensions.typo3.org/extension/schema_pending>`_

The schema.org vocabulary is evolving, approx. every 2-3 months a new version
is `released <https://schema.org/docs/releases.html>`_. The TYPO3 extensions are
updated when changes are made to the according vocabulary. The classes for the
type models and view helpers are generated by the `schema-generator
<https://github.com/brotkrueml/schema-generator>`_ library.

.. _release-management:

Release management
==================

This extension uses `semantic versioning <https://semver.org/>`_ which
basically means for you, that

* Bugfix updates (e.g. 1.0.0 => 1.0.1) just includes small bug fixes or security
  relevant stuff without breaking changes.
* Minor updates (e.g. 1.0.0 => 1.1.0) includes new features and smaller tasks
  without breaking changes.
* Major updates (e.g. 1.0.0 => 2.0.0) breaking changes which can be
  refactorings, features or bug fixes.