Map source data to Senzing JSON through a guided 8-step workflow. Use this INSTEAD of hand-coding Senzing JSON. Optional `environment` — one of snowflake, aws_lambda, azure_functions, kafka, spark, databricks (aliases such as spcs, snowpark, lambda, azure_function, kafka_connect, apache_kafka, apache_spark, pyspark, lakebase, unity_catalog, sz_databricks, databricks_sql are accepted) — names where this deployment runs; the response then opens with `environment_note`, the rules for that environment and the search_docs query to run before writing code or SQL. For mapping_workflow the note is on the start response only; dotted DB.SCHEMA.TABLE source labels (bare or with a data-file extension) infer environment=snowflake.
REQUIRED ARGUMENTS for action='start' — arguments, not files: `file_paths`, the source file name(s) exactly as the user gave them (a LABEL the server never opens, so pass it even when the file is not readable from here), AND `workspace_dir` (e.g. workspace_dir="/home/you/sz-workspace") — a writable directory where scripts, reference docs, mapper code, and outputs are saved. Do NOT assume /tmp exists (some environments like Kiro do not provide it). The call needs both arguments present; it does NOT need the file to exist. OPTIONAL on start: `output_path` — the output file the USER ASKED FOR, if any (a .jsonl path; a directory ending in / for one <schema_name>.jsonl per schema; or a per-schema map {"<schema_name>": "<path>.jsonl"}). Omit it for the default <workspace_dir>/<name>_output.jsonl. Start arguments are accepted at the top level or inside `payload`.
NO READABLE FILE, NO SHELL — START ANYWAY. If the user only DESCRIBED their columns, or you have no shell to run the profiler, step 1 accepts a `profile_summary` you write yourself: field_count from their column list, record_count as they stated it or 0 (zero means 'not measured' and is expected — it is not fabrication). An unreadable source file is NOT a reason to hand-code a mapping instead.
Actions: start, advance, back, status, reset. Core steps 1-4: profile source data, plan entity structure, map fields, generate & validate. Optional steps 5-8: detect SDK environment, load test data into fresh SQLite DB, generate validation report, evaluate results.
STATE: Every response returns a 'state' JSON object. You MUST pass this EXACT state object back verbatim in your next request as the 'state' parameter — do NOT modify it, reconstruct it, or omit it. The state is opaque and managed by the server. If you have lost the state, call with action='start' instead.
Common errors: (1) omitting state on advance — always include it, (2) reconstructing state from memory — always echo the exact JSON from the previous response, (3) omitting payload on advance — each step requires specific payload fields documented in the instructions (`data` is a legacy alias of `payload`), (4) omitting the file_paths or workspace_dir ARGUMENTS on start — the server needs the names, not a readable file.
Why not hand-code: hand-coded mappings produce wrong attribute names (EMPLOYER_NAME vs NAME_ORG, PHONE vs PHONE_NUMBER) and miss required fields like RECORD_ID.
View input schema
{
"type": "object",
"properties": {
"action": {
"description": "Action to perform. ONLY these values are valid: start, advance, back, status, reset.",
"type": [
"string",
"null"
],
"enum": [
"start",
"advance",
"back",
"status",
"reset",
null
],
"default": null
},
"file_paths": {
"description": "Source file paths (required for \"start\" action). Also accepted inside\n`data` — see `workspace_dir` for why both placements are honoured.",
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"default": null
},
"workspace_dir": {
"description": "Writable output directory (required for \"start\" action). Historically\nthis lived ONLY inside `data` while `file_paths` lived ONLY at the top\nlevel, so the two arguments of a single call sat in different places.\nClients reliably put both in one place — either place — and the half\nthat landed in the \"wrong\" one was silently dropped, producing a\n\"required\" error for an argument that WAS sent and forcing a retry.\nBoth placements are now accepted for both arguments; top level wins\nwhen a value is present in both.",
"type": [
"string",
"null"
],
"default": null
},
"output_path": {
"description": "Optional, \"start\" only: the output file the USER ASKED FOR, if any — the\nSenzing JSONL the mapper writes at step 4. Omit it to use the default\n`<workspace_dir>/<name>_output.jsonl`. Forms: a file path ending in\n`.jsonl` (absolute, or relative to workspace_dir; no `..`); a directory\nending in `/` (one `<dir>/<schema_name>.jsonl` per source schema); or a\nper-schema map `{\"<schema_name>\": \"<path>.jsonl\"}`. Accepted at the top\nlevel or inside `payload`/`data`, like workspace_dir.",
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"additionalProperties": {
"type": "string"
}
}
],
"default": null
},
"data": {
"description": "Step-specific data (for \"advance\" action). Legacy untyped channel; prefer\n`payload` (typed) when your client can satisfy it.",
"type": "object",
"default": null
},
"payload": {
"description": "Typed step payload for the \"advance\" action (H16). A discriminated `oneOf`\nover each step's accepted shape — pick the branch whose `for_step` equals\nthe step number you are advancing FROM. When present it is merged over\n`data` (payload wins); when absent, behavior is identical to sending `data`.",
"type": "object",
"oneOf": [
{
"title": "advance from step 1 (profile_source_data)",
"type": "object",
"properties": {
"profile_summary": {
"description": "One entry per source schema (table) discovered. Writable from the user's own description of their data — a readable file is not required.",
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"schema_name": {
"description": "Name of the source schema/table (for one flat file, its base name).",
"type": "string"
},
"record_count": {
"description": "Records in this schema. Use the profiler's count when it ran. If you could NOT read the file (the user only listed columns, or you have no shell), use the count the user stated, else 0. Zero is a legitimate, expected value — it means 'not measured', it is not fabrication, and it does not degrade the mapping.",
"type": "integer",
"minimum": 0
},
"field_count": {
"description": "Distinct fields/columns in this schema — countable from a pasted column list even when the file itself was never read.",
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false,
"required": [
"schema_name",
"record_count",
"field_count"
]
}
},
"capped_files": {
"type": "array",
"items": {
"type": "string"
}
},
"workspace_dir": {
"type": "string"
},
"for_step": {
"const": 1
}
},
"required": [
"profile_summary",
"for_step"
],
"additionalProperties": false
},
{
"title": "advance from step 2 (plan_entity_structure) — master-slot shape (master-less plan ungeneratable; required/enum/minItems subset, no contains/if-then)",
"type": "object",
"properties": {
"master_schemas": {
"description": "The main/primary entities (disposition 'master'). At least one is required — the slot IS the master disposition, so NO `disposition` field here.",
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"schema_name": {
"type": "string"
},
"data_source": {
"description": "UPPERCASE data source code",
"type": "string"
},
"record_type": {
"description": "Free text: the entity type of this source's records. The usual values are PERSON, ORGANIZATION, VESSEL and AIRCRAFT; any other value (e.g. VEHICLE) is accepted. Use the user's own value when the data already has one.",
"type": "string"
},
"record_id_source": {
"description": "field name of the stable natural key (PREFERRED), or RECORD_HASH only when no stable unique field exists",
"type": "string"
},
"field_count": {
"type": "integer"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"additionalProperties": false,
"required": [
"schema_name",
"data_source",
"record_type",
"record_id_source"
]
}
},
"support_schemas": {
"description": "Lookups, relationships, and child schemas that fold into the masters.",
"type": "array",
"items": {
"type": "object",
"properties": {
"schema_name": {
"type": "string"
},
"disposition": {
"enum": [
"lookup",
"relationship",
"child"
]
},
"key_field": {
"type": "string"
},
"join_key": {
"type": "string"
},
"from_key": {
"type": "string"
},
"to_key": {
"type": "string"
},
"role": {
"type": "string"
},
"field_count": {
"type": "integer"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"additionalProperties": false,
"required": [
"schema_name",
"disposition"
]
}
},
"questions": {
"type": "array"
},
"decisions": {
"type": "array"
},
"for_step": {
"const": 2
}
},
"required": [
"master_schemas",
"support_schemas",
"for_step"
],
"additionalProperties": false
},
{
"title": "advance from step 3 (map_fields)",
"type": "object",
"properties": {
"schema_mappings": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"schema_name": {
"type": "string"
},
"field_mappings": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"disposition": {
"const": "feature"
},
"feature": {
"description": "feature family, e.g. NAME",
"type": "string"
},
"attribute": {
"description": "attribute code, e.g. NAME_FULL",
"type": "string"
},
"custom": {
"description": "set true to deliberately map to a CUSTOM attribute not in the default Senzing spec (your schema added it); declare it via custom_attributes. Omit/false for standard catalog attributes.",
"type": "boolean"
},
"source_field": {
"type": "string"
},
"usage_type": {
"type": [
"string",
"null"
]
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"ref": {
"type": "string"
},
"ref_citation": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"disposition",
"feature",
"attribute"
]
},
{
"type": "object",
"properties": {
"disposition": {
"const": "payload"
},
"source_field": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"ref": {
"type": "string"
},
"ref_citation": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"disposition",
"source_field"
]
},
{
"type": "object",
"properties": {
"disposition": {
"const": "ignore"
},
"source_field": {
"type": "string"
},
"reason": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"ref": {
"type": "string"
},
"ref_citation": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"disposition",
"source_field"
]
},
{
"type": "object",
"properties": {
"disposition": {
"const": "derived"
},
"derived_as": {
"type": "string",
"enum": [
"DATA_SOURCE",
"RECORD_ID",
"RECORD_TYPE",
"REL_ANCHOR",
"REL_POINTER"
]
},
"source": {
"type": "string"
},
"source_field": {
"type": "string"
},
"value": {
"type": "string"
},
"justification": {
"description": "provenance for a constant derived RECORD_TYPE (validator-enforced)",
"type": "string"
},
"domain": {
"description": "for REL_ANCHOR/REL_POINTER",
"type": "string"
},
"role": {
"description": "for REL_POINTER",
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"ref": {
"type": "string"
},
"ref_citation": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"disposition",
"derived_as"
]
},
{
"type": "object",
"properties": {
"disposition": {
"const": "extract"
},
"source_field": {
"type": "string"
},
"expected_features": {
"type": "array",
"items": {
"type": "string"
}
},
"extraction_notes": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"ref": {
"type": "string"
},
"ref_citation": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"disposition",
"source_field",
"expected_features"
]
}
]
}
},
"code_mappings": {
"type": "object"
},
"type_discriminator": {
"type": "object"
}
},
"required": [
"schema_name",
"field_mappings"
]
}
},
"questions": {
"type": "array"
},
"decisions": {
"type": "array"
},
"for_step": {
"const": 3
}
},
"required": [
"schema_mappings",
"for_step"
]
},
{
"title": "advance from step 4 (generate_validate)",
"type": "object",
"properties": {
"verdict": {
"type": "string",
"enum": [
"approve",
"rework_mapping",
"rework_code"
]
},
"records_output": {
"type": "integer",
"minimum": 0
},
"output_path": {
"type": "string"
},
"for_step": {
"const": 4
}
},
"required": [
"verdict",
"for_step"
],
"additionalProperties": false
},
{
"title": "advance from step 5 (detect_environment)",
"type": "object",
"properties": {
"decision": {
"type": "string",
"enum": [
"skip",
"test_load"
]
},
"senzing_config": {
"type": "object"
},
"for_step": {
"const": 5
}
},
"required": [
"decision",
"for_step"
],
"additionalProperties": false
},
{
"title": "advance from step 6 (load_test_data)",
"type": "object",
"properties": {
"records_loaded": {
"type": "integer",
"minimum": 0
},
"load_errors": {
"type": "integer",
"minimum": 0
},
"for_step": {
"const": 6
}
},
"required": [
"records_loaded",
"for_step"
],
"additionalProperties": false
},
{
"title": "advance from step 7 (validation_report)",
"type": "object",
"properties": {
"report_generated": {
"const": true
},
"report_path": {
"type": "string"
},
"for_step": {
"const": 7
}
},
"required": [
"report_generated",
"for_step"
],
"additionalProperties": false
},
{
"title": "advance from step 8 (evaluate_results)",
"type": "object",
"properties": {
"verdict": {
"type": "string",
"enum": [
"approve",
"marginal",
"rework_mapping",
"rework_code"
]
},
"for_step": {
"const": 8
}
},
"required": [
"verdict",
"for_step"
],
"additionalProperties": false
}
],
"default": null
},
"environment": {
"description": "Optional, \"start\" only: where this deployment runs (an id or alias from\nthe tool description, e.g. snowflake, aws_lambda, kafka). The START\nresponse then opens with `environment_note` — that environment's rules\nand the search_docs query to run before writing the mapping view or\ncode; later steps never repeat it. Accepted at the top level or inside\n`payload`/`data`, like workspace_dir. Inferred as `snowflake` when a\nsource label is a dotted DB.SCHEMA.TABLE name (bare or with one data-file\nextension, e.g. CRM.PUBLIC.CUSTOMER.csv); an\nexplicit value wins. Omit when none applies.",
"type": [
"string",
"null"
],
"default": null,
"enum": [
"snowflake",
"aws_lambda",
"azure_functions",
"kafka",
"spark",
"databricks",
null
]
},
"state": {
"description": "Workflow state from previous response (required for all actions except \"start\").\nCRITICAL: Pass the EXACT 'state' JSON object from the previous mapping_workflow\nresponse verbatim — do NOT reconstruct, modify, or omit any fields.\nIf you have lost the state, call with action='start' instead.",
"type": "object",
"default": null
},
"version": {
"description": "Senzing version (default: \"current\").",
"type": "string",
"default": "current"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}