Package Exports
- @llmprofiles/core
- @llmprofiles/core/profiles/article
- @llmprofiles/core/profiles/book
- @llmprofiles/core/profiles/course
- @llmprofiles/core/profiles/dataset
- @llmprofiles/core/profiles/event
- @llmprofiles/core/profiles/faqpage
- @llmprofiles/core/profiles/howto
- @llmprofiles/core/profiles/jobposting
- @llmprofiles/core/profiles/localbusiness
- @llmprofiles/core/profiles/productoffer
- @llmprofiles/core/profiles/qapage
- @llmprofiles/core/profiles/recipe
- @llmprofiles/core/profiles/review
- @llmprofiles/core/profiles/softwareapplication
- @llmprofiles/core/profiles/videoobject
Readme
@llmprofiles/core
Schema.org structured data that “just works” — secured, validated, and ready for SEO, AI, and LLM pipelines.
- ✅ Rich-Results friendly (Google/Bing aware)
- 🔒 Built-in XSS/URL sanitization
- 🤖 3 output modes (Strict SEO, Split Channels, Standards Header)
- 🧩 Typed builders for 15+ common profiles
- 🧪 Validation utilities & examples
🔗 Quick Links
- Install • 60-sec Demo • Why @llmprofilescore • Output Modes • Examples • Profiles • Security • Nextjs/HTML • API & Validation • FAQ • Contributing
📦 Install
# npm
npm install @llmprofiles/core
# yarn
yarn add @llmprofiles/core
# pnpm
pnpm add @llmprofiles/core⏱ 60-sec Demo
import { ProductBuilder, MODES } from '@llmprofiles/core';
const product = new ProductBuilder(MODES.STRICT_SEO)
.name('Wireless Bluetooth Headphones')
.description('High-quality wireless headphones with noise cancellation')
.image('https://example.com/headphones.jpg')
.brand('AudioTech')
.sku('AT-WH-001')
.offers(199.99, 'USD', 'InStock')
.aggregateRating(4.5, 127)
.build();
console.log(JSON.stringify(product, null, 2));✨ Why @llmprofiles/core?
SEO-First
- Emits Schema.org that is friendly to Google/Bing rich result guidelines.
- Sensible defaults — zero config to get valid JSON-LD for common use cases.
Security Built-In
- XSS-safe: sanitizes HTML, validates URLs, strips unsafe protocols.
- Configurable sanitization levels when you fully trust inputs.
AI & LLM Ready
- Three output modes for production SEO, LLM ingestion, or full semantic web compliance.
- Optional profile metadata and training export helpers.
Dev-Friendly
- Full TypeScript types, ESM & CJS builds, tree-shakeable.
- Clean, chainable builders for 15+ profiles.
🔧 Three Output Modes
| Mode | Best For | Output Shape | Notes |
|---|---|---|---|
| STRICT_SEO (default) | Production SEO (Google/Bing) | Single JSON-LD block | Adds additionalType, schemaVersion, and profile metadata in a way that plays nicely with search engines. |
| SPLIT_CHANNELS | SEO + AI pipelines | { seo, llm } object |
Keep your SEO block pristine while shipping a parallel LLM-rich block. |
| STANDARDS_HEADER | Semantic-web purists, gateways | JSON-LD + HTTP Link/rel="profile" |
Access getRelProfile() / getLinkHeader() for headers integration. |
Example (Split Channels):
import { ProductBuilder, MODES } from '@llmprofiles/core';
const out = new ProductBuilder(MODES.SPLIT_CHANNELS)
.name('Product Name')
.build();
// out.seo -> clean SEO JSON-LD
// out.llm -> LLM-enriched metadata block🧪 Usage Examples
Product
import { ProductBuilder } from '@llmprofiles/core';
const product = new ProductBuilder()
.name('Wireless Headphones')
.description('Noise-cancelling, 30h battery')
.brand('AudioTech')
.offers(199.99, 'USD', 'InStock')
.build();Article
import { ArticleBuilder } from '@llmprofiles/core';
const article = new ArticleBuilder()
.headline('Structured Data That Actually Helps')
.author('Jane Developer')
.datePublished('2024-01-15T10:00:00Z')
.articleBody('…')
.keywords(['SEO','Schema.org','AEO'])
.build();JobPosting
import { JobPostingBuilder } from '@llmprofiles/core';
const job = new JobPostingBuilder()
.title('Senior JavaScript Developer')
.hiringOrganization('Tech Corp')
.jobLocation('San Francisco, CA')
.datePosted('2024-01-15')
.employmentType('FULL_TIME')
.baseSalary(120000, 'USD', 'YEAR')
.build();LocalBusiness
import { LocalBusinessBuilder } from '@llmprofiles/core';
const biz = new LocalBusinessBuilder()
.name("Joe's Pizza")
.address('123 Main St, City, ST 12345')
.telephone('+1-555-123-4567')
.openingHours('Mo-Fr 11:00-22:00')
.priceRange('$$')
.build();📋 Available Profile Types
Click to view profiles
| Profile | Typical Use | Rich Results? |
|---|---|---|
| Article | Blog/news | ✅ |
| Product | E-commerce | ✅ |
| JobPosting | Jobs | ✅ |
| LocalBusiness | Local SEO | ✅ |
| Event | Events | ✅ |
| Recipe | Cooking | ✅ |
| Book | Publications | ✅ |
| Course | Education | ✅ |
| Review | Reviews | ✅ |
| FAQPage | FAQs | ✅ |
| HowTo | Tutorials | ✅ |
| VideoObject | Video | ✅ |
| Dataset | Data pubs | ✅ |
| SoftwareApplication | Apps | ✅ |
| QAPage | Q&A | ✅ |
🔒 Security Features
Automatic input sanitization
import { ArticleBuilder } from '@llmprofiles/core';
const article = new ArticleBuilder()
.headline('<script>alert("xss")</script>Breaking News!') // sanitized
.author('John <b>Doe</b>') // tags stripped
.url('javascript:alert("xss")') // blocked
.build();
// Safe outputs:
console.log(article.headline); // 'alert("xss")Breaking News!'
console.log(article.author); // 'John Doe'
console.log(article.url); // nullTrusted content (opt-out)
import { MODES, ArticleBuilder } from '@llmprofiles/core';
// Disable sanitization (only if you 100% trust your inputs)
const trusted = new ArticleBuilder(MODES.STRICT_SEO, false)
.headline('<em>Trusted HTML</em>')
.build();🌐 HTML & Next.js Integration
Basic HTML
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Product Name"
}
</script>Split Channels (two blocks)
<!-- SEO block -->
<script type="application/ld+json">
{ /* SEO-optimized JSON-LD */ }
</script>
<!-- LLM block -->
<script type="application/ld+json">
{ /* AI-optimized JSON-LD */ }
</script>Standards Header
<head>
<link rel="profile" href="https://llmprofiles.org/profiles" />
<script type="application/ld+json">{ /* JSON-LD */ }</script>
</head>Next.js
import Head from 'next/head';
import { ProductBuilder } from '@llmprofiles/core';
export default function Page() {
const product = new ProductBuilder().name('Widget 3000').build();
return (
<>
<Head>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(product) }}
/>
</Head>
<main>…</main>
</>
);
}🛠 Advanced Usage
ESM & CJS
// ESM
import { ProductBuilder, MODES } from '@llmprofiles/core';
// CJS
const { ProductBuilder, MODES } = require('@llmprofiles/core');Individual Profile Imports
import { productofferProfile } from '@llmprofiles/core/profiles/productoffer';
import { articleProfile } from '@llmprofiles/core/profiles/article';
console.log(productofferProfile.type);
console.log(Object.keys(articleProfile.required));Custom Validation
import { validateStructuredData } from '@llmprofiles/core';
const result = validateStructuredData(
{ name: 'Product Name', description: 'Description' },
'Product'
);
if (!result.isValid) console.error(result.errors);⚙️ Performance & Compatibility
- Small, tree-shakeable core
- TypeScript types included
- Node.js 16+
- ESM and CommonJS builds
- No runtime telemetry
❓ FAQ
Will this guarantee Google Rich Results? No library can guarantee rich results. This package emits Schema.org-compatible JSON-LD aligned with common guidelines; eligibility is determined by search engines and your page/content quality.
Do I need to configure anything to start?
No. Chain a few fields on a builder, call .build(), and you’ll get a valid JSON-LD object.
What’s the difference between STRICT_SEO and SPLIT_CHANNELS?
STRICT_SEO outputs a single, clean block for search engines. SPLIT_CHANNELS returns { seo, llm } so you can keep SEO pristine while shipping an LLM-rich variant separately.
Is sanitization always on? Yes (by default). You can disable it per-builder only when you fully trust the input source.
🤝 Contributing
We welcome PRs and issues!
- Read the Contributing Guide
- Open an Issue
- Star the repo if this helps you ⭐
Development
git clone https://github.com/HaMi-IQ/llmprofiles.git
cd llmprofiles/npm-package
npm install
npm test📚 Resources
- Docs: https://llmprofiles.org
- Examples: ./examples/
- API Types: ./types/
- GitHub: https://github.com/HaMi-IQ/llmprofiles
- Issues: https://github.com/HaMi-IQ/llmprofiles/issues
📄 License
MIT — see LICENSE-CODE.
🏆 What Devs Say
“No more guessing what Google wants. The builders produce valid JSON-LD out of the box.” — Sarah M., SEO Developer
“Automatic sanitization saved us from nasty XSS edge cases.” — Mike R., Full-Stack Engineer
“The split channels pattern fits our SEO + LLM pipeline perfectly.” — Alex K., AI Engineer
Ready to ship safer, richer structured data?
npm i @llmprofiles/core and go.