API & Attributes Reference

Complete technical specification for BiModal Design markup

This reference documents all custom data attributes, ARIA patterns, Schema.org types, and semantic elements used in BiModal Design. Bookmark this page for quick lookup while developing.

Quick Navigation

Data AttributesARIA ReferenceSchema.org TypesHTML ElementsMicrodataAgent MetadataJS HelpersValidationTypeScript

Data Attributes API

Custom data attributes that make content easily extractable by agents.

data-entity-type

Purpose:

Identifies the semantic type of an HTML element or section. Helps agents understand the purpose and structure of content.

Common Values:
productarticlereviewpricingspecificationscontact-infosearch-resultsdata-table
<!-- Product entity -->
<article data-entity-type="product">
  <!-- Product content -->
</article>

<!-- Pricing information -->
<div data-entity-type="pricing">
  <!-- Price details -->
</div>

data-field

Purpose:

Identifies specific data fields within an entity. Makes individual pieces of information easily extractable.

Common Values:
namepricedescriptionavailabilityratingauthordateemail
<article data-entity-type="product">
  <h1 data-field="name">Premium Headphones</h1>
  <p data-field="price">$299.99</p>
  <p data-field="description">High-quality audio...</p>
</article>

data-action

Purpose:

Identifies the action that a button, link, or form performs. Helps agents understand what user actions are available.

Common Values:
add-to-cartpurchasesearchloginsubmitdeleteeditshare
<!-- Add to cart button -->
<button
  type="submit"
  data-action="add-to-cart"
  data-product-id="12345"
>
  Add to Cart
</button>

<!-- Search form -->
<form data-action="search">
  <input type="search" name="q">
  <button data-action="search">Search</button>
</form>

data-intent

Purpose:

Describes the high-level intent or purpose of an action. Helps agents understand the user's goal.

Values:
transactinformnavigatecommunicateauthenticateconfigure
<!-- Purchase form -->
<form
  action="/checkout"
  method="POST"
  data-action="checkout"
  data-intent="transact"
>
  <!-- Form fields -->
</form>

<!-- Contact form -->
<form
  action="/contact"
  method="POST"
  data-action="contact"
  data-intent="communicate"
>
  <!-- Form fields -->
</form>

Additional Data Attributes

data-requires-auth

Indicates if action requires authentication. Values: "true" or "false"

data-value

Machine-readable value for a field (useful when display differs from actual value)

data-unit

Unit of measurement for numeric values (e.g., "kg", "hours", "USD")

data-currency

Currency code for prices (ISO 4217, e.g., "USD", "EUR", "GBP")

data-status

Status of an entity (e.g., "in-stock", "out-of-stock", "active", "pending")

ARIA Quick Reference

Essential ARIA attributes for accessibility and agent comprehension.

Common Roles

role="navigation"

Navigation landmark

role="main"

Main content area

role="search"

Search region

role="button"

Interactive button

role="dialog"

Modal dialog

role="alert"

Important message

States & Properties

aria-label

Accessible name for element

aria-labelledby

ID of labeling element

aria-describedby

ID of describing element

aria-expanded

Expanded state (true/false)

aria-current

Current item (page/step/date)

aria-invalid

Validation state

Live Regions

aria-live="polite"

Announce when not busy

aria-live="assertive"

Announce immediately

aria-atomic="true"

Read entire region

Form Attributes

aria-required="true"

Required field

aria-invalid="true"

Invalid input

aria-errormessage

ID of error message

Schema.org Quick Reference

Common Schema.org types for structured data. Use JSON-LD format in <head>.

Product

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product name",
  "description": "Product description",
  "image": ["https://example.com/image.jpg"],
  "brand": {
    "@type": "Brand",
    "name": "Brand name"
  },
  "offers": {
    "@type": "Offer",
    "price": "99.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/product"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "reviewCount": "142"
  }
}

Article / BlogPosting

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Article title",
  "description": "Article description",
  "image": "https://example.com/image.jpg",
  "author": {
    "@type": "Person",
    "name": "Author name"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Publisher name",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  },
  "datePublished": "2025-01-15T08:00:00Z",
  "dateModified": "2025-01-20T10:30:00Z"
}

LocalBusiness

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Business name",
  "image": "https://example.com/image.jpg",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "City",
    "addressRegion": "State",
    "postalCode": "12345",
    "addressCountry": "US"
  },
  "telephone": "+1-555-123-4567",
  "openingHoursSpecification": {
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "opens": "09:00",
    "closes": "17:00"
  }
}

Other Common Types

Organization

Company information

Person

Individual profile

Event

Events and occasions

Recipe

Cooking recipes

WebPage

General web page

FAQPage

FAQ pages

Review

Customer reviews

VideoObject

Video content

Full Schema.org documentation: schema.org

HTML Semantic Elements

Landmarks

<header>

Page or section header

<nav>

Navigation section

<main>

Main content (one per page)

<aside>

Sidebar or tangential content

<footer>

Page or section footer

Content Sections

<article>

Self-contained content

<section>

Thematic grouping

<h1> - <h6>

Headings (hierarchy)

<p>

Paragraph

Text Semantics

<strong>

Strong importance

<em>

Emphasis

<time>

Date/time with datetime attr

<code>

Code snippet

<mark>

Highlighted text

Interactive

<button>

Clickable button

<a>

Hyperlink

<form>

Form container

<input>

Form input

<label>

Input label

JavaScript Helpers

Utility functions for working with BiModal markup.

Extract entities by type
function getEntitiesByType(type) {
  return Array.from(
    document.querySelectorAll(`[data-entity-type="${type}"]`)
  );
}

// Usage
const products = getEntitiesByType('product');
const reviews = getEntitiesByType('review');
Extract field value from entity
function getFieldValue(entity, fieldName) {
  const field = entity.querySelector(`[data-field="${fieldName}"]`);

  // Check for data-value attribute first
  if (field?.dataset.value) {
    return field.dataset.value;
  }

  // Fall back to text content
  return field?.textContent.trim() || null;
}

// Usage
const product = document.querySelector('[data-entity-type="product"]');
const name = getFieldValue(product, 'name');
const price = getFieldValue(product, 'price');
Extract all fields from entity
function extractEntity(entity) {
  const type = entity.dataset.entityType;
  const fields = {};

  entity.querySelectorAll('[data-field]').forEach(field => {
    const fieldName = field.dataset.field;
    fields[fieldName] = field.dataset.value || field.textContent.trim();
  });

  return { type, fields };
}

// Usage
const product = document.querySelector('[data-entity-type="product"]');
const data = extractEntity(product);
// { type: 'product', fields: { name: '...', price: '...', ... } }
Find actions on page
function getAvailableActions() {
  const actions = [];

  document.querySelectorAll('[data-action]').forEach(el => {
    actions.push({
      action: el.dataset.action,
      intent: el.dataset.intent || null,
      element: el,
      requiresAuth: el.dataset.requiresAuth === 'true'
    });
  });

  return actions;
}

// Usage
const actions = getAvailableActions();
// [{ action: 'add-to-cart', intent: 'transact', ... }, ...]

TypeScript Definitions

Type definitions for BiModal data attributes.

// bimodal.d.ts

declare namespace BiModal {
  // Entity types
  type EntityType =
    | 'product'
    | 'article'
    | 'review'
    | 'pricing'
    | 'specifications'
    | 'contact-info'
    | 'search-results'
    | 'data-table';

  // Action types
  type ActionType =
    | 'add-to-cart'
    | 'purchase'
    | 'search'
    | 'login'
    | 'logout'
    | 'submit'
    | 'delete'
    | 'edit'
    | 'share';

  // Intent types
  type IntentType =
    | 'transact'
    | 'inform'
    | 'navigate'
    | 'communicate'
    | 'authenticate'
    | 'configure';

  // Entity with fields
  interface Entity {
    type: EntityType;
    fields: Record<string, string>;
    element: HTMLElement;
  }

  // Action definition
  interface Action {
    action: ActionType;
    intent?: IntentType;
    requiresAuth: boolean;
    element: HTMLElement;
  }

  // Data attributes interface
  interface DataAttributes {
    entityType?: EntityType;
    field?: string;
    action?: ActionType;
    intent?: IntentType;
    requiresAuth?: 'true' | 'false';
    value?: string;
    unit?: string;
    currency?: string;
    status?: string;
  }
}

// Extend HTMLElement to include data attributes
declare global {
  interface HTMLElement {
    dataset: DOMStringMap & BiModal.DataAttributes;
  }
}

export default BiModal;

Validation Rules

BiModal Compliance Checklist

Automated Validation Tools

axe DevTools: Browser extension for accessibility testing
WAVE: Visual accessibility evaluation
Lighthouse: Built into Chrome DevTools
Google Rich Results Test: Validate Schema.org markup
HTML Validator: Check valid HTML at validator.w3.org

Need More Help?

This reference covers the essentials. For more detailed examples and patterns, check out these resources:

View Code ExamplesStart Tutorial