opensource.google.com

Menu

schema-dts turns 1.0: Author valid Schema.org JSON-LD in TypeScript

Monday, August 30, 2021

Today, schema-dts turns 1.0 to properly reflect its current maturity. I started the project in November 2018 to improve the developer experience of writing Structured Data.

The project has continued to improve, validating a broader and more complex subset of Schema.org, improving type-checking performance, and eliminating the runtime bundle entirely. Many of these improvements were only fully understood due to feedback and reports from the community. Today, schema-dts receives more than 100k downloads/week on NPM. These users have helped validate and harden the library over the past few years.

Here are some of the highlighted improvement since the last announcement:

0kb Bundle Runtime Size

The library is now entirely type only. Previously, convenience enums were generated in .js files, but improved TypeScript completions mean that this is no longer necessary.

schema-dts provides type checking during authoring and compilation, with no runtime cost on your built output.

Roles

A Role in Schema.org is a special kind of relationship that can apply to any property. schema-dts did not previously understand the special nature of Roles, but it now does.


For example, the following code is now fully validated by schema-dts:

import {SportsTeam, WithContext} from "schema-dts";


const sf49ers: WithContext<SportsTeam> = {

  "@context": "https://schema.org",

  "@type": "SportsTeam",

  "name": "San Francisco 49ers",

  "member": {

    "@type": "OrganizationRole",

    "member": {

      "@type": "Person",

      "name": "Joe Montana"

    },

    "startDate": "1979",

    "endDate": "1992",

    "roleName": "Quarterback"

  }

};


Note how the relationship between Joe Montana and the 49ers goes through an OrganizationRole that specifies the start and end dates of the relationship. Roles in schema-dts now understand what property they belong to, allowing you to fully write-out these relationships. In the above example, schema-dts type checks "member" on the OrganizationRole as if it were a property of the Sports Team directly.

Graphs & IDs

When you have cyclical structured data, it can be helpful to encode it in a JSON-LD "@graph".

JSON-LD can encode a "@graph", representing a series of nodes with "@id" values. Nodes can reference each other simply by ID. For example, here is a cyclical graph showing the "member" relationship used with its inverse "memberOf" relationship:

import { Graph } from 'schema-dts';


const sf49ers: Graph = {

  '@context': 'https://schema.org',

  '@graph': [

    {

      '@type': 'SportsTeam',

      '@id': 'https://sportsball.com/team/49ers',

      name: 'San Francisco 49ers',

      member: { '@id': 'https://sportsball.com/player/JoeMontana' }

    },

    {

      '@type': 'Person',

      '@id': 'https://sportsball.com/player/JoeMontana',

      name: 'Joe Montana',

      memberOf: {

        '@id': 'https://sportsball.com/team/49ers'

      }

    }

  ]

};

Numbers as Strings

Schema.org long supported using string values to represent Floats, Numbers, and Integers. Thanks to TypeScript’s template literal types introduced in 4.1.0, schema-dts now can type check numeric strings anywhere a Float, Integer, or Number is expected.

Works better with React

We also provide a helper library, react-schemaorg, which makes embedding JSON-LD in react easier than ever. While we previously only supported embedding JSON-LD directly into the page, the library now supports utility libraries like react-helmet and Next.js’s next/head.

For example, here is how you can inject JSON-LD into your Next.js component:

import * as React from 'react';

import Head from 'next/head';

import { jsonLdScriptProps } from 'react-schemaorg/dist/src/json-ld';

import { Person } from 'schema-dts';


export default function Intro() {

  return (

    <div>

      <Head>

        <script

          {...jsonLdScriptProps<Person>({

            '@context': 'https://schema.org',

            '@type': 'Person',

            name: 'Grace Hopper',

            alternateName: 'Grace Brewster Murray Hopper',

            alumniOf: [

              {

                '@type': 'CollegeOrUniversity',

                name: 'Yale University'

              },

              {

                '@type': 'CollegeOrUniversity',

                name: 'Vassar College'

              }

            ],

            knowsAbout: ['Compilers', 'Computer Science']

          })}

        />

      </Head>

      <p>Hello, world! This is the personal homepage of Grace Hopper.</p>

    </div>

  );

}

***

I hope you’re excited to try out these new features! As of 1.0, I’m confident the library is stable enough for breaking changes to be few and far between.

If you’re passionate about structured data, please join the conversation on GitHub!

By Eyas Sharaiha, Geo Engineering and Open Source schema-dts Project
Labels: , , ,
.