Package Exports
- @meta-aiml/parser
Readme
@meta-aiml/parser
AIML Parser SDK v2.0.1 - Official validation library for Meta-AIML.org entity schemas
🎯 SAME VALIDATION LOGIC AS UI VALIDATOR - Complete schema validation for 31 entity types across 6 categories with META-AIML Intelligent Scoring Engine and comprehensive v2.0.1 compliance.
⭐ NEW in v2.0.1
🔄 Enhanced Validation System
- entityCapabilities: Objective business capabilities with boolean functional features
- siteCapabilities: Website interaction capabilities and user actions
- META-AIML Intelligent Scoring Engine: Google PageSpeed-like quality zones (EXCELLENT 90-100, GOOD 50-89, POOR 0-49)
- Exact UI Validator Logic: Same validation rules, scoring, and completeness calculation as the official UI validator
📋 Critical Required Fields (v2.0.1)
{
"@context": "https://schemas.meta-aiml.org/v2.0.1/context.jsonld",
"@id": "https://example.com/entity",
"@type": "EntityTypeName",
"schemaVersion": "2.0.1",
"entityType": "entity_type",
"entityCategory": "category",
"subcategory": "subcategory",
"name": { "en": "Name" },
"description": { "en": "Description 50+ characters" }
}
🚀 Quick Start
Installation
npm install @meta-aiml/parser
Basic Usage
const AIMLParser = require('@meta-aiml/parser');
// Validate a schema using EXACT SAME LOGIC as UI validator
const parser = new AIMLParser();
const result = parser.validate({
"@context": "https://schemas.meta-aiml.org/v2.0.1/context.jsonld",
"@id": "https://bellavista.com/entity",
"@type": "Restaurant",
"schemaVersion": "2.0.1",
"entityType": "restaurant",
"entityCategory": "organization",
"subcategory": "hospitality",
"name": {
"en": "Bella Vista Restaurant",
"es": "Restaurante Bella Vista"
},
"description": {
"en": "A cozy neighborhood restaurant serving fresh, local cuisine with modern twist and exceptional dining experience in a warm and inviting atmosphere."
},
"url": "https://bellavista.com",
// NEW v2.0.1 FIELDS - Required for complete validation
"entityCapabilities": {
"functionalFeatures": {
"acceptsReservations": true,
"hasDelivery": true,
"hasTakeout": true,
"acceptsCreditCards": true,
"hasWifi": true
},
"contentTypes": ["menu", "photos", "reviews", "location"],
"businessModel": "restaurant",
"paymentMethods": ["credit_card", "cash", "digital_wallet"]
},
"siteCapabilities": {
"availableActions": ["view_menu", "make_reservation", "order_delivery"],
"interactionMethods": ["online_form", "phone_call"],
"supportedDevices": ["desktop", "mobile", "tablet"],
"languages": ["en", "es"]
},
// Required module for restaurant entities
"modules": {
"location": {
"version": "2.0.1",
"enabled": true
}
}
});
if (result.isValid) {
console.log(`✅ Valid schema! Score: ${result.score}/100`);
console.log(`📊 Completeness: ${result.completeness}%`);
// Quality zones (same as UI validator)
if (result.score >= 90) {
console.log('🟢 EXCELLENT - Production ready!');
} else if (result.score >= 50) {
console.log('🟡 GOOD - Minor improvements needed');
} else {
console.log('🔴 POOR - Address critical errors');
}
} else {
console.log('❌ Validation errors:', result.errors);
console.log('⚠️ Warnings:', result.warnings);
}
📊 META-AIML Intelligent Scoring Engine
Same scoring algorithm as the official UI validator:
🎯 Quality Zones:
- 🟢 EXCELLENT (90-100): No warnings, with completeness bonus for 100 points
- 🟡 GOOD (50-89): Functional schema with warnings or minor errors (≤3)
- 🔴 POOR (0-49): Critical issues requiring immediate attention (>3 errors)
🧮 Scoring Algorithm:
// Base calculation: 100 - (ERRORS×30 + WARNINGS×10 + SUGGESTIONS×5)
// Enhanced logic:
// - No warnings → 90 + (completeness × 10%) up to 100
// - Has errors (≤3) → minimum 50 points (Good zone)
// - Multiple errors (>3) → may fall to Poor zone (floor 25 points)
🏗️ Complete Entity Type Coverage
📊 Organization (6 types)
clinic
- Healthcare clinics (Required modules: auth, security, compliance)education_platform
- Educational platforms (Required: auth, user-management)fitness_platform
- Fitness and wellness centershotel
- Hotels and accommodation (Required: location, payments)restaurant
- Food service establishments (Required: location)store
- Physical retail stores
🛍️ Product Offering (4 types)
ecommerce_store
- Online stores (Required: auth, payments)marketplace
- Multi-vendor marketplaces (Required: auth, payments, user-management)product
- Physical productssoftware_product
- Digital software products
🔧 Service (9 types)
business_services
- Professional servicesgenerative_ai_platform
- AI platforms (Required: auth, security)real_estate_platform
- Property servicesridesharing_service
- Transportation (Required: auth, location)task_management_app
- Productivity appstelemedicine_platform
- Remote healthcare (Required: auth, security, compliance, streaming)virtual_event_platform
- Online eventsweb_app
- Web applicationswebsite_services
- Website development services
🎨 Creative Work (9 types)
blog
- Content publishing platformsevent
- Events and gatheringsfile_hosting
- File storage servicesgaming_platform
- Gaming platformsnews
- News and media outletspersonal_website
- Personal websitesphoto_hosting
- Image sharing platformsstreaming_platform
- Media streamingvideo_hosting
- Video platforms
👥 Community (2 types)
dating_platform
- Dating platformssocial_network
- Social networks (Required: auth, user-management)
💰 Financial Product (1 type)
online_banking
- Digital banking (Required: auth, security, compliance)
🔧 Complete API Reference
Constructor
const parser = new AIMLParser(options);
Options:
debug
(boolean): Enable debug modestrict
(boolean): Enable strict validationversion
(string): Target AIML version (default: "2.0.1")
Core Validation Methods
validate(data)
Complete schema validation with META-AIML Intelligent Scoring Engine.
const result = parser.validate(schema);
// Returns: AIMLValidationResult with exact same logic as UI validator
isValid(data)
Quick boolean validation check.
const valid = parser.isValid(schema);
// Returns: boolean
getEntityInfo(data)
Extract detailed entity information.
const info = parser.getEntityInfo(schema);
// Returns: AIMLEntityInfo | null
Static Methods
// Quick validation (same as UI validator)
const result = AIMLParser.validate(schema, options);
// Factory methods
const prodParser = AIMLParser.createProduction();
const devParser = AIMLParser.createDevelopment();
// Utility methods
const version = AIMLParser.getVersion(); // "2.0.1"
const entityTypes = AIMLParser.getEntityTypes(); // All 31 types
const categories = AIMLParser.getEntityCategories(); // 6 categories
const modules = AIMLParser.getModules(); // 14 available modules
const subcategories = AIMLParser.getSubcategories(); // 15 subcategories
📊 Validation Result Structure
{
isValid: boolean, // Overall validation status
errors: AIMLValidationError[], // Critical errors (30 points each)
warnings: AIMLValidationError[], // Warnings (10 points each)
suggestions: AIMLValidationError[], // Suggestions (5 points each)
entityInfo: { // Entity information
entityType: string, // One of 31 supported types
entityCategory: string, // One of 6 base categories
subcategory: string, // One of 15 subcategories
baseSchema: string, // Base schema category
modules: string[], // Active modules (max 14)
hasEntityCapabilities: boolean, // NEW v2.0.1
hasSiteCapabilities: boolean // NEW v2.0.1
},
score: number, // META-AIML Intelligent Scoring Engine (0-100)
completeness: number, // Completeness percentage (0-100)
performance: { // Performance metrics
schemaSize: number, // Schema size in bytes
complexity: 'low'|'medium'|'high', // Complexity assessment
moduleCount: number // Number of enabled modules
}
}
⚡ v2.0.1 Enhanced Features
NEW: entityCapabilities (Required)
Objective, verifiable business capabilities:
"entityCapabilities": {
"functionalFeatures": {
// Boolean values for objective verification
"acceptsReservations": true,
"hasDelivery": true,
"acceptsCreditCards": true,
"hasWifi": true
},
"contentTypes": ["menu", "photos", "reviews"], // Available content
"businessModel": "restaurant", // Business model type
"paymentMethods": ["credit_card", "cash"] // Supported payments
}
NEW: siteCapabilities (Required)
Website interaction and accessibility features:
"siteCapabilities": {
"availableActions": ["view_menu", "make_reservation"], // User actions
"interactionMethods": ["online_form", "phone_call"], // Contact methods
"contentAccess": ["public", "members_only"], // Access levels
"supportedDevices": ["desktop", "mobile", "tablet"], // Device support
"languages": ["en", "es"], // UI languages
"realTimeFeatures": ["real_time_availability"] // Real-time features
}
🔍 Complete Examples
Marketplace Entity (Product Offering)
const marketplaceSchema = {
"@context": "https://schemas.meta-aiml.org/v2.0.1/context.jsonld",
"@id": "https://techbazaar.com/entity",
"@type": "Marketplace",
"schemaVersion": "2.0.1",
"entityType": "marketplace",
"entityCategory": "product_offering",
"subcategory": "ecommerce_platform",
"name": {
"en": "TechBazaar Global Marketplace",
"es": "Mercado Global TechBazaar"
},
"description": {
"en": "Leading B2B2C technology marketplace connecting vendors and buyers worldwide with comprehensive product catalog and secure payment processing."
},
"url": "https://techbazaar.com",
"shortDescription": "Global technology marketplace platform",
// Required v2.0.1 fields
"entityCapabilities": {
"functionalFeatures": {
"supportsOnlinePayments": true,
"hasShoppingCart": true,
"hasUserAccounts": true,
"hasProductReviews": true,
"hasVendorVerification": true
},
"contentTypes": ["products", "reviews", "guides", "vendor_profiles"],
"businessModel": "marketplace",
"paymentMethods": ["credit_card", "paypal", "digital_wallet"]
},
"siteCapabilities": {
"availableActions": ["browse_products", "compare_products", "add_to_cart", "checkout"],
"interactionMethods": ["online_form", "live_chat", "email"],
"supportedDevices": ["desktop", "mobile", "tablet"],
"languages": ["en", "es", "zh"]
},
// Required modules for marketplace
"modules": {
"auth": { "version": "2.0.1", "enabled": true },
"payments": { "version": "2.0.1", "enabled": true },
"user-management": { "version": "2.0.1", "enabled": true }
}
};
const result = AIMLParser.validate(marketplaceSchema);
console.log(`Score: ${result.score}/100 - ${result.score >= 90 ? 'EXCELLENT' : result.score >= 50 ? 'GOOD' : 'POOR'}`);
🚀 Advanced Usage
Comprehensive Error Handling
const result = parser.validate(schema);
// Same error structure as UI validator
if (!result.isValid) {
console.log('🔴 Critical Errors (Must Fix):');
result.errors.forEach(error => {
console.log(` - ${error.field}: ${error.message}`);
if (error.suggestion) {
console.log(` 💡 ${error.suggestion}`);
}
});
console.log('🟡 Warnings (Recommended):');
result.warnings.forEach(warning => {
console.log(` - ${warning.field}: ${warning.message}`);
});
console.log('🔵 Suggestions (Optional):');
result.suggestions.forEach(suggestion => {
console.log(` - ${suggestion.field}: ${suggestion.message}`);
});
}
// Quality assessment (same as UI validator)
const getQualityZone = (score) => {
if (score >= 90) return { name: 'EXCELLENT', color: 'green', description: 'Production ready' };
if (score >= 50) return { name: 'GOOD', color: 'orange', description: 'Minor improvements needed' };
return { name: 'POOR', color: 'red', description: 'Critical issues' };
};
const zone = getQualityZone(result.score);
console.log(`${zone.name} (${result.score}/100) - ${zone.description}`);
Batch Validation
const schemas = [restaurantSchema, marketplaceSchema, clinicSchema];
const results = schemas.map(schema => AIMLParser.validate(schema));
// Quality distribution (same logic as UI validator)
const excellent = results.filter(r => r.score >= 90).length;
const good = results.filter(r => r.score >= 50 && r.score < 90).length;
const poor = results.filter(r => r.score < 50).length;
console.log(`Quality Distribution: ${excellent} Excellent, ${good} Good, ${poor} Poor`);
📋 Required Fields by Category
Critical Fields (All entities)
// ERRORS if missing - from required_fields_v2.0.1.md
const criticalRequired = [
'@context', // Must be "https://schemas.meta-aiml.org/v2.0.1/context.jsonld"
'@id', // Unique URI identifier
'@type', // Pascal Case entity name
'schemaVersion', // Must be "2.0.1"
'entityType', // snake_case type (one of 31)
'entityCategory',// one of 6 base categories
'subcategory', // must match entityType
'name', // Multilingual object (minimum "en")
'description' // Multilingual object (minimum "en", 50+ chars)
];
Required Modules by Entity Type
const requiredModules = {
"clinic": ["auth", "security", "compliance"],
"education_platform": ["auth", "user-management"],
"hotel": ["location", "payments"],
"restaurant": ["location"],
"ecommerce_store": ["auth", "payments"],
"marketplace": ["auth", "payments", "user-management"],
"generative_ai_platform": ["auth", "security"],
"ridesharing_service": ["auth", "location"],
"social_network": ["auth", "user-management"],
"online_banking": ["auth", "security", "compliance"],
"telemedicine_platform": ["auth", "security", "compliance", "streaming"]
};
🌐 Browser Usage
CDN (UMD)
<script src="https://unpkg.com/@meta-aiml/parser@2.1.0/dist/aiml-parser.min.js"></script>
<script>
const parser = new AIMLParser();
const result = parser.validate(mySchema);
// Same quality assessment as UI validator
if (result.score >= 90) {
console.log('🟢 EXCELLENT - Ready for production!');
}
</script>
ES Modules
<script type="module">
import AIMLParser from 'https://unpkg.com/@meta-aiml/parser@2.1.0/dist/index.esm.js';
const result = AIMLParser.validate(schema);
console.log(`META-AIML Score: ${result.score}/100`);
</script>
🏗️ Schema Hierarchy
All AIML v2.0.1 schemas follow this exact structure:
@type → entityCategory → subcategory → entityType
Examples:
Restaurant → organization → hospitality → restaurant
Marketplace → product_offering → ecommerce_platform → marketplace
SocialNetwork → community → social_platform → social_network
Complete Subcategories (15 total)
ecommerce_platform
,hospitality
,healthcare_services
education_services
,ai_platform
,professional_services
ridesharing_services
,website_services
,property_services
physical_product
,digital_product
,media_entertainment
social_platform
,event_platform
,financial_services
✅ Migration from v2.0.0
Removed in v2.0.1
- ❌
semanticProperties
- Subjective AI qualities - ❌
intentContext
- User intent contexts - ❌
appliedContexts
- External context references - ❌
context/
folder - Geographic/cultural contexts
Added in v2.0.1
- ✅
entityCapabilities
- Objective business capabilities - ✅
siteCapabilities
- Website interaction features - ✅ Enhanced validation with exact UI validator logic
- ✅ META-AIML Intelligent Scoring Engine with quality zones
🔄 Changelog
v2.1.0 (Latest)
- 🎯 EXACT UI VALIDATOR LOGIC: Same validation rules, scoring, and completeness
- 🔧 Enhanced error messages with actionable suggestions
- 📊 META-AIML Intelligent Scoring Engine with quality zones
- 🚀 Complete v2.0.1 support with new required fields
🤝 Contributing
Thank you for your interest.
However, this project does not accept external contributions at this time.
Please do not submit pull requests or feature requests.
We appreciate your understanding.
📄 License
Source-Available License - see LICENSE file.
🔗 Links
- GitHub Repository: https://github.com/meta-aiml-org/SDK
- NPM Package: https://www.npmjs.com/package/@meta-aiml/parser
- Meta-AIML.org: https://meta-aiml.org
- Schema Documentation: https://meta-aiml.org/docs
- UI Validator: https://meta-aiml.org/playground
Built for AI agents and developers. 🤖✨
Validated with the same engine that powers the official Meta-AIML.org UI validator.