# Mappings Mappings are JSONata transformations that convert your source JSON data into the format required by a trading partner's EDI implementation. Each mapping targets a specific implementation schema and is used by outbound flows to generate EDI documents from your API submissions. ## The Mapping Editor The mapping editor has four tabs - **Source**, **Transform**, **Output**, and **Validate** - that represent each stage of the transformation process. Click a tab to view it. Pin a tab to keep it visible while you switch between others, letting you view multiple panes side-by-side. At the top of the editor: - **Implementation** selector: choose the target EDI implementation. The mapping's output must conform to this implementation's JSON schema. Click **View** to open the full implementation guide in a dialog. - **Settings**: update the mapping's name, description, and tags. - **Save**: persists changes to the transformation, implementation selection, source, and any settings changes. The button highlights when there are unsaved changes. Navigating away with unsaved changes triggers a confirmation prompt. ## Source The Source pane manages the sample JSON data used to test your transformation. A source is a representative example of the JSON your system will submit to the partner API endpoint. Sources are reusable: a single source can be shared across multiple mappings. When you update a shared source, Tediware warns you and lists the other mappings that will be affected. - **Select**: choose an existing source. - **New**: create a blank source. - **Generate**: have the AI assistant propose a source shaped around the target implementation. You can optionally provide a sample of your own data (CSV, SQL schema, field list, or XML/JSON) for it to follow, or instructions to steer the result. Generation requires an implementation to be selected. Review the proposal, refine it, then accept it into the Source pane and save. - **Save As New**: duplicate the current source as a new source with a different name. Sources should be short and *representative* of the data your system outputs. If you're outputting the source for an 856, for example, your source should not contain hundreds of items. It should contain just enough items to be a representative example. ### Semantics Semantics are optional markdown descriptions of the fields in your source. They help the AI assistant understand what each field represents, which is especially useful when your JSON keys are abbreviated or opaque (e.g., `ord_ln_qty` instead of `orderLineQuantity`). You can write semantics manually using the **Edit** toggle, or click **Generate** to have the AI assistant produce them automatically. Generation requires an implementation to be selected. Review and adjust generated semantics as needed. ## Transform The Transform pane contains the JSONata expression editor where you write (or generate) the transformation logic. - **Execute**: runs the transformation against the source sample. Results appear in the Output pane, and validation runs automatically. - **Generate** / **Refine**: opens the AI assistant. When the transformation is empty, the button reads **Generate**; otherwise it reads **Refine**. - **History**: opens the version history panel. An implementation must be selected and saved before you can execute a transformation. ## Output The Output pane shows the result of executing the transformation. It is read-only. - **JSON** / **EDI** / **Inspector** toggle: switch between the JSON output, the generated EDI, and a human-readable version. The EDI and Inspector views require a selected implementation and valid output (passing schema validation). - **Copy**: copies the current output to your clipboard. - **Review** / **Fix**: opens the AI assistant. When errors are present, the button reads **Fix**; otherwise it reads **Review**. The assistant can automatically fix errors, as well as review the output for accuracy. ## Validate The Validate pane checks the transformation output against the implementation's JSON schema using AJV (JSON Schema draft 2020-12). When validation fails, each error shows: - **Message**: what the error is. - **Instance path**: where in the output the error occurred. - **Keyword**: the JSON Schema keyword that failed (e.g., `required`, `type`, `enum`). - **Schema path**: where in the schema the constraint is defined. Transformation errors (JSONata syntax or runtime errors) are also displayed here, with position, error code, and token details when available. Click **Fix** to open the AI assistant with error context pre-loaded. In most cases, using the assistant is the quickest and easiest way to resolve validation errors. ## AI Assistant The mapping editor includes an AI assistant accessible from the assistant button in the header or from the contextual buttons on each pane. - **Chat**: ask questions about your mapping, source data, target schema, or JSONata syntax. The assistant can explain existing transformations, suggest approaches, and help debug issues. - **Generate**: direct the assistant to create or modify a JSONata transformation. It analyzes your source data, target implementation schema, and any existing errors, then iteratively generates and validates a transformation. You can provide additional instructions to guide the output. When the assistant produces a transformation, you can review and accept it to apply it directly to the editor. Chat history is preserved across interactions within the same session. ### Model Selection You can choose which AI model the assistant uses for generation from the assistant settings. The available models are controlled by the platform and may change over time. ## Settings and Version History ### Settings Click **Settings** to open the settings modal. You can update: - **Name**: the display name for the mapping. - **Description**: an optional description. - **Tags**: organizational labels. Changes made in the settings modal are staged locally until you click **Save** on the main editor. ### Version History Tediware automatically creates a new version each time you save changes to the transformation. Open the version history panel by clicking **History** in the Transform pane. From the version history you can: - Browse all previous versions with timestamps and author names. - View the full transformation for any version. - **View Diff**: compare a previous version against the current transformation side-by-side. - **Restore**: replace the current transformation with the selected version. - **Edit notes**: add a note to any version for future reference.