Specifying semantics on Schemas

You can map existing Schemas to existing View Models without changing the View Model semantics by applying Semantic annotations on the Schema and Schema fields.

About this task

The information is stored in the Schema application data and XSD (not currently viewable in the Content Manager). In this way you can mark Schema fields with semantic meaning, either using a public vocabulary like Schema.org, or a private vocabulary like the core DXA Schema namespace). When you have annotated Schema fields, the annotation is taken into account when trying to match View Model properties with Schema fields.

Procedure

  1. Add a system wide (global) application data containing the different vocabularies you will use: the format of the application data is XML containing vocabulary elements with a prefix and a name attribute, for example :
    <vocabularies>
        <vocabulary prefix="s" name="http://schema.org/"/>
        <vocabulary prefix="lib" name="http://purl.org/library/"/>
    </vocabularies> 

    The Application ID used for this system wide application data is: http://www.sdl.com/tridion/SemanticMapping/vocabularies

  2. Add application data to the Schema on which you want to add Semantic annotations containing the semantic type for each of the vocabularies you want to use: the format of this application data is XML containing a typeof element with in there a comma separated list of vocabulary types.
    For example, to map a Schema to schema.org Article and purl.org Library Thesis:
    <typeof>s:Article,lib:Thesis</typeof>

    The Application ID used for the Schema application data is: http://www.sdl.com/tridion/SemanticMapping/typeof

  3. Map the Schema fields via Schema annotation using the ExtensionXml on a field.
    For example, if we assume the above-mentioned Schema has a field TextField which must map to the headline of a schema.org Article and the title to a purl.org Library Thesis, in Content Manager open the Schema and go to the Source tab to view the following XML/XSD:
    ...
        <xsd:element name="TextField" minOccurs="1" maxOccurs="1" type="xsd:normalizedString">
            <xsd:annotation>
                <xsd:appinfo>
                    <tcm:ExtensionXml xmlns:tcm="http://www.tridion.com/ContentManager/5.0"></tcm:ExtensionXml>
                </xsd:appinfo>
            </xsd:annotation>
        </xsd:element>
    ...
  4. Inside the ExtensionXml element, add a property element (in the http://www.sdl.com/tridion/SemanticMapping namespace) specifying the semantic mapping of that field.

    Additionally, you can also add a typeof element here in case the type of this field does not match the type(s) specified in the Schema application data, for example:

    ...
        <xsd:element name="TextField" minOccurs="1" maxOccurs="1" type="xsd:normalizedString">
            <xsd:annotation>
                <xsd:appinfo>
                    <tcm:ExtensionXml xmlns:tcm="http://www.tridion.com/ContentManager/5.0">
                        <property xmlns="http://www.sdl.com/tridion/SemanticMapping">s:headline,lib:title</property>
                        <!-- optionally specify the type, only required if it does not match the type(s) set in the Schema application data -->
                        <typeof xmlns="http://www.sdl.com/tridion/SemanticMapping">s:Article,lib:Thesis</typeof>
                    </tcm:ExtensionXml>
                </xsd:appinfo>
            </xsd:annotation>
        </xsd:element>
    ...
    You can only set system wide and Schema application data through the available SDL Tridion APIs, for example in a Custom Page. For an (open source) example, see: https://github.com/bkoopman/sdl-tridion-world/tree/master/AppData%20Custom%20Page/trunk.
  5. Refresh the Web application settings:
    1. Go to the Home/_System Structure Group.
    2. Select the Publish Settings Page and click Publishing > Publish.
    3. Go to your Web application and enter the URL /admin/refresh refresh the cache and reload the settings in the Web application.