Inject JSON-LD into AEM Edge Delivery Services with BYOM

It has been a few months since my last post. Things have changed at work and our marketing technology roadmap was recently scrapped. Without a major project to focus on, finding exciting topics to write about has been a bit of a challenge.

Despite the quiet period, I have stayed busy. I have spent time learning GitHub Copilot and using Generative AI for all sorts of tasks. It has helped me update my resume, build presentations, and do comparison shopping. Even cooking. Last night my kids asked "What's for dinner?" I replied "ChatGPT soup!" It is even helping me write this post. Before you ask, no, it is not as simple as telling ChatGPT to write a blog for me. It still takes a lot of human direction to get the details right.

On one of these quiet days I turned my focus to AEM Edge Delivery Services. I wanted to explore a feature called Bring Your Own Markup, or BYOM, and how you can use it to inject JSON-LD into a page.

Introducing BYOM and JSON-LD

Even though my work with AEM has paused for now, I am still having great conversations about it. One idea was to look into how to inject JSON-LD into AEM Edge Delivery Services. I started digging into the details using Google Gemini. After some time, I felt like I had enough to share a helpful story.

JSON-LD is a key part of Generative Engine Optimization (GEO). It helps machines understand your content in a clear way. Instead of guessing from HTML, systems can read structured data. This includes things like products, events, and locations. It removes confusion and helps AI systems use your data in their answers.

Bring Your Own Markup, or BYOM, is a pattern in AEM Edge Delivery Services. It gives you control over how HTML gets created. With BYOM, you use your own backend to return HTML that Edge Delivery Services will process.

This makes BYOM a good fit for JSON-LD. Instead of trying to add structured data on the client side, it gets injected into the source content. This matters because crawlers and AI systems read the page as it arrives. If JavaScript adds JSON-LD after the page loads, crawlers and AI systems may miss it. This follows the composable approach in Edge Delivery. Tasks that used to happen inside AEM Publisher now happen in separate services outside of it.

Setting Up a Content Endpoint for Testing

For this experiment, I needed a simple content source.

A BYOM source can be anything that returns HTML. It can be dynamic, like a service that combines content from different sources. Or it can be static. Luckily, we have a solid reference implementation for this: the Adobe Commerce Prerender solution, which stores static HTML in cloud storage.

For my setup, I chose the simplest path. I created a static website using Azure Blob Storage and uploaded a few HTML files that match the Edge Delivery boilerplate.

Here is what my setup looked like.

First, a script to create the storage account and enable static hosting:

Next, a script to upload the HTML files to BLOB storage:

And finally, the sample HTML files. These follow the boilerplate structure, with:

nav.html

index.html

footer.html

At this point, I have a working content source that I can use with BYOM.

BYOM as a Content Source

Now that I have a static content source, the first thing I will test is BYOM as the primary content source. The concept is simple. Out of the box, Adobe supports four sources: SharePoint, Google Docs, Document Authoring (DA) and AEM (aka Crosswalk). Say you have a legacy CMS, or you are already happy with WordPress. You can still take advantage of Edge Delivery Services. All you need to do is write your middleware layer to translate the source to the semantic HTML ingested by EDS.

Here is how I switched my content source over.

You will need to use the Admin API to change the content source. First, get an X-Auth-Token. Then write a cURL command to update the boilerplate configuration. If you need help getting started with the Admin API, read my post here. Or watch this video from Jack Jin if you want to dive into an agentic AI alternative for working with the Admin API.

In my case, I’m pressed for time so I’ll stick to the tried and true method of using cURL :-)

Once my content source gets updated, I need to update preview with the content. That is, I send a message to EDS telling it the content is ready to get ingested into either preview (or publish). In this case, I will send the command to ingest each page (nav, index and footer).

You can check on the page status by using the Page Status admin tool. It will show the three pages and the time there were added to preview.

In the end, my site has one URL that gets sourced from the nav/index/footer in the BYOM content source.

https://main--getting-started-with-byom--the-aem-maven.aem.page/

BYOM as a Content Overlay

BYOM as the primary source is cool and you can source content from WordPress 😵‍💫. But that's likely not a good idea. You will want to use SharePoint, Google Docs or AEM as the primary. And use BYOM as an overlay.

One thing worth knowing before we go further. The primary source supports three types: Google Drive, OneDrive, and markup. The overlay only supports markup. Both BYOM and Document Authoring use the markup type. That means you could use BYOM as your primary and Document Authoring as your overlay and vice versa. Or two BYOM sources. Or two Document Authoring sources. As long as the overlay is markup, you have options.

When someone requests a page, Edge Delivery Services checks the overlay first. If the overlay returns a 404, it falls back to the primary content source. This is also how the AEM Commerce prerender solution is set up. Their overlay contains product description pages. These are pre-rendered to /products/{urlKey}/{sku}.

In my test environment the first thing I will do is set the primary content source back to the DA source. And set the overlay to my blob storage. Don't forget to delete index/nav/footer from the overlay. Otherwise they will take precedence over the primary.

Then I will “prerender” a page under /people/juanayala, which happens to contain JSON-LD for a person.

And finally I update preview with the content. I’ll send the cURL command for nav, index, footer (as before). But now I am also updating people/juanayala which will be sourced from the overlay.

In the end, my site has two URLs. The first is sourced from the DA primary content source, covering nav/index/footer.

https://main--getting-started-with-byom--the-aem-maven.aem.page/

The second is sourced from BYOM.

https://main--getting-started-with-byom--the-aem-maven.aem.page/people/juanayala

Conclusion

When I first began this research, I was focusing on "how can I generate JSON-LD server-side". This led me to the Adobe Commerce prerender solution. It is a full storefront integration built on Edge Delivery Services and a great example of composable architecture. If you move a few pieces around, swap out some parts, it can get repurposed to suit your own needs.

BYOM is also an important part of other Adobe solutions. For example, consider this early access technology: JSON2HTML for Edge Delivery Services. Adobe wrote a middleware layer that turns your JSON into the HTML that Edge Delivery expects. Why couldn't you write your own? Or check out this one: Publishing AEM Content Fragments. Adobe built on top of JSON2HTML to publish content fragments to Edge Delivery. Why couldn't you build your own?

I hope you get to try this on your own. It's free with no special licenses or access requirements. I only had to pay .87¢. That's because at first I used an Azure container instance. And I forgot to instruct Claude to stick to the free service tier!

BYOM is a small feature with a lot of potential. The hard part is knowing it is there.