Schema API Reference

Overview

Schema.org helpers create JSON-LD structured data for rich search results. These functions generate properly formatted JSON without requiring detailed knowledge of schema.org specifications.

Functions

airheads.schema.build_article_schema(headline, description, image, date_published, author_name, author_url=None, publisher_name='', publisher_logo=None, date_modified=None, url=None)

Build JSON-LD Article schema for rich search results.

Parameters:

Name	Type	Description	Default
headline	str	Article headline/title	required
description	str	Article description	required
image	str	URL to article image	required
date_published	str | datetime	Publication date (ISO 8601 string or datetime)	required
author_name	str	Author's name	required
author_url	str | None	URL to author's page/profile	None
publisher_name	str	Publisher/site name	''
publisher_logo	str | None	URL to publisher logo	None
date_modified	str | datetime | None	Last modified date (ISO 8601 string or datetime)	None
url	str | None	Canonical URL of the article	None

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_article_schema from airheads import build_json_ld

json_str = build_article_schema( ... headline="My Great Article", ... description="An informative piece", ... image="https://example.com/image.jpg", ... date_published="2025-01-15T10:00:00Z", ... author_name="Jane Developer", ... publisher_name="My Blog" ... ) script = build_json_ld(json_str)

airheads.schema.build_product_schema(name, description, image, brand=None, price=None, currency='USD', availability='https://schema.org/InStock', url=None, sku=None)

Build JSON-LD Product schema for e-commerce.

Parameters:

Name	Type	Description	Default
name	str	Product name	required
description	str	Product description	required
image	str	URL to product image	required
brand	str | None	Brand name	None
price	str | float | None	Product price (as string or number)	None
currency	str	ISO 4217 currency code (default: "USD")	'USD'
availability	str	Availability URL (default: InStock)	'https://schema.org/InStock'
url	str | None	Canonical URL of the product	None
sku	str | None	Stock keeping unit identifier	None

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_product_schema json_str = build_product_schema( ... name="Air Framework", ... description="Python web framework", ... image="https://example.com/product.jpg", ... brand="Kentro Tech", ... price="0.00", ... currency="USD" ... )

airheads.schema.build_person_schema(name, url=None, image=None, job_title=None, works_for=None, description=None, email=None)

Build JSON-LD Person schema.

Parameters:

Name	Type	Description	Default
name	str	Person's name	required
url	str | None	URL to person's website or profile	None
image	str | None	URL to person's photo	None
job_title	str | None	Person's job title	None
works_for	str | None	Organization name	None
description	str | None	Bio/description	None
email	str | None	Contact email	None

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_person_schema json_str = build_person_schema( ... name="Jane Developer", ... job_title="Software Engineer", ... works_for="Tech Corp" ... )

airheads.schema.build_organization_schema(name, url, logo=None, description=None, email=None, telephone=None, address=None)

Build JSON-LD Organization schema.

Parameters:

Name	Type	Description	Default
name	str	Organization name	required
url	str	Organization website URL	required
logo	str | None	URL to organization logo	None
description	str | None	Organization description	None
email	str | None	Contact email	None
telephone	str | None	Contact phone number	None
address	str | None	Physical address	None

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_organization_schema json_str = build_organization_schema( ... name="Kentro Tech", ... url="https://kentro.tech", ... logo="https://kentro.tech/logo.png" ... )

airheads.schema.build_website_schema(name, url, description=None, search_url=None)

Build JSON-LD WebSite schema for homepage/site-wide data.

Parameters:

Name	Type	Description	Default
name	str	Website name	required
url	str	Website homepage URL	required
description	str | None	Website description	None
search_url	str | None	Search URL template (e.g., "https://example.com/search?q={search_term_string}")	None

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_website_schema json_str = build_website_schema( ... name="My Site", ... url="https://example.com", ... search_url="https://example.com/search?q={search_term_string}" ... )

airheads.schema.build_breadcrumb_schema(items)

Build JSON-LD BreadcrumbList schema for navigation breadcrumbs.

Parameters:

Name	Type	Description	Default
items	list[tuple[str, str]]	List of (name, url) tuples representing the breadcrumb trail	required

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_breadcrumb_schema json_str = build_breadcrumb_schema([ ... ("Home", "https://example.com"), ... ("Blog", "https://example.com/blog"), ... ("Article", "https://example.com/blog/my-article"), ... ])

airheads.schema.build_faq_schema(questions)

Build JSON-LD FAQPage schema for frequently asked questions.

Parameters:

Name	Type	Description	Default
questions	list[tuple[str, str]]	List of (question, answer) tuples	required

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_faq_schema json_str = build_faq_schema([ ... ("What is Air?", "Air is a Python web framework."), ... ("How do I install it?", "Run: pip install air"), ... ])

airheads.schema.build_howto_schema(name, description, steps, image=None, total_time=None, tool=None, supply=None)

Build JSON-LD HowTo schema for step-by-step guides.

Parameters:

Name	Type	Description	Default
name	str	Title of the how-to guide	required
description	str	Description of what the guide teaches	required
steps	list[tuple[str, str]]	List of (step_name, step_text) tuples	required
image	str | None	URL to image showing the completed result	None
total_time	str | None	Total time in ISO 8601 duration format (e.g., "PT30M" for 30 minutes)	None
tool	list[str] | None	List of tools needed	None
supply	list[str] | None	List of supplies/materials needed	None

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_howto_schema json_str = build_howto_schema( ... name="How to Install Air", ... description="Learn to install the Air framework", ... steps=[ ... ("Install Python", "Download and install Python 3.8+"), ... ("Install Air", "Run pip install air"), ... ], ... total_time="PT5M" ... )

airheads.schema.build_video_schema(name, description, thumbnail_url, upload_date, content_url=None, embed_url=None, duration=None)

Build JSON-LD VideoObject schema for video content.

Parameters:

Name	Type	Description	Default
name	str	Video title	required
description	str	Video description	required
thumbnail_url	str	URL to video thumbnail image	required
upload_date	str | datetime	Upload date (ISO 8601 string or datetime)	required
content_url	str | None	Direct URL to video file	None
embed_url	str | None	URL to embedded player	None
duration	str | None	Video duration in ISO 8601 format (e.g., "PT1H30M" for 1h 30min)	None

Returns:

Type	Description
str	JSON string ready to use with build_json_ld()

Example

from airheads.schema import build_video_schema json_str = build_video_schema( ... name="Air Framework Tutorial", ... description="Learn to build with Air", ... thumbnail_url="https://example.com/thumb.jpg", ... upload_date="2025-01-15T10:00:00Z", ... embed_url="https://youtube.com/embed/abc123", ... duration="PT15M" ... )