Skip to main content

Level Up Your SEO: Type-Safe JSON-LD with @antinna/schema-ld-types

By

Building structured data for search engines just got a lot safer. @antinna/schema-ld-types is a comprehensive, type-safe library for Schema.org JSON-LD objects.

Whether you are injecting dynamic SEO metadata or serializing search data, this package ensures both runtime and compile-time accuracy for your structured data pipelines.

✨ Core Features

  • Full Type-Safety: Autogenerated TypeScript definitions compiled directly from the official Schema.org vocabulary.
  • Validation & Typeguards: Built-in helper utilities to validate and assert schema structures safely at runtime.
  • Smart Hydration: Automatically insert missing @type properties onto deeply nested objects based on Schema.org rules.
  • Serialization / Deserialization: Seamless translation to and from JSON-LD strings, with automatically resolved @context wrappers.

📦 Installation

Add the package to your project using npm:

npm install @antinna/schema-ld-types

🚀 Usage Examples

Here are the standard patterns to validate, serialize, deserialize, and type-check your Schema.org JSON-LD elements.

1. Import Types & Utilities

import { 
  Person, 
  validate, 
  assertType, 
  serialize, 
  deserialize, 
  hydrate 
} from '@antinna/schema-ld-types';

2. Validate Data (Type Guarding)

Ensure at runtime that an arbitrary object correctly conforms to the expected Schema.org hierarchy.

const data: any = {
  '@type': 'Person',
  name: 'Jane Doe',
  jobTitle: 'Software Engineer',
  worksFor: {
    '@type': 'Organization',
    name: 'Antinna'
  }
};

if (validate<Person>(data, 'Person')) {
  // TypeScript now knows 'data' is strictly a Person object
  console.log(`Successfully verified Person: ${data.name}`);
} else {
  console.error("Invalid Person structure!");
}

3. Assertion Testing

Quickly throw an error if an object fails to match the required schema type.

try {
  const verifiedPerson = assertType<Person>(data, 'Person');
  console.log(verifiedPerson.name);
} catch (error) {
  console.error(error.message);
}

4. Serialize to JSON-LD String

Automatically prepend the correct @context and compile your data into a ready-to-inject string.

const author: Person = {
  '@type': 'Person',
  name: 'Manish',
  url: 'https://github.com/manishmg3994'
};

const jsonLdString = serialize(author);
console.log(jsonLdString);

/* 
Output:
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Manish",
  "url": "https://github.com/manishmg3994"
}
*/

5. Deserialize & Hydrate

Parse a raw JSON-LD string and automatically hydrate missing nested @type properties recursively based on the official schema rules.

const rawJson = `
{
  "name": "John Doe",
  "worksFor": {
    "name": "Antinna"
  }
}
`;

// Deserializes and automatically infers worksFor's @type as Organization
const loadedPerson = deserialize<Person>(rawJson, 'Person');

console.log(loadedPerson['@type']); // "Person"
console.log(loadedPerson.worksFor['@type']); // "Organization"

📄 License

This project is open-source and licensed under the MIT License.

Labels:

Comments

Post a Comment

Popular posts from this blog

Flutter™ Installation Without Android Studio™

By
When developing with Flutter™, you typically install Android Studio™ as part of the setup process. However, if you want a lightweight alternative, you can install Flutter™ with only the Android command-line tools. This guide walks you through the steps to set up Flutter™ on Windows without Android Studio™. Step 1: Install Android Command-Line Tools Download Command-Line Tools: Download the Android SDK Command-Line Tools from the Android Developer website . Extract the downloaded zip file: Extract it to a directory, e.g., C:\Users\<User Name>\AppData\Local\Android\Sdk\cmdline-tools . Set up SDK directories: Inside the cmdline-tools folder, create a subfolder named latest . Move the extracted files and folders into this latest folder. The structure should look like: ...
Post a Comment
Read more

Building a Modular Project with a Monorepo Using Pub Workspaces Feature

By
Flutter™  projects often start small, but as they scale, managing multiple packages becomes challenging. If you find yourself working with several modules or features in one project, organizing them efficiently is crucial. Enter Monorepos with Pub Workspaces – an excellent solution for managing a Flutter project with multiple packages in a modular way. In this post, we’ll explore how to structure a Flutter project in a modular way using a monorepo , and how to manage dependencies across various sub-projects without worrying about version conflicts. We’ll also look at how to configure Pub Workspaces to simplify dependency resolution and management. When working with Flutter™ and Dart™ , structuring a project in a modular way can improve scalability and maintainability. This is especially important when managing multiple packages in a single repository, also known as a monorepo . Pub Workspaces , introduced to simplify dependency management, provide a robust solution...
Post a Comment
Read more

Stop Guessing: A Scalable Strategy for Flutter Environment Management

By
When building production-grade applications, hardcoding API endpoints, feature flags, or tracking keys directly into your source code is an architectural anti-pattern. To guarantee security and runtime predictability, setups should cleanly isolate target environments depending on compile-time parameters. This guide establishes a compile-time, zero-overhead environment orchestration system leveraging strict encapsulation patterns and modern features in native Dart. 1. Define the Immutable Flavor Domain ( flavor_enum.dart ) The foundation of this pattern relies on an explicit Flavor enumeration. This handles your application's environmental constraints and leverages a resilient static factory fallback to transform incoming build-time string tokens safely into type-safe domains. lib/flavor/flavor_enum.dart Dart /// flavor_enum.dart library; enum Flavor { development, ...
Post a Comment
Read more