Introducing Content Source Maps: A shortcut from front-end to content

As companies embrace decoupled CMSes in the composable era, they need to ensure that the performance and flexibility gains coincide with increased resilience, strong security, and better editorial affordances. Although teams see the potential of headless CMS architectures, they want to ensure that transitioning from their traditional setup won't negatively impact team efficiency.

Today we’re releasing a new open standard for annotating JSON data with contextual metadata: Content Source Maps. By adding data to a content API response, Content Source Maps provide a shortcut from the front-end site directly to the source of content within a modern, decoupled content management system. This standard creates opportunities for increased efficiency and accuracy for the ecosystem of teams working on digital experiences: content teams (including creators, editors, and designers), developers, and subject matter experts.

This open standard is brought to life by Sanity as a new API for all Sanity projects and an end-to-end visual editing experience for customers using Sanity and Vercel.

As we all experience in our day to day, digital surfaces and devices have continued to proliferate, and our expectations for personalized, localized, and cohesive content are ever-increasing. This is why modern content solutions have emerged: they make it possible to meet the demands of the omnichannel era at scale.

Distilling the “how” comes down to a core concept: reuse. In a monolithic world where content back ends are tied tightly to the specific front end surface (e.g., WordPress), teams spend inordinate amounts of time creating and updating content across many instances.

• With a modern CMS—which goes beyond a headless CMS—content is created centrally within a composable, no-ops storage layer: Content Lake. Content Lake aggregates changes from any source, including Sanity’s editing environment but also other sources of content and data such as a PIM or ecommerce platform.
• When the content is created, it’s represented as structured content, which means it’s broken down into its component parts. For example, a blog post has a title, an author, body content, and perhaps a video. Each of these is stored as discrete components, and the types of components that matter to each business can be uniquely and expressively defined (this makes up the content model).
• Finally, APIs are used to query the content and present whichever relevant parts are needed for each front-end surface. Sanity developed GROQ as another open standard to provide developers with a powerful query language to formulaically gather, recompose, and deliver the exact content needed to develop your application. To use Content Source Maps with GROQ, utilize the query endpoint version v2021-03-25 or later. In addition to GROQ, Sanity customers have the option to use GraphQL; GraphQL support for Content Source Maps is available with the GraphQL endpoint version v2023-08-01 and on.

With a modern CMS like the Sanity Composable Content Cloud, the benefits of this approach include dramatically faster content creation in a multi-experience world and far better customer experiences through content performance, accuracy, and relevance.

Here’s the tradeoff: when a content person, developer, SME, or simply a good samaritan has feedback about a piece of content they encounter in the world—whether on a website, app, or in-store display—it can take time to hunt down the exact source of that root content. Especially in enterprise scenarios when there’s an immense volume of content owned by various teams, within a complex content model (lots of nested relationships, for example).

This can undermine the efficiency of going with a modern, decoupled CMS when even minor, everyday changes like a typo or incorrect image take a good chunk of time to locate within the editing environment. Often this requires a team member who has a deep understanding of how their organization’s content is modeled, leading to further bottlenecks.

Customers moving to headless or composable CMSes are hungry for ways to make content editing more intuitive for non-developers; they struggle with querying or traversing through complex content structures. Content Source Maps solves this in a powerful, intuitive way by providing a link from any front-end to the source of content.

– Scott Gentz, Sanity Strategic Director of Accounts (and former Director of Technology at AT&T).

Content Source Maps work by adding a bit of data to the content API response which can be used to trace any bit of content back to its source in the content management system. This data includes the exact document and field where the content originated.  However complex the join you did to assemble the output, we’ll give you the source of every field in the final document.

{
  "documents": [
    {
      "_id": "author-1"
    },
    {
      "_id": "author-2"
    }
  ],
  "paths": ["$['name']"],
  "mappings": {
    "$[0]": {
      "type": "value",
      "source": {
        "type": "documentValue",
        "document": 0,
        "path": 0
      }
    },
    "$[1]": {
      "type": "value",
      "source": {
        "type": "documentValue",
        "document": 1,
        "path": 0
      }
    }
  }
}

In this example, a query for two documents also returns two associated mappings, where each entry indicates, for each element of the response, what document and path (attribute) from the lists above it comes from. You can explore a full example in our Content Source Maps API documentation.

Importantly, the content source map is separate from the content itself. This means systems that don’t recognize content source maps will remain unaffected—a good separation of concerns that drove Sanity’s design of this standard.

Sanity released this as an open standard so that any framework and any content management system can provide this high-impact utility for their users. We see this as an important advancement to further support the adoption of modern content architectures, which benefit not just the teams creating digital experiences, but all of us who consume them.

Content Source Maps are a brand-new standard that we believe developers and content teams will use in a myriad of ways given the metadata that’s now available.

The first end-to-end implementation of Content Source Maps, co-developed by Sanity and Vercel, powers seamless transition from any piece of content on a Vercel-based frontend to the source of that content within Sanity Studio. Called Visual Editing, this feature is available today for any Sanity project.

As anyone who has chased down 10s or 100s of instances of a misattributed quote or incorrect price can attest, this direct link to content and ability to “edit once, publish everywhere” provides massive time savings. As one of our co-founders, Even Westvang joked, it takes us from “WYSIWYG” (what you see is what you get) to “WYSLH” (what you see lives here).

In large organizations, the number of people involved in the content lifecycle (or with expertise about the content) greatly exceeds the small group of people actually building and maintaining their content architecture. These organizations need to make content changes both fast and accurately, especially when regulatory compliance is at play.

For example, a compliance officer at a large bank who finds a required clause is missing on a piece of live content often needs to send several messages to the digital team to flag the content and identify who needs to be aware of the error. With Content Source Maps, one idea would be to design a custom dashboard that the compliance team can use to self-serve the information they need to enforce regulatory requirements.

Content Source Maps can also help developers debug presentation issues that may be driven by how content is modeled and managed within their CMS setup. For example, if a title field’s translation was not working for a specific language, the developer could create an inspection tool that reads from the Content Source Map to identify the origin of the translation issue—this would identify whether the error is within the CMS or from a third party service.

We’re early days for Content Source Maps, and are excited to see what the developer and content communities devise to put this actionable data to use.

Content Source Maps are available as an API for all Sanity projects. Contact our sales team for more information. You can explore the API documentation here.