Referenced content

References

The s.keyOf() schema type creates a reference to keys from another Val module that is defined using s.record(). This enables safe references between your content, ensuring that links and references always point to existing content.

Note: For referencing routes in page routers, use s.route() instead. See the Page Router guide for more information.

Setting up referenceable content

In order to refer to content using keyOf, you must first have a s.record to which you want to refer.

In the example below, we have defined a module of all authors by email.

// authors.val.ts
const authorsSchema = s.record(
  s.object({
    name: s.string(),
  })
);

export default c.define("/content/authors.val.ts", authorsSchema, {
  "freekh@val.build": { name: "Freddy" },
  "theo@val.build": { name: "Theddy"  },
});

Refering to content using keyOf

When you have a record of keys that you want to refer to, use s.keyOf. This will make it possible for content editors to select from a list of possible options, the keys of the record. It will also make it possible for Val to validate the reference.

import authorsVal from "./authors.val";

const pageSchema = s.object({
  title: s.string(),
  author: s.keyOf(authorsVal), // References authors
});

export default c.define("/content/page.val.ts", pageSchema, {
  title: "Welcome",
  author: "fre", // this will be validated by Val
});

Recursive keyOf

When using keyOf, you might end up in a situation where you have mutually recursive schemas. A consequence of this is that TypeScript will no longer be able to infer the types of the modules that are mutually recursive.

To avoid this, you can use the "getter syntax" on all keyOf related types.

import { s } from "@/val.config";
import { DecodeVal, Schema, t } from "@valbuild/next";
import blogsPageVal from "./blogs/[slug]/page.val";
import supportArticlePageVal from "./support/[slug]/page.val";

export const linkButtonSchema = s.object({
  label: s.string(),
  link: s.union(
    "type",
    s.object({
      type: s.literal("support-article"),
      get href(): Schema<string> {
        return s.keyOf(supportArticlePageVal);
      },
    }),
    s.object({
      type: s.literal("blog"),
      get href(): Schema<string> {
        return s.keyOf(blogsPageVal);
      },
    }),
  ),
});

export type LinkButton = DecodeVal<t.inferSchema<typeof linkButtonSchema>>;

By using the the "getter syntax" you are now able to use the linkButton in the blogs / support article pages.

import { s, c, nextAppRouter } from "@/val.config";
import { LinkButton, linkButtonSchema } from "../../linkButton.val";
import { Schema } from "@valbuild/next";

const blogSchema = s.object({
  // ...
  get cta(): Schema<LinkButton> {
    return linkButtonSchema;
  },
});

export default c.define(
  "/app/(main)/blogs/[slug]/page.val.ts",
  s.router(nextAppRouter, blogSchema),
  {
    "/blogs/my-blog": {
      cta: {
        label: "My blog",
        link: {
          type: "blog",
          href: "/blogs/my-blog",
        },
      },
    },
  },
);