Skip to main content

Implementation Best Practices

This guide provides essential best practices for implementing MVMD-compliant metadata in your projects to ensure interoperability, performance, and maintainability.

Metadata Structure & Design

Schema Organization

  • Use Consistent Namespaces: Always include proper context declarations for Schema.org and MVMD vocabularies
  • Choose Appropriate Types: Select the most specific Schema.org type for your asset
  • Follow Type Hierarchy: Respect parent-child relationships in Schema.org types
  • Group Related Properties: Organize properties logically for readability
{
"@context": {
"@vocab": "https://schema.org/",
"mvmd": "https://mvmd.org/v1/"
},
"@type": "3DModel",
"name": "Example Asset",
"description": "This is an example of proper schema organization"
}

Identity & Reference Management

  • Provide Unique Identifiers: Use consistent identification mechanisms
  • Link Related Assets: Use proper references between related assets
  • Maintain Reference Integrity: Ensure all references are valid and resolvable
  • Support Multiple Reference Methods: Include both URIs and content-addressed references when possible
{
"@context": {
"@vocab": "https://schema.org/",
"mvmd": "https://mvmd.org/v1/"
},
"@type": "3DModel",
"@id": "https://example.com/assets/model-123",
"identifier": {
"@type": "PropertyValue",
"propertyID": "assetId",
"value": "model-123"
},
"sameAs": [
"ipfs://QmXaXa1XaX...",
"ar://asset/model123"
]
}

Technical Implementation

Performance Optimization

  • Minimize Metadata Size: Include only necessary properties
  • Use Appropriate Data Types: Match data types to expected values
  • Implement Progressive Loading: Structure metadata to support incremental loading
  • Balance Embedding vs. Linking: Reference large or commonly reused components

Validation & Testing

  • Validate Against Schemas: Use MVMD validation tools for all metadata
  • Test Cross-Platform Compatibility: Verify metadata works across different systems
  • Check Reference Integrity: Ensure all linked resources are accessible
  • Verify Required Properties: Confirm all required properties exist and have valid values
# Example validation command
npm run validate-mvmd ./assets/metadata.json

Version Control

  • Include Version Information: Add version numbers to all metadata
  • Document Version Compatibility: Specify which versions work together
  • Maintain Backward Compatibility: Support older schema versions when possible
  • Track Metadata Evolution: Keep history of metadata changes alongside asset changes
{
"@context": {
"@vocab": "https://schema.org/",
"mvmd": "https://mvmd.org/v1/"
},
"@type": "3DModel",
"name": "Example Asset",
"version": "2.1.0",
"additionalProperty": [
{
"@type": "PropertyValue",
"propertyID": "schemaVersion",
"name": "Schema Version",
"value": "1.2.0"
}
]
}

Content & Metadata Management

Rights Management

  • Specify Clear Licenses: Include explicit license information
  • Document Usage Rights: Define how assets can be used
  • Credit Contributors: Include proper attribution for all creators
  • Link to Terms: Provide references to detailed license terms
{
"@context": {
"@vocab": "https://schema.org/",
"mvmd": "https://mvmd.org/v1/"
},
"@type": "3DModel",
"name": "Example Asset",
"license": "https://creativecommons.org/licenses/by/4.0/",
"creator": {
"@type": "Person",
"name": "Asset Creator",
"url": "https://creator.example.com"
},
"copyrightHolder": {
"@type": "Organization",
"name": "Example Studio",
"url": "https://studio.example.com"
}
}

Documentation

  • Include Comprehensive Metadata: Document all relevant asset characteristics
  • Add Implementation Notes: Provide guidance for developers working with your assets
  • Document Technical Requirements: Specify system requirements and dependencies
  • Maintain Technical Documentation: Keep documentation in sync with metadata changes

Storage & Distribution

  • Use Content-Addressed Storage: Implement content-addressed storage for immutability
  • Implement CDN Delivery: Use content delivery networks for efficient distribution
  • Configure Proper Caching: Set appropriate cache control headers
  • Plan for Redundancy: Use multiple storage solutions for critical assets

Process & Workflow

Integration Pipeline

  • Automate Metadata Generation: Build automated tools to create and update metadata
  • Implement Validation Checks: Add validation to your CI/CD pipeline
  • Document Generation Process: Create clear documentation for metadata generation
  • Review Generated Metadata: Periodically review automated output for quality

Maintenance Strategy

  • Establish Update Procedures: Define processes for metadata updates
  • Monitor Reference Health: Regularly check that all references remain valid
  • Plan for Schema Evolution: Prepare for future schema changes
  • Implement Deprecation Policies: Create clear policies for obsolete assets and formats