mirror of https://github.com/johndoe6345789/metabuilder.git synced 2026-04-24 13:54:57 +00:00

Files

copilot-swe-agent[bot] 0ab852d227 Initial plan: Fix README styles documentation

Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>

2026-01-03 20:17:49 +00:00

11 KiB

Raw Permalink Blame History

MetaBuilder Schema Versioning Guide

Overview

This document outlines the versioning strategy for MetaBuilder package schemas, ensuring predictable evolution and backward compatibility.

Current Version: 2.0.0 Last Updated: 2026-01-01 Status: Active

Semantic Versioning

All MetaBuilder schemas follow Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH

Version Components

MAJOR: Incompatible API changes (breaking changes)
MINOR: New functionality in a backward-compatible manner
PATCH: Backward-compatible bug fixes

Examples

1.0.0 → 1.0.1  (Bug fix: corrected regex pattern)
1.0.1 → 1.1.0  (New feature: added optional field)
1.1.0 → 2.0.0  (Breaking: removed deprecated field)

Breaking Changes Policy

What Constitutes a Breaking Change?

A MAJOR version bump is required for:

Removing required fields

// v1.0.0
{"required": ["name", "email"]}

// v2.0.0 - BREAKING
{"required": ["name"]}  // email removed

Changing field types

// v1.0.0
{"type": "string"}

// v2.0.0 - BREAKING
{"type": "number"}

Restricting enum values

// v1.0.0
{"enum": ["read", "write", "admin"]}

// v2.0.0 - BREAKING
{"enum": ["read", "write"]}  // admin removed

Changing validation rules (stricter patterns, lower max values, etc.)

// v1.0.0
{"pattern": "^[a-z]+$"}

// v2.0.0 - BREAKING
{"pattern": "^[a-z]{3,}$"}  // now requires minimum 3 chars

Removing or renaming fields

// v1.0.0
{"field": {"type": "string"}}

// v2.0.0 - BREAKING
{"fieldName": {"type": "string"}}  // renamed

What is NOT a Breaking Change?

A MINOR version bump is sufficient for:

Adding optional fields

// v1.0.0
{"properties": {"name": {}}}

// v1.1.0 - OK
{"properties": {"name": {}, "description": {}}}

Expanding enum values

// v1.0.0
{"enum": ["read", "write"]}

// v1.1.0 - OK
{"enum": ["read", "write", "admin"]}

Relaxing validation (looser patterns, higher max values)

// v1.0.0
{"maxLength": 50}

// v1.1.0 - OK
{"maxLength": 100}

Adding new schema files
Improving documentation/descriptions
Adding examples

Deprecation Process

Deprecation Timeline

Announcement (Version N): Mark as deprecated, add warnings
Grace Period (Version N+1): Feature still works but logs warnings
Removal (Version N+2): Feature removed (breaking change)

Minimum Grace Period

Major schemas (metadata, entities, script): 6 months
Minor schemas (styles, forms): 3 months
Critical security fixes: May skip grace period

Example: Deprecating `field.primary`

v1.0.0 (2024-06-01)
  - field.primary supported

v1.5.0 (2024-09-01) - DEPRECATION ANNOUNCED
  - field.primary marked as deprecated
  - Documentation updated with migration guide
  - Schema validation emits warnings

v2.0.0 (2025-03-01) - REMOVAL (6 months later)
  - field.primary removed
  - entity.primaryKey is the only supported method
  - Schema validation fails for field.primary

Deprecation Markers

Use these patterns to deprecate fields:

{
  "field": {
    "type": "object",
    "properties": {
      "oldField": {
        "type": "string",
        "deprecated": {
          "since": "1.5.0",
          "reason": "Use newField instead for better type safety",
          "alternative": "newField",
          "removeIn": "2.0.0"
        }
      }
    }
  }
}

Or use JSON Schema not constraint:

{
  "field": {
    "not": {
      "required": ["primary"],
      "description": "DEPRECATED: field.primary is no longer supported. Use entity.primaryKey instead."
    }
  }
}

Version Compatibility Matrix

Schema Inter-Dependencies

Schema	v1.0	v1.5	v2.0
metadata	1.0.0	1.0.0	1.0.0
entities	1.0.0	1.0.0	2.0.0
types	1.0.0	1.0.0	1.0.0
script	1.0.0	2.1.0	2.2.0
validation	1.0.0	1.0.0	2.0.0
api	1.0.0	1.0.0	1.0.0
forms	1.0.0	1.0.0	1.1.0
config	1.0.0	1.0.0	1.0.0

Runtime Compatibility

Schemas can be mixed across MINOR versions
All schemas in a package must use compatible MAJOR versions
Runtime validates schema compatibility on load

Migration Guides

General Migration Steps

Audit current usage

# Find deprecated field usage
grep -r '"primary":' entities/

Update schema version

{
  "schemaVersion": "2.0.0"  // Update from "1.0.0"
}

Apply schema-specific migrations (see below)

Validate

./schema_validator.sh entities/schema.json

Test thoroughly

Schema-Specific Migrations

Entities Schema: v1.0 → v2.0

Change: field.primary → entity.primaryKey

// migrate-entities-v2.js
function migrate(schema) {
  for (const entity of schema.entities) {
    let primaryKey = null;

    // Find and remove field.primary
    for (const [name, field] of Object.entries(entity.fields)) {
      if (field.primary) {
        primaryKey = name;
        delete field.primary;  // Remove deprecated
      }
    }

    // Set entity.primaryKey
    if (primaryKey && !entity.primaryKey) {
      entity.primaryKey = primaryKey;
    }
  }

  schema.schemaVersion = "2.0.0";
  return schema;
}

CLI Migration:

# Automated migration
node scripts/migrate-entities-v2.js entities/schema.json

# Manual migration
# 1. Move primary key to entity level
# 2. Remove field.primary properties
# 3. Update schemaVersion to "2.0.0"

Validation Schema: v1.0 → v2.0

Change: sanitize default changed from false → true

// v1.0.0 - explicit opt-in
{
  "params": [{
    "name": "userInput",
    "type": "string",
    "sanitize": true  // Must explicitly enable
  }]
}

// v2.0.0 - secure by default
{
  "params": [{
    "name": "userInput",
    "type": "string"
    // sanitize: true is now default
  }]
}

Migration:

# If you need unsanitized input (rare!), explicitly disable:
{
  "params": [{
    "name": "trustedContent",
    "type": "string",
    "sanitize": false  // ONLY for trusted sources
  }]
}

Script Schema: v2.1 → v2.2

Change: Added visual programming metadata (non-breaking)

// v2.1.0 - basic function
{
  "functions": [{
    "id": "calc",
    "name": "calculate",
    "params": [],
    "body": []
  }]
}

// v2.2.0 - with visual metadata (optional)
{
  "functions": [{
    "id": "calc",
    "name": "calculate",
    "params": [],
    "body": [],
    "visual": {  // NEW: optional visual metadata
      "icon": "💰",
      "color": "#27ae60",
      "category": "math"
    }
  }]
}

Migration: No changes required (backward compatible)

Release Process

Pre-Release Checklist

All tests pass
Documentation updated
CHANGELOG.md updated
Migration guide written (for MAJOR)
Examples updated
Deprecation warnings added (if applicable)

Release Types

Patch Release (1.0.0 → 1.0.1)

Bug fixes only
No API changes
Immediate release

Minor Release (1.0.0 → 1.1.0)

New features
Backward compatible
1-week beta period

Major Release (1.0.0 → 2.0.0)

Breaking changes
4-week beta period
Migration tools provided
Blog post announcement

Release Channels

Stable: Production-ready releases
Beta: Feature-complete, testing phase
Alpha: Early access, may have bugs
Nightly: Automated builds, unstable

Backward Compatibility Guarantees

What We Guarantee

✅ Within MAJOR versions:

Existing valid data remains valid
No required fields added
Enum values not removed
Validation not stricter

✅ Across MINOR versions:

Can upgrade without code changes
New features are optional

What We Don't Guarantee

❌ Internal implementation:

Validation algorithm changes
Error message format
Schema file organization

❌ Deprecated features:

May be removed in next MAJOR version
No guarantee of continued support

❌ Alpha/Beta releases:

No stability guarantees
Breaking changes allowed

Version Detection

Runtime Version Check

import { validateSchemaVersion } from '@metabuilder/schema-validator';

const schema = require('./entities/schema.json');

// Check compatibility
const result = validateSchemaVersion(schema, {
  expected: '2.x.x',  // Accept any 2.x version
  strict: false        // Allow newer versions
});

if (!result.compatible) {
  console.error(`Incompatible schema version: ${result.message}`);
}

Schema Version in Files

All schema files must include schemaVersion:

{
  "$schema": "https://metabuilder.dev/schemas/entities.schema.json",
  "schemaVersion": "2.0.0",
  "entities": [...]
}

Changelog Format

Use Keep a Changelog format:

## [2.0.0] - 2025-03-01

### Breaking Changes
- **entities**: Removed `field.primary`, use `entity.primaryKey` instead
- **validation**: Changed `sanitize` default from `false` to `true`

### Added
- **forms**: Added ARIA accessibility properties
- **validation**: Added `ValidationResult` type definition

### Changed
- **config**: Improved security guidance for secret providers

### Deprecated
- Nothing deprecated in this release

### Removed
- **entities**: `field.primary` (deprecated in v1.5.0)

### Fixed
- **api**: Fixed body validation defaults documentation

### Security
- **validation**: Input sanitization now enabled by default

Getting Help

Check the migration guide for your version
Search GitHub Issues
Ask in Discord #schema-help
Email: schemas@metabuilder.dev

Reporting Bugs

Include:

Current schema version
Target schema version
Minimal reproduction example
Migration steps attempted

Contributing

Proposing Breaking Changes

Open GitHub issue with [BREAKING] prefix
Explain rationale and migration path
Wait for community feedback (minimum 2 weeks)
Submit PR with migration guide

Version Bump Guidelines

When submitting a PR, increment the version in:

Schema file schemaVersion field
CHANGELOG.md
Documentation examples

Appendix

Quick Reference

Change Type	Version Bump	Example
Bug fix	PATCH	1.0.0 → 1.0.1
New optional field	MINOR	1.0.0 → 1.1.0
New schema file	MINOR	1.0.0 → 1.1.0
Enum expansion	MINOR	1.0.0 → 1.1.0
Remove required field	MAJOR	1.0.0 → 2.0.0
Rename field	MAJOR	1.0.0 → 2.0.0
Enum restriction	MAJOR	1.0.0 → 2.0.0
Stricter validation	MAJOR	1.0.0 → 2.0.0

SCHEMAS_README.md - Schema overview
QUICKSTART.md - Getting started guide
IMPROVEMENTS_SUMMARY.md - Recent changes
CHANGELOG.md - Version history

Document Version: 1.0.0 Last Updated: 2026-01-01 Maintained by: MetaBuilder Team

Generated with Claude Code

11 KiB Raw Permalink Blame History