Schema Shortcode Guide

The WPSSO Schema JSON-LD Markup add-on provides extensive support for hundreds of Schema types and the WPSSO Core Premium plugin can pull information 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 necessary, the [schema] shortcode can also be used to define additional (non-standard) properties and types for sections of your content.

PLEASE NOTE that the [schema] shortcode is meant for advanced users only and is not required for WPSSO Core and WPSSO JSON to create complete and accurate Schema JSON-LD markup for your content. You should not use the [schema] shortcode unless you're familiar and comfortable with markup - and have a very specific / non-standard requirement. If you use the [schema] shortcode, make sure you always validate any change with 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).

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 URL. When using the 'type' shortcode attribute, the 'prop' shortcode attribute is required (so the Schema type can be assigned to a Schema property). WPSSO JSON will automatically detect and include the example image in the Schema Map content.

By default, the [schema] shortcode merges / repaces existing Schema property values - if instead you want to add a new element to the 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).

The resulting JSON-LD array:

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

The WPSSO JSON add-on does support nested shortcodes, but a numeric extension must be used to work around the WordPress limitation. WPSSO JSON supports up to 3 levels of nesting (by default), as the following example illustrates.

Practical Examples

Customer Reviews

You can add (and maintain) customer reviews in your content manually using this 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're using Schema type IDs from WPSSO in this example - using type="review" is the same as using type="". Also note the use of a leading "+" sign in the first [schema] shortcode 'prop' attribute - this tells WPSSO JSON to add this property as an array, so several reviews can be included this way. WPSSO JSON 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. ;-)

Aggregate Ratings

Again, you can add (and maintain) aggregate rating values in your content manually using this 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.