Overview

Enterprise users can define custom schema type definitions beyond ValidGraph’s standard 25 types. This allows validation of niche or proprietary schema types with configurable required/recommended/optional property rules.

How It Works

1. Admin creates a custom schema type definition
2. Defines which properties are required, recommended, or optional
3. Sets expected value types for each property
4. Custom types appear alongside standard types in all validation features
5. Custom types are scoped to the Enterprise account

Tier Availability

| Tier | Available |
|——|———–|
| Free | No |
| Pro | No |
| Agency | No |
| Enterprise | Yes |

Related Features

– Industry Presets: Pre-built validation profiles for common verticals
– Supported Schema Types: Standard types available in all tiers

Quick Start: Define a Custom Schema Type

Step 1: Plan your custom type
Decide what properties matter for your use case (e.g., CustomProperty for your SaaS).

Step 2: Create the type via API

curl -X POST https://api.validgraph.io/wp-json/validgraph/v1/custom-types 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "ServicePackage",
    "description": "Custom type for SaaS service packages",
    "extends": "https://schema.org/Service",
    "properties": {
      "packageName": {"type": "Text", "required": true},
      "monthlyPrice": {"type": "Number", "required": true},
      "maxUsers": {"type": "Integer", "recommended": true},
      "setupFee": {"type": "Number", "optional": true}
    }
  }'

Step 3: Use in validation
Your custom type now appears in validation reports for your enterprise account.

Step 4: Validate content with custom type

curl -X POST https://api.validgraph.io/wp-json/validgraph/v1/validate 
  -d '{
    "data_url": "https://example.com/pricing",
    "custom_types": ["ServicePackage"]
  }'

Technical Details

Custom Type Definition Schema

Request to create a custom type:

{
  "name": "ServicePackage",
  "description": "Proprietary SaaS service package offering",
  "extends": "https://schema.org/Service",
  "parent_type": "Service",
  "properties": {
    "packageName": {
      "type": "Text",
      "required": true,
      "description": "Name of the service package"
    },
    "monthlyPrice": {
      "type": "Number",
      "required": true,
      "description": "Monthly cost in USD"
    },
    "maxUsers": {
      "type": "Integer",
      "required": false,
      "recommended": true,
      "description": "Maximum number of users allowed"
    },
    "includedFeatures": {
      "type": "Text[]",
      "required": false,
      "recommended": true,
      "description": "Array of included features"
    },
    "setupFee": {
      "type": "Number",
      "required": false,
      "optional": true,
      "description": "One-time setup cost"
    },
    "trialDays": {
      "type": "Integer",
      "required": false,
      "optional": true,
      "description": "Free trial period in days"
    }
  },
  "scoring_weights": {
    "required": 3,
    "recommended": 2,
    "optional": 1
  }
}

Response Example

Create Custom Type Response:

{
  "success": true,
  "data": {
    "custom_type_id": "ct_servicepkg_001",
    "name": "ServicePackage",
    "status": "active",
    "created_at": "2024-03-20T10:15:00Z",
    "account_id": "acct_enterprise_123",
    "extends": "https://schema.org/Service",
    "properties_count": 6,
    "required_count": 2,
    "recommended_count": 2,
    "optional_count": 2,
    "definition_url": "https://api.validgraph.io/custom-types/ct_servicepkg_001"
  }
}

Validation Response with Custom Type

Request:

{
  "data_url": "https://saas.example.com/pricing",
  "custom_types": ["ServicePackage"]
}

Response:

{
  "success": true,
  "data": {
    "url": "https://saas.example.com/pricing",
    "validation_id": "val_custom_def789",
    "types": ["ServicePackage"],
    "custom_type_used": true,
    "score": 83,
    "completeness": {
      "ServicePackage": {
        "required": {
          "packageName": true,
          "monthlyPrice": true
        },
        "recommended": {
          "maxUsers": false,
          "includedFeatures": true
        },
        "optional": {
          "setupFee": true,
          "trialDays": false
        },
        "score": 83,
        "custom_type_id": "ct_servicepkg_001"
      }
    },
    "warnings": [
      {
        "type": "ServicePackage",
        "property": "maxUsers",
        "message": "Recommended property missing"
      }
    ]
  }
}

CRUD Operations on Custom Types

List all custom types:

GET /wp-json/validgraph/v1/custom-types

Get specific custom type:

GET /wp-json/validgraph/v1/custom-types/ct_servicepkg_001

Update custom type:

PUT /wp-json/validgraph/v1/custom-types/ct_servicepkg_001
{
  "description": "Updated description",
  "properties": {
    ...modified properties...
  }
}

Delete custom type:

DELETE /wp-json/validgraph/v1/custom-types/ct_servicepkg_001

Property Type Support

Supported property types for custom definitions:

– Scalars: Text, Number, Integer, Boolean, Date, DateTime, Time, URL, Email
– Complex: Object (for nested structures), Text[] (arrays)
– Schema.org types: Any schema.org type can be used (e.g., Person, Organization, ImageObject)

Example with complex properties:

{
  "properties": {
    "pricing": {
      "type": "Object",
      "required": true,
      "schema": {
        "basePrice": {"type": "Number"},
        "currency": {"type": "Text"}
      }
    },
    "team": {
      "type": "https://schema.org/Person",
      "required": false,
      "description": "Team member"
    },
    "features": {
      "type": "Text[]",
      "required": false
    }
  }
}

Validation with Multiple Custom Types

Enterprise can validate against multiple custom types simultaneously:

{
  "data_url": "https://example.com/page",
  "custom_types": ["ServicePackage", "PricingTier", "FeatureSet"]
}

Response includes validation results for all three custom types.

Scope and Access

– Account scoped: Custom types are private to the enterprise account
– No sharing: Custom types cannot be shared between accounts
– Version tracking: ValidGraph maintains version history of type definitions
– Backward compatibility: Changing existing type definitions doesn’t invalidate past validations

References

– Schema.org Service Type: https://schema.org/Service
– Schema.org Documentation: https://schema.org/docs/documents.html
– JSON Schema Specification: https://json-schema.org/
– Custom Schema Best Practices: https://example.com/docs/custom-schema-guide
– Enterprise Feature Documentation: https://example.com/docs/enterprise