Output Schema

Shape agent results into JSON for APIs and downstream systems.

Table of contents

Schema and mapping

An Output Schema has two parts:

  • The schema is JSON Schema Draft 2020-12. It defines field names, types, objects, and arrays.
  • The mapping says which agent result or dimension value fills each position.

Open Output Schema from the Agents page menu. Once saved, it also appears as a button beside Create.

Start from the generated draft

If the project has no saved schema, Parsewise creates an unsaved draft from the current agents. Agents without dimensions become scalar fields. Agents that share dimensions are grouped into arrays of objects, with nested arrays where dimensions nest.

This draft is a starting point. It does not keep changing when agents change. Use Reset to rebuild it from the current configuration.

Edit

Tree and JSON edit the same schema and mapping. Tree view supports adding, renaming, removing, and mapping fields. JSON view shows the schema on the left and mapping on the right. Copy and paste are available in both views.

When the schema changes, Parsewise keeps mapping nodes whose field paths and structures still match and removes orphaned nodes. Pasting a mapping also removes fields outside the current schema.

Unsaved changes reopen automatically in the same browser and device while the server schema and mapping are unchanged. A server update invalidates that local draft. Discard clears it and returns to the saved server state, or to the blank starter when nothing has been saved. Reset replaces the draft with a newly generated base schema and mapping.

Map dimensions

Use arrays for repeated dimension values. For example, a Financial Year array can contain one object per year, and a nested Region array can contain one object per region within that year.

Mappings support six node kinds:

  • literal writes a fixed value.
  • scalar_from_agent writes a named agent’s resolved result.
  • dimension_value writes the current value of an enclosing dimension.
  • object maps named child properties.
  • array_from_dimension emits one item per dimension value.
  • object_from_dimension uses dimension values as object keys.

Agent and dimension references use names, so a mapping can be reused in another project with matching names. The editor filters agent choices to those compatible with the surrounding dimension path.

This example mapping emits years, includes each year value, and nests regions:

{
  "kind": "object",
  "properties": {
    "years": {
      "kind": "array_from_dimension",
      "agent_name": "Revenue",
      "dimension_name": "Financial Year",
      "item": {
        "kind": "object",
        "properties": {
          "year": {
            "kind": "dimension_value",
            "dimension_name": "Financial Year"
          },
          "revenue": {
            "kind": "scalar_from_agent",
            "agent_name": "Revenue",
            "dimension_filters": {
              "Scenario": "Actual"
            }
          },
          "regions": {
            "kind": "array_from_dimension",
            "agent_name": "Regional Sales",
            "dimension_name": "Region",
            "item": {
              "kind": "object",
              "properties": {
                "region": {
                  "kind": "dimension_value",
                  "dimension_name": "Region"
                },
                "sales": {
                  "kind": "scalar_from_agent",
                  "agent_name": "Regional Sales"
                }
              }
            }
          }
        }
      }
    }
  }
}

Here, the enclosing Financial Year array supplies the year for each Revenue lookup, while dimension_filters pins the agent’s Scenario dimension to Actual. Dimension names and values must exactly match the project configuration.

scalar_from_agent, array_from_dimension, and object_from_dimension can use dimension_filters to pin other dimensions. object_from_dimension maps each keyed value through its value_template.

Preview and save

The result preview updates from the current draft and existing project results. Enrichment is on by default, adding consistency status and links back to the underlying results.

Save persists the schema and mapping together. If fields are unmapped, choose either:

  • Keep unmapped to save the manual mapping and omit those fields from shaped results.
  • Map automatically to regenerate agents and the full mapping.

Mapping diagnostics identify missing or ambiguous names, incompatible types, and invalid dimension scope. Fix the project configuration or mapping, or regenerate automatically.

API use

Use GET and PUT /projects/{project_id}/schema/ to read or save the configuration. auto_map is required when saving. Read shaped output from GET /projects/{project_id}/results/schema/; append ?enrich=true for consistency and Parsewise links.

See the API Reference for examples.