Make the structured data methods API-friendly

[sybrew]

From jmikrut's request:

Make the structured data functions API-friendly; where developers can supply a custom query to generate the outcome: [ 'id' => 1, 'taxonomy' => 'category' ]

See rework-family: #166

[sybrew]

Make the generators' output hook-able; whereafter other developers can modify the current array of data, and even add to them before it's being converted to a JSON-LD script.

For example, as we now do for the SEO Bar: https://github.com/sybrew/the-seo-framework/blob/3326e9f8e6bb8de2b93f12b47f6e752568f0046d/inc/classes/interpreters/seobar.class.php#L116-L148

---

Edit: I overlooked that we already have a filter in place.

The following filter is for editing the current structured data. It suffices, although it isn't as powerful as the one for the SEO Bar.

add_filter( 'the_seo_framework_receive_json_data', function( $data, $key ) {

    switch ( $key ) :
        case 'WebSite':
            break;

        case 'Links':
            break;

        // We used to have more than one script. Now it's just 0, nothing else.
        case 'Breadcrumb_0':
            break;

        default:
            break;
    endswitch;

    return $data;
}, 10, 2 );

[sybrew]

Since we already have a filter in place, and since we have no other structured data markup planned, this issue can wait.

When we tackle #276 and #407, it would be wise to implement the proposed implementation here as well.

[sybrew]

Filters the_seo_framework_schema_entity_builders and the_seo_framework_schema_graph_data allow for modifying, trimming, and adding to the structured data to our new Schema.org @graph.

Function tsf()->schema() provides a bridge between the generators via a property: $entities. For example, to create a dynamic reference to the Author entity generator, you call:

$entity['author'] = &tsf()->schema()->entities['Author']::get_dynamic_ref()

This dynamic reference is cool: If it's called once, it'll write the Schema.org entity to the caller. If it's called more than once (by you or something else), every caller gets dynamically replaced with an @id reference, and the entity is then queued to be appended to the graph. This cleans up nicely.

If you want a static id reference, without all the fancy rewriting, use this:

$entity['author'] = &tsf()->schema()->entities['Author']::get_instant_ref()

That code is referenced here: https://github.com/sybrew/the-seo-framework/blob/bf0ac1e963c74a7d9c26c225979330ad2a7fb1f1/inc/classes/meta/factory/schema/entities/reference.class.php#L70-L72

All graph data goes through our new function The_SEO_Framework\Utils\scrub_array(), which scrubs the array from any empty fields. Integer 0 and string '0' are the only empty fields accepted (null, false, [], etc. are scrubbed). The scrubber changes all single-index lists to a string, so [ 'thing' ] becomes 'thing', but [ 'key' => 'thing' ] remains, and so will [ 'thing', 2 ] remain.

All functions support our $args system, which I believe is now (finally, after 5 years of conception applied consistently throughout the entire public generator API. There's one minor tweak -- the Author entity generator also supports, next to null, id, taxonomy (provisioned to change to tax), and pta, also author_id (name pending... may become uid). I will likely add support for this ID to all functions in a future update (when we add all sorts of Authorial data).

I will detail all this in a future post; I'll likely pen down my thoughts and share tricks and tweaks in a KB article.

All Extension Manager extensions are incompatible with this new system; since 4.3.0 (probably relabeling to 5.0) is so large, I just need some time to rest, and I'll only patch the deprecation notices. So, even I won't have real experience with the new API once it launches. Bear with me once it does.

[Dade88]

I hope it is not an issue to revive this, but would like to know how we could add data to a Person or Organization using current TSF schema.org API.

A starting point at least to understand where to go if we want to add a knowsAbout or alumniOf, for example.

[Dade88]

Found my way using TSF, amazing!

[sybrew]

Howdy @Dade88,

Person and Organization are automatically populated based on your WordPress settings, The SEO Framework settings, and Post meta.

But, you can filter the_seo_framework_schema_graph_data to modify the structured data. You can see how I use it in an advanced way here: https://github.com/sybrew/tsf-snippets/blob/main/schema/tsf-image-graph.php. Here's a simpler, more direct approach to manipulating the data: https://github.com/sybrew/the-seo-framework/issues/663#issuecomment-1926121676.

In the next update, the_seo_framework_schema_queued_graph_data will also be available for even more advanced manipulation (i.e., reference-based). Our Extension Manager plugin will hook into that, thus providing a perfect example of the API.