Schema Shortcode Guide

The WPSSO Core plugin provides support for hundreds of Schema types, and can read data from dozens of supported third-party plugins and service APIs. The most popular Schema properties can be customized easily in the Document SSO metabox, and if required, the [schema] shortcode can be used to define additional properties and types for sections of the content.

Please note that the [schema] shortcode is meant for advanced users only and is not required for WPSSO Core to create complete and accurate Schema JSON-LD markup for the content. You should avoid using the [schema] shortcode unless you're very familiar with https://schema.org markup and have very specific, non-standard requirements. If you use the [schema] shortcode, make sure you always validate any change with the Schema Markup Validator and the Google Rich Results Test tool.

The [schema] shortcode can be used to define additional properties for the content. The following example defines an 'articleSection' property for the Schema Article type. Note that all shortcode attributes are considered to be Schema property names, except for the 'prop' and 'type' attribute names, which have special meaning (see below).

[schema articleSection="Sports" /]

The [schema] shortcode can also be used to define a Schema type for a section of content, along with using that section of content for the Schema type description and its media properties. The following example defines a section of content as a Schema Map type. Please note that the 'type' value can be a WPSSO Schema type ID (as shown here) or a complete https://schema.org URL. When using the 'type' shortcode attribute, the 'prop' shortcode attribute is required (so the Schema type can be assigned to a Schema property). Note that WPSSO Core will automatically detect and include the image in the Schema map example content.

[schema prop="hasPart" type="map" name="Map of the World"]

        Here's a nice detailed map of the world.

        [caption id="attachment_1" align="alignnone" width="600"]

                <img src="http://example.com/wp-content/uploads/worldmap.jpg"
                        alt="A nice world map." width="600" height="600"
                        class="size-featured wp-image-1" data-wp-pid="1"
                        data-pin-nopin="nopin" />

                A nice world map.

        [/caption]

[/schema]

By default the [schema] shortcode replaces an existing Schema property value — if instead you want to add a new element to a Schema property array, prefix the 'prop' attribute value with a '+' sign. For example, the following shortcodes will create an 'offers' array with two price specifications (see below for additional notes on using nested shortcodes).

[schema prop="+offers" type="https://schema.org/Offer"]

	[schema_1 prop="priceSpecification"
		type="https://schema.org/UnitPriceSpecification"
		price="50.00" priceCurrency="USD" unitText="DAY" /]

[/schema]

[schema prop="+offers" type="https://schema.org/Offer"]

	[schema_1 prop="priceSpecification"
		type="https://schema.org/UnitPriceSpecification"
		 price="250.00" priceCurrency="USD" unitText="WEEK" /]

[/schema]

The resulting JSON-LD array:

"offers": [
    {
        "@context": "https://schema.org",
        "@type": "Offer",
        "priceSpecification": {
            "@context": "http://schema.org",
            "@type": "UnitPriceSpecification",
            "price": "50.00",
            "priceCurrency": "USD",
            "unitText": "DAY"
        }
    },
    {
        "@context": "https://schema.org",
        "@type": "Offer",
        "priceSpecification": {
            "@context": "http://schema.org",
            "@type": "UnitPriceSpecification",
            "price": "250.00",
            "priceCurrency": "USD",
            "unitText": "WEEK"
        }
    }
]

Please note that WordPress is not able to parse nested shortcodes, so the following shortcode structure is not supported by WordPress.

[schema]
        [schema]
        [/schema]
[/schema]

The WPSSO Schema Shortcode add-on does support nested shortcodes using a numeric extension to work around the WordPress limitation. The add-on supports up to three levels of nesting by default, as the following example illustrates.

[schema]
        [schema_1]
                [schema_2]
                        [schema_3]
                        [/schema_3]
                [/schema_2]
        [/schema_1]
[/schema]

Practical Examples

Customer Reviews

You can add and maintain customer reviews directly in the content using the following example, but a much better (and more scalable) solution is to use a proper content rating / review plugin like the WPSSO Ratings and Reviews add-on, which adds customer ratings, reviews, replies and aggregate ratings markup automatically. The WPSSO Core Premium plugin also supports ratings and reviews from the WooCommerce and WP-PostRatings plugins.

Note that we are using Schema type IDs from WPSSO in this example — using type="review" is the same as using type="https://schema.org/Review". Also note the use of a leading "+" sign in the first [schema] shortcode 'prop' attribute — this tells the plugin to add this property as an array, so several reviews can be included. The plugin handles nested shortcodes, but WordPress does not, so nested shortcodes must be numbered for WordPress (schema, schema_1, schema_2, etc.). Don't forget to terminate the shortcode enclosure — it can be easy to forget that closing [/schema] tag. ;-)

<dl>
<dt>John Doe said on June 25th, 2018:<dt>
<dd>

[schema prop="+review" type="review" dateCreated="2018-06-25T12:40:09+00:00"]

    [schema_1 prop="reviewRating" type="rating"
        ratingValue="4" worstRating="1" bestRating="5"/]

    [schema_1 prop="author" type="person" name="John Doe"/]

    An example review text.

[/schema]

Rating: 4/5

<dd>
<dl>

Aggregate Ratings

You can add and maintain aggregate rating values directly in the content using the following example, but a much better (and more scalable) solution is to use a proper content rating / review plugin. ;-) And in case you're using a non-supported rating / review plugin, that saves aggregate rating values in post meta, instead of using a shortcode you can also use a plugin filter to update the Schema aggregateRating property value.

[schema prop="aggregateRating" type="rating.aggregate"
    ratingValue="4" ratingCount="1" worstRating="1" bestRating="5"/]