Purpose

This guide provides complete workflows for working with EXPRESS schema manifests, from creation through validation to package building. Manifests are essential for managing complex schema collections and ensuring reproducible builds.

What You’ll Learn

  • How to create manifests from root schemas

  • When to use manifests vs auto-resolution

  • How to resolve missing schema paths

  • Validating manifests for completeness and integrity

  • Building LER packages from manifests

Prerequisites

Complete Workflow

The typical manifest workflow consists of these steps:

┌─────────────────────┐
│  1. Create Manifest │  ← From root schema(s)
│   from Root Schema  │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  2. Review Manifest │  ← Check for unresolved schemas
│   and Edit Paths    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  3. Resolve Missing │  ← Auto-resolve or manual edit
│   Schema Paths      │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  4. Validate        │  ← Check integrity
│   Manifest          │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  5. Build LER       │  ← Create package
│   Package           │
└─────────────────────┘

Quick Start Example

Here’s a complete example workflow:

# Step 1: Create manifest from root schema
expressir manifest create schemas/activity/mim.exp \
  -o activity_manifest.yaml \
  --base-dirs ~/iso-10303/schemas \
  --verbose

# Step 2: Review unresolved schemas in the output
# Edit activity_manifest.yaml to add missing paths

# Step 3: Try auto-resolution for remaining schemas
expressir manifest resolve activity_manifest.yaml \
  -o resolved_manifest.yaml \
  --verbose

# Step 4: Validate the manifest
expressir manifest validate resolved_manifest.yaml \
  --check-references \
  --verbose

# Step 5: Build the package
expressir package build \
  --manifest resolved_manifest.yaml \
  activity.ler \
  --validate

When to Use Manifests

Use manifests when:

  • Working with 10+ interdependent schemas

  • Schemas are in non-standard locations

  • You need reproducible builds

  • Managing circular dependencies

  • Building production packages

  • Documenting schema relationships

Use auto-resolution when:

  • Quick prototyping or development

  • Schemas follow standard naming conventions

  • All schemas are in standard locations

  • Simple dependency structures

Guide Contents

Creating Manifests

Learn how to generate manifests from root schemas, understanding resolved vs unresolved schemas, and editing manifests to add missing paths.

Topics covered:

  • Using expressir manifest create

  • Understanding manifest structure

  • Interpreting creation output

  • Adding base directories

  • Handling circular dependencies

Resolving Manifests

Discover how to automatically resolve missing schema paths and when to use the resolve command.

Topics covered:

  • Using expressir manifest resolve

  • Auto-resolution patterns

  • When to use resolve vs manual editing

  • Troubleshooting resolution failures

Validating Manifests

Master manifest validation at different levels and learn to interpret validation errors.

Topics covered:

  • Basic validation (file existence)

  • Referential integrity checking

  • Using --check-references flag

  • Interpreting validation errors

  • Fixing validation issues

Best Practices

Always validate before building:

expressir manifest validate manifest.yaml --check-references

Use verbose mode during development:

expressir manifest create schema.exp -o manifest.yaml --verbose

Version control your manifests:

git add manifest.yaml
git commit -m "Add schema manifest for activity module"

Document unresolved schemas: Add comments in the YAML to explain why certain schemas are unresolved:

schemas:
  Activity_method_mim:  # TODO: Waiting for upstream release

Keep base directories minimal: Only include necessary search directories to avoid false matches.

Common Patterns

Pattern 1: Standard Module Build

For a typical STEP module with standard structure:

expressir manifest create schemas/modules/activity/mim.exp \
  -o activity.yaml \
  --base-dirs schemas/resources,schemas/modules

expressir manifest validate activity.yaml --check-references
expressir package build --manifest activity.yaml activity.ler

Pattern 2: Mixed Resource and Module Schemas

When combining different schema types:

expressir manifest create \
  schemas/resources/geometry.exp \
  schemas/modules/mechanical/arm.exp \
  -o combined.yaml \
  --base-dirs schemas/resources,schemas/modules,schemas/integrated

expressir manifest validate combined.yaml --check-references --verbose
expressir package build --manifest combined.yaml combined.ler

Pattern 3: Incremental Resolution

For schemas with many missing dependencies:

# Initial creation
expressir manifest create root.exp -o manifest.yaml \
  --base-dirs schemas/

# First resolution attempt
expressir manifest resolve manifest.yaml -o resolved1.yaml

# Manual editing of resolved1.yaml
# Add paths for schemas that couldn't be auto-resolved

# Second resolution with additional base dirs
expressir manifest resolve resolved1.yaml -o resolved2.yaml \
  --base-dirs schemas/,additional/schemas/

# Validate
expressir manifest validate resolved2.yaml --check-references

# Build
expressir package build --manifest resolved2.yaml output.ler

Troubleshooting

Problem: Many Unresolved Schemas

Symptom: Manifest creation shows many schemas without paths

Solutions:

  1. Add more base directories: bash expressir manifest create root.exp -o manifest.yaml \ --base-dirs dir1,dir2,dir3

  2. Use the resolve command: bash expressir manifest resolve manifest.yaml -o resolved.yaml \ --base-dirs additional/dirs

  3. Manually edit the manifest to add known paths

Problem: Circular Dependency Warnings

Symptom: Warnings about circular references during creation

Solution: This is normal for schema-level circular dependencies in EXPRESS. The warning is informational only. Both schemas will be included correctly.

Problem: Validation Fails with Missing References

Symptom: --check-references reports unresolved USE FROM or REFERENCE FROM

Solutions:

  1. Check if schema files actually exist at specified paths

  2. Verify schema names match actual SCHEMA declarations in files

  3. Add missing schemas to manifest with correct paths

  4. Use --verbose to see which schemas are being checked

Problem: Package Build Fails After Successful Validation

Symptom: Manifest validates but package build fails

Solutions:

  1. Ensure all schema files are readable

  2. Check for syntax errors in EXPRESS files

  3. Verify file encodings (should be UTF-8)

  4. Use --verbose flag on build command

Next Steps

Now that you understand the manifest workflow:

Deep dive into creation

Read Creating Manifests for detailed guidance

Learn resolution techniques

Explore Resolving Manifests

Master validation

Study Validating Manifests

Build production packages

See LER Packages for packaging details

Bibliography