# PortaShape Example Catalog ## Twelve Illustrative `.posh` Files ## Purpose of This Document This document contains twelve example PortaShape files designed to demonstrate the simplicity, flexibility, and potential depth of the `.posh` format. The examples use invented systems, fields, values, adapters, and data. They are intended to help people understand what PortaShape could feel like in practice. These examples are conceptual rather than normative. They do not define the final `.posh` specification. The final specification may change: * Key names * Required properties * Data types * Operation names * Validation syntax * Adapter declarations * Runtime behavior * Extension mechanisms * Versioning rules The examples progress from very small mappings to more sophisticated transformations. Most represent ordinary use cases that could be created through a simple visual interface. A user might drag one source value onto one destination value, accept a suggested transformation, and save the result as a `.posh` file. Only the final two examples demonstrate advanced or power-user scenarios. --- # Basic Examples ## Example 1: Rename and Transfer a Website Title ### Use Case A user is moving a website configuration from one system to another. The source system calls the website title `siteTitle`. The destination system calls the same value `projectName`. The user drags `siteTitle` onto `projectName` and saves the mapping. ### Example File: `website-title.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Website Title Mapping", "source": { "type": "object", "id": "old-site-config" }, "destination": { "type": "object", "id": "new-site-config" }, "mappings": [ { "id": "map-site-title", "source": "siteTitle", "destination": "projectName", "operation": "copy" } ] } } ``` ### What This Demonstrates This is the simplest PortaShape use case. One value in the source corresponds directly to one value in the destination. The names are different, but the meaning is the same. No custom migration script is necessary. --- ## Example 2: Transfer a Brand Color ### Use Case A website stores its primary brand color in a theme object. Another system stores the equivalent value as a design token. The user maps one color value to the other. ### Example File: `primary-color.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Primary Brand Color", "source": { "type": "theme", "id": "source-theme" }, "destination": { "type": "design-tokens", "id": "destination-tokens" }, "mappings": [ { "id": "map-primary-color", "source": "colors.primary", "destination": "color.brand.primary", "operation": "copy", "valueType": "color" } ] } } ``` ### What This Demonstrates PortaShape can preserve the meaning of a value even when the source and destination organize their information differently. The `valueType` metadata helps the interface recognize that the value should be displayed using a color control rather than a plain text field. --- ## Example 3: Transfer a User Theme Preference ### Use Case A user prefers dark mode in one application. Another application stores the same preference using a different field name. Because this is a user-focused preference, the mapping is placed inside the PortaShape `options` scope. ### Example File: `user-theme-option.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "options", "name": "User Theme Preference", "source": { "type": "user-profile", "id": "source-user" }, "destination": { "type": "user-profile", "id": "destination-user" }, "options": { "mappings": [ { "id": "map-theme-preference", "source": "preferences.theme", "destination": "display.colorMode", "operation": "copy", "allowedValues": [ "light", "dark", "system" ] } ] } } } ``` ### What This Demonstrates The example distinguishes a user option from a global system setting. The website may support several themes as a system-level setting, while an individual user’s selected theme remains an option. --- ## Example 4: Convert Pixels to Rem Units ### Use Case A source design system stores its base font size in pixels. The destination design system stores the same value in rem units. The user connects the two fields and chooses a built-in unit conversion. ### Example File: `font-size-conversion.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Base Font Size Conversion", "source": { "type": "design-system", "id": "pixel-theme" }, "destination": { "type": "design-system", "id": "rem-theme" }, "mappings": [ { "id": "convert-base-font-size", "source": "typography.baseFontSizePx", "destination": "typography.baseFontSizeRem", "operation": "translate", "transform": { "type": "unitConversion", "fromUnit": "px", "toUnit": "rem", "basePixelSize": 16 } } ] } } ``` ### What This Demonstrates PortaShape is not limited to copying data. A mapping can preserve the meaning of a value while changing how it is represented. A source value of `16` pixels would become `1` rem. A source value of `24` pixels would become `1.5` rem. --- ## Example 5: Translate Status Names with a Lookup Table ### Use Case A task system uses the statuses: * `todo` * `doing` * `done` A destination system uses: * `not_started` * `in_progress` * `complete` The user maps the status field and provides a small lookup table. ### Example File: `task-status-lookup.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Task Status Translation", "source": { "type": "task-list", "id": "simple-tasks" }, "destination": { "type": "project-manager", "id": "project-board" }, "mappings": [ { "id": "translate-task-status", "source": "task.status", "destination": "workItem.state", "operation": "translate", "transform": { "type": "lookup", "values": { "todo": "not_started", "doing": "in_progress", "done": "complete" }, "fallback": "not_started" } } ] } } ``` ### What This Demonstrates The source and destination agree on the concept but use different vocabularies. The user does not need to modify either system. PortaShape records the relationship between them. --- ## Example 6: Combine a First and Last Name ### Use Case A source system stores first and last names separately. The destination expects one display name. The user drags both source values onto the destination field and selects a text template. ### Example File: `display-name.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Create Display Name", "source": { "type": "contact-record", "id": "source-contact" }, "destination": { "type": "profile-record", "id": "destination-profile" }, "mappings": [ { "id": "combine-person-name", "source": [ "person.firstName", "person.lastName" ], "destination": "profile.displayName", "operation": "transmute", "transform": { "type": "template", "template": "{person.firstName} {person.lastName}", "trimWhitespace": true } } ] } } ``` ### What This Demonstrates Several source values can be combined to create one destination value. Although this is technically a transmutation, the user-facing workflow can remain very simple. --- ## Example 7: Split a Full Name into Two Fields ### Use Case A source system stores a person’s full name in one field. The destination system requires separate given-name and family-name values. The user maps the source value to both destination values and chooses a built-in name-splitting operation. ### Example File: `split-person-name.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Split Full Name", "source": { "type": "subscriber-list", "id": "newsletter-subscribers" }, "destination": { "type": "customer-database", "id": "customer-records" }, "mappings": [ { "id": "split-full-name", "source": "subscriber.fullName", "destination": [ "customer.givenName", "customer.familyName" ], "operation": "transmute", "transform": { "type": "personNameSplit", "givenNameTarget": "customer.givenName", "familyNameTarget": "customer.familyName", "fallbackBehavior": "placeInGivenName" } } ] } } ``` ### What This Demonstrates One source value can produce multiple destination values. The file also records what should happen when a source name cannot be split reliably. --- ## Example 8: Map a Navigation Label and URL ### Use Case A website migration needs to transfer one navigation item. The source system uses `label` and `url`. The destination system uses `text` and `href`. ### Example File: `navigation-item.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Navigation Item Mapping", "source": { "type": "navigation-item", "id": "source-nav-item" }, "destination": { "type": "menu-link", "id": "destination-menu-link" }, "mappings": [ { "id": "map-navigation-label", "source": "label", "destination": "text", "operation": "copy" }, { "id": "map-navigation-url", "source": "url", "destination": "href", "operation": "copy" } ] } } ``` ### What This Demonstrates A small PortaShape file can describe the complete translation of a simple structured object. The user could apply the same mapping to every item in a navigation collection. --- # Practical Everyday Examples ## Example 9: Capture a Website Settings and Options Snapshot ### Use Case A user wants to record the current configuration of a website before making changes. The snapshot distinguishes between global system settings and user-focused options. ### Example File: `website-snapshot.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "snapshot", "name": "Northstar Website Snapshot", "capturedAt": "2026-06-15T14:30:00Z", "source": { "type": "website", "id": "northstar-production", "environment": "production" }, "settings": { "siteName": "Northstar Studio", "defaultLocale": "en-US", "availableLocales": [ "en-US", "fr-CA" ], "theme": { "primaryColor": "#4A5CFF", "backgroundColor": "#FFFFFF", "baseFontFamily": "Inter" }, "features": { "searchEnabled": true, "customerPortalEnabled": false } }, "options": { "userId": "user-example-104", "colorMode": "dark", "dashboardDensity": "compact", "preferredLocale": "fr-CA", "reducedMotion": true }, "metadata": { "capturedBy": "runtime-interface", "reason": "Snapshot before theme update" } } } ``` ### What This Demonstrates Not every `.posh` file needs a source-to-destination mapping. A file can preserve the current state of a system. This snapshot could be used as: * A backup * A comparison point * A rollback reference * A migration source * A configuration record It also demonstrates the difference between settings and options. The site’s available languages are settings. The individual user’s preferred language is an option. --- ## Example 10: Transfer a Contact Form Submission into a CRM ### Use Case A website contact form sends a submission into a customer-management system. Most fields can be copied directly, while the destination’s lead source is assigned automatically. ### Example File: `contact-form-to-crm.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "mapping", "name": "Contact Form to CRM Lead", "source": { "type": "form-submission", "id": "website-contact-form" }, "destination": { "type": "crm-record", "id": "crm-lead" }, "mappings": [ { "id": "map-email", "source": "form.email", "destination": "lead.emailAddress", "operation": "copy", "required": true }, { "id": "map-name", "source": "form.name", "destination": "lead.displayName", "operation": "copy" }, { "id": "map-message", "source": "form.message", "destination": "lead.initialNote", "operation": "copy" }, { "id": "assign-lead-source", "destination": "lead.source", "operation": "constant", "value": "website-contact-form" } ], "validation": { "rules": [ { "id": "require-valid-email", "target": "lead.emailAddress", "type": "email" } ] } } } ``` ### What This Demonstrates A PortaShape mapping can combine copied values with generated or constant values. The same configuration can also describe basic validation. This type of file could be produced by a user connecting form fields to CRM fields in a visual editor. --- # Intermediate Examples ## Example 11: Migrate a Blog Article Between Content Systems ### Use Case A team is moving articles from one content-management system to another. The destination uses different field names and requires the source article’s author information to be converted into an author reference. The source URL is also rewritten for the new website structure. ### Example File: `blog-article-migration.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "migration", "name": "Article Migration", "source": { "type": "cms-entry", "adapter": "paperpress-cms", "contentType": "article" }, "destination": { "type": "cms-entry", "adapter": "brightfield-content", "contentType": "story" }, "mappings": [ { "id": "map-article-title", "source": "article.title", "destination": "story.headline", "operation": "copy", "required": true }, { "id": "map-article-body", "source": "article.bodyHtml", "destination": "story.content", "operation": "translate", "transform": { "type": "htmlToRichText" } }, { "id": "map-publication-date", "source": "article.publishedAt", "destination": "story.publishDate", "operation": "translate", "transform": { "type": "dateFormat", "input": "MM/DD/YYYY", "output": "YYYY-MM-DD" } }, { "id": "resolve-author", "source": "article.authorEmail", "destination": "story.authorReference", "operation": "translate", "transform": { "type": "referenceLookup", "collection": "authors", "sourceMatchField": "email", "destinationMatchField": "emailAddress", "returnField": "id" } }, { "id": "rewrite-article-path", "source": "article.slug", "destination": "story.path", "operation": "transmute", "transform": { "type": "template", "template": "/journal/{article.slug}" } } ], "validation": { "rules": [ { "id": "require-headline", "target": "story.headline", "type": "required" }, { "id": "require-author-reference", "target": "story.authorReference", "type": "referenceExists" }, { "id": "require-unique-path", "target": "story.path", "type": "unique" } ] }, "unresolvedBehavior": { "authorNotFound": "queueForReview", "invalidContent": "skipRecord" } } } ``` ### What This Demonstrates This example combines several ordinary migration needs: * Renaming fields * Converting content formats * Reformatting dates * Resolving references * Rewriting URLs * Validating the result Although the file is more detailed, each individual relationship can still be created through familiar visual controls. --- # Advanced Example ## Example 12: Transfer and Tune a Website Through a Shared Runtime Interface ### Use Case A company is rebuilding a website on a new platform. The team wants to transfer global settings, user options, design tokens, navigation, and animation behavior. They also want to preview values inside the shared runtime interface before applying them to the destination. This example includes: * Multiple source types * Several destinations * Settings * Options * Direct mappings * Translation * Transmutation * Runtime controls * Validation * Execution stages * Provenance * Unresolved-value handling ### Example File: `complete-site-transfer.posh` ```json { "portaShape": { "formatVersion": "0.1", "kind": "system-transfer", "name": "Northstar Website Transfer", "description": "Transfers the current website configuration, theme, navigation, and user preferences into the Horizon platform.", "sources": [ { "id": "source-site", "type": "website", "adapter": "northstar-runtime", "environment": "production" }, { "id": "source-theme", "type": "design-tokens", "adapter": "css-variables" }, { "id": "source-motion", "type": "animation-runtime", "adapter": "motion-engine" } ], "destinations": [ { "id": "destination-site", "type": "website", "adapter": "horizon-platform", "environment": "staging" }, { "id": "destination-theme", "type": "design-tokens", "adapter": "horizon-theme" }, { "id": "destination-motion", "type": "animation-config", "adapter": "horizon-motion" } ], "settings": { "mappings": [ { "id": "map-site-name", "source": { "system": "source-site", "path": "settings.siteName" }, "destination": { "system": "destination-site", "path": "project.name" }, "operation": "copy" }, { "id": "map-default-language", "source": { "system": "source-site", "path": "settings.defaultLocale" }, "destination": { "system": "destination-site", "path": "localization.defaultLanguage" }, "operation": "translate", "transform": { "type": "lookup", "values": { "en-US": "en", "fr-CA": "fr", "es-MX": "es" } } }, { "id": "map-primary-color", "source": { "system": "source-theme", "path": "--brand-primary" }, "destination": { "system": "destination-theme", "path": "color.action.primary" }, "operation": "copy", "valueType": "color" }, { "id": "generate-hover-color", "source": { "system": "source-theme", "path": "--brand-primary" }, "destination": { "system": "destination-theme", "path": "color.action.primaryHover" }, "operation": "transmute", "transform": { "type": "adjustColor", "lightness": -8 } }, { "id": "map-navigation", "source": { "system": "source-site", "path": "navigation.primary.items" }, "destination": { "system": "destination-site", "path": "menus.main.links" }, "operation": "translate", "transform": { "type": "collectionMap", "itemMappings": [ { "source": "label", "destination": "text", "operation": "copy" }, { "source": "url", "destination": "href", "operation": "copy" }, { "source": "openInNewWindow", "destination": "target", "operation": "translate", "transform": { "type": "lookup", "values": { "true": "_blank", "false": "_self" } } } ] } }, { "id": "map-page-transition-duration", "source": { "system": "source-motion", "path": "pageTransition.durationMs" }, "destination": { "system": "destination-motion", "path": "navigation.transition.durationSeconds" }, "operation": "translate", "transform": { "type": "unitConversion", "fromUnit": "ms", "toUnit": "s" } } ] }, "options": { "mappings": [ { "id": "map-user-color-mode", "source": { "system": "source-site", "path": "user.preferences.theme" }, "destination": { "system": "destination-site", "path": "account.options.colorMode" }, "operation": "copy" }, { "id": "map-reduced-motion", "source": { "system": "source-site", "path": "user.preferences.reduceMotion" }, "destination": { "system": "destination-site", "path": "account.options.motionPreference" }, "operation": "translate", "transform": { "type": "lookup", "values": { "true": "reduced", "false": "full" } } } ] }, "runtimeInterface": { "panels": [ { "id": "theme-preview", "title": "Theme Preview", "controls": [ { "mappingId": "map-primary-color", "controlType": "colorPicker", "allowTemporaryOverride": true }, { "mappingId": "generate-hover-color", "controlType": "colorPicker", "allowTemporaryOverride": true } ] }, { "id": "motion-preview", "title": "Motion Preview", "controls": [ { "mappingId": "map-page-transition-duration", "controlType": "slider", "minimum": 0, "maximum": 2, "step": 0.05, "unit": "seconds" } ] } ], "preview": { "destination": "destination-site", "mode": "staging", "applyChanges": "temporary" } }, "validation": { "rules": [ { "id": "require-site-name", "target": { "system": "destination-site", "path": "project.name" }, "type": "required" }, { "id": "validate-primary-color", "target": { "system": "destination-theme", "path": "color.action.primary" }, "type": "colorContrast", "against": "#FFFFFF", "minimumRatio": 4.5 }, { "id": "validate-navigation-links", "target": { "system": "destination-site", "path": "menus.main.links" }, "type": "urlReachability" }, { "id": "validate-motion-duration", "target": { "system": "destination-motion", "path": "navigation.transition.durationSeconds" }, "type": "range", "minimum": 0, "maximum": 2 } ] }, "execution": { "mode": "previewThenApply", "stages": [ { "id": "stage-settings", "name": "Transfer Global Settings", "includeScope": "settings" }, { "id": "stage-options", "name": "Transfer User Options", "includeScope": "options", "dependsOn": [ "stage-settings" ] }, { "id": "stage-validation", "name": "Validate Destination", "action": "runValidation", "dependsOn": [ "stage-settings", "stage-options" ] } ], "rollbackOnFailure": true }, "unresolvedBehavior": { "default": "queueForReview", "allowSilentDiscard": false }, "provenance": { "recordSourceValues": true, "recordTransforms": true, "recordDestinationValues": true, "recordUserApprovals": true }, "metadata": { "createdBy": "example-user", "purpose": "Demonstrate a complete website transfer", "tags": [ "website", "migration", "runtime", "theme", "motion" ] } } } ``` ### What This Demonstrates This example shows how PortaShape and the runtime interface can operate as one connected system. The mapping file does more than describe where values should go. It also describes: * How values should be transformed * Which mappings belong to settings * Which mappings belong to options * Which controls should appear in the runtime interface * How users can preview and tune the result * Which validation rules must pass * In which order the transfer should run * How failures should be handled * Which provenance information should be recorded Despite its size, the file is still composed of understandable building blocks. Each mapping represents a relationship that could be created visually. The complexity comes from combining many simple relationships, not from requiring every user to write a complex program. --- # Summary of the Twelve Examples ## Example 1: Website Title Demonstrates a direct one-to-one value mapping. ## Example 2: Brand Color Demonstrates mapping a typed visual value between different structures. ## Example 3: User Theme Preference Demonstrates a user-focused PortaShape option. ## Example 4: Pixel-to-Rem Conversion Demonstrates unit translation. ## Example 5: Status Lookup Demonstrates vocabulary translation through a lookup table. ## Example 6: Combined Display Name Demonstrates many-to-one transmutation. ## Example 7: Split Person Name Demonstrates one-to-many transmutation. ## Example 8: Navigation Item Demonstrates mapping a small structured object. ## Example 9: Website Snapshot Demonstrates capturing settings and options without performing a transfer. ## Example 10: Form to CRM Demonstrates a practical data integration with validation and generated values. ## Example 11: Article Migration Demonstrates a moderate content migration involving formats, references, URLs, and validation. ## Example 12: Complete Website Transfer Demonstrates an advanced system with multiple sources, destinations, runtime controls, settings, options, execution stages, validation, and provenance. --- # Central Design Principle The most important lesson from these examples is that PortaShape does not need to be complicated for ordinary users. A basic PortaShape file may contain only: * One source * One destination * One mapping A user may create that file by dragging one value onto another. Additional capabilities can appear only when needed: * Translation * Lookup tables * Templates * Validation * Settings * Options * Runtime controls * Collections * Execution stages * Provenance * Synchronization This allows PortaShape to support both ends of the complexity spectrum. It can be simple enough to rename and transfer one field, while remaining structured enough to describe the migration and reconstruction of an entire digital system.