{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/signatureapi-com/json-schema/signatureapi-com-upload-structure-schema.json",
  "title": "Structure",
  "description": "The analyzed structure of an uploaded file. Includes page dimensions, detected placeholders, and -- for DOCX templates -- detected template fields. Use this to verify that placeholders and fields are correctly positioned before creating an envelope.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/signatureapi-com-uploads-api-openapi.yml#/components/schemas/Upload.Structure",
  "x-schema-role": "model",
  "x-schema-direction": "output",
  "oneOf": [
    {
      "$ref": "#/$defs/Upload.PdfDocumentStructure"
    },
    {
      "$ref": "#/$defs/Upload.DocxDocumentStructure"
    }
  ],
  "$defs": {
    "Upload.DocxDocumentStructure": {
      "x-schema-role": "model",
      "x-schema-direction": "output",
      "title": "DOCX Document Structure",
      "description": "The analyzed structure of a DOCX upload. Includes page dimensions, detected placeholders, and detected template fields. DOCX documents support both placeholders (`[[key]]`) for positioning interactive elements and template fields (`{{key}}`) for dynamic data insertion.\n",
      "type": "object",
      "properties": {
        "format": {
          "allOf": [
            {
              "$ref": "#/$defs/Upload.Format"
            },
            {
              "const": "docx"
            }
          ]
        },
        "page_count": {
          "$ref": "#/$defs/Upload.PageCount"
        },
        "placeholders": {
          "$ref": "#/$defs/Upload.Placeholders"
        },
        "fields": {
          "$ref": "#/$defs/Upload.Fields"
        },
        "pages": {
          "$ref": "#/$defs/Upload.Pages"
        }
      },
      "required": [
        "format",
        "page_count",
        "placeholders",
        "fields",
        "pages"
      ]
    },
    "Upload.Field": {
      "x-schema-role": "model",
      "x-schema-direction": "output",
      "title": "Template Field",
      "description": "A template field detected in a DOCX template. Template fields use the `{{key}}` syntax and are replaced with data values when the document is generated. For example, `{{name}}` is replaced with the value provided in the document's `data` field.\n",
      "type": "object",
      "properties": {
        "key": {
          "$ref": "#/$defs/Upload.FieldKey"
        },
        "page_number": {
          "$ref": "#/$defs/Upload.FieldPageNumber"
        },
        "left": {
          "$ref": "#/$defs/Upload.FieldLeft"
        },
        "top": {
          "$ref": "#/$defs/Upload.FieldTop"
        },
        "width": {
          "$ref": "#/$defs/Upload.FieldWidth"
        },
        "height": {
          "$ref": "#/$defs/Upload.FieldHeight"
        },
        "errors": {
          "$ref": "#/$defs/Upload.FieldErrors"
        }
      },
      "required": [
        "key",
        "page_number",
        "left",
        "top",
        "width",
        "height",
        "errors"
      ]
    },
    "Upload.FieldErrors": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Template Field Errors",
      "description": "Validation errors detected for the template field. An empty array means the field is valid.\n",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "Upload.FieldHeight": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Template Field Height",
      "description": "The height in points (1/72 of an inch) of the template field.",
      "type": "number"
    },
    "Upload.FieldKey": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Template Field Key",
      "description": "The key of the template field, extracted from the `{{key}}` syntax in the DOCX template. Supports dot notation for nested data (e.g., `person.name`).\n",
      "type": "string"
    },
    "Upload.FieldLeft": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Template Field Left Distance",
      "description": "The distance in points (1/72 of an inch) from the left edge of the page to the left edge of the template field.\n",
      "type": "number"
    },
    "Upload.FieldPageNumber": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Page Number",
      "description": "The page number where the template field is located.",
      "type": "integer"
    },
    "Upload.FieldTop": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Template Field Top Distance",
      "description": "The distance in points (1/72 of an inch) from the top edge of the page to the bottom edge of the template field.\n",
      "type": "number"
    },
    "Upload.FieldWidth": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Template Field Width",
      "description": "The width in points (1/72 of an inch) of the template field.",
      "type": "number"
    },
    "Upload.Fields": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Template Fields",
      "description": "The template fields detected in the DOCX document. Template fields use the `{{key}}` syntax and are replaced with values from the document's `data` field when the document is generated. Only present for DOCX uploads.\n",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Upload.Field"
      }
    },
    "Upload.Format": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "type": "string",
      "title": "Format",
      "description": "The file format of the upload.\n\n- `pdf` -- A PDF file (`application/pdf`).\n- `docx` -- A DOCX file (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`).\n- `png` -- A PNG image (`image/png`).\n",
      "enum": [
        "pdf",
        "docx",
        "png"
      ]
    },
    "Upload.Page": {
      "x-schema-role": "model",
      "x-schema-direction": "output",
      "title": "Page",
      "description": "A page in the uploaded document, with its dimensions in points.",
      "type": "object",
      "properties": {
        "page_number": {
          "$ref": "#/$defs/Upload.PageNumber"
        },
        "height": {
          "$ref": "#/$defs/Upload.PageHeight"
        },
        "width": {
          "$ref": "#/$defs/Upload.PageWidth"
        }
      },
      "required": [
        "page_number",
        "height",
        "width"
      ]
    },
    "Upload.PageCount": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "type": "integer",
      "title": "Page Count",
      "description": "The total number of pages in the uploaded file."
    },
    "Upload.PageHeight": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "type": "number",
      "title": "Page Height",
      "description": "The height of the page in points (1/72 of an inch)"
    },
    "Upload.PageNumber": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "type": "integer",
      "title": "Page Number",
      "description": "The page number, starting from 1."
    },
    "Upload.PageWidth": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "type": "number",
      "title": "Page Width",
      "description": "The width of the page in points (1/72 of an inch)"
    },
    "Upload.Pages": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Pages",
      "description": "The pages in the uploaded document, including dimensions for each page.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Upload.Page"
      }
    },
    "Upload.PdfDocumentStructure": {
      "x-schema-role": "model",
      "x-schema-direction": "output",
      "title": "PDF Document Structure",
      "description": "The analyzed structure of a PDF upload. Includes page dimensions and detected placeholders. PDF documents support placeholders (`[[key]]`) for positioning signature fields and other interactive elements.\n",
      "type": "object",
      "properties": {
        "format": {
          "allOf": [
            {
              "$ref": "#/$defs/Upload.Format"
            },
            {
              "const": "pdf"
            }
          ]
        },
        "page_count": {
          "$ref": "#/$defs/Upload.PageCount"
        },
        "placeholders": {
          "$ref": "#/$defs/Upload.Placeholders"
        },
        "pages": {
          "$ref": "#/$defs/Upload.Pages"
        }
      },
      "required": [
        "format",
        "page_count",
        "placeholders",
        "pages"
      ],
      "additionalProperties": false
    },
    "Upload.Placeholder": {
      "x-schema-role": "model",
      "x-schema-direction": "output",
      "title": "Placeholder",
      "description": "A placeholder detected in an uploaded document. Placeholders use the `[[key]]` syntax and mark positions where signature fields and other interactive elements appear. The placeholder key must match the `key` of a place defined in the envelope.\n",
      "type": "object",
      "properties": {
        "key": {
          "$ref": "#/$defs/Upload.PlaceholderKey"
        },
        "page_number": {
          "$ref": "#/$defs/Upload.PlaceholderPageNumber"
        },
        "left": {
          "$ref": "#/$defs/Upload.PlaceholderLeft"
        },
        "top": {
          "$ref": "#/$defs/Upload.PlaceholderTop"
        },
        "width": {
          "$ref": "#/$defs/Upload.PlaceholderWidth"
        },
        "height": {
          "$ref": "#/$defs/Upload.PlaceholderHeight"
        },
        "errors": {
          "$ref": "#/$defs/Upload.PlaceholderErrors"
        }
      },
      "required": [
        "key",
        "page_number",
        "left",
        "top",
        "width",
        "height",
        "errors"
      ]
    },
    "Upload.PlaceholderErrors": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Placeholder Errors",
      "description": "Validation errors detected for the placeholder. An empty array means the placeholder is valid.\n",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "Upload.PlaceholderHeight": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Placeholder Height",
      "description": "The height in points (1/72 of an inch) of the placeholder.",
      "type": "number"
    },
    "Upload.PlaceholderKey": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Placeholder Key",
      "description": "The key of the placeholder, extracted from the `[[key]]` syntax in the document. Must match the `key` of a place defined in the envelope.\n",
      "type": "string"
    },
    "Upload.PlaceholderLeft": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Placeholder Left Distance",
      "description": "The distance in points (1/72 of an inch) from the left edge of the page to the left edge of the placeholder.\n",
      "type": "number"
    },
    "Upload.PlaceholderPageNumber": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Page Number",
      "description": "The page number where the placeholder is located.",
      "type": "integer"
    },
    "Upload.PlaceholderTop": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Placeholder Top Distance",
      "description": "The distance in points (1/72 of an inch) from the top edge of the page to the bottom edge of the placeholder.\n",
      "type": "number"
    },
    "Upload.PlaceholderWidth": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Placeholder Width",
      "description": "The width in points (1/72 of an inch) of the placeholder.",
      "type": "number"
    },
    "Upload.Placeholders": {
      "x-schema-role": "property",
      "x-schema-direction": "output",
      "title": "Placeholders",
      "description": "The placeholders detected in the document. Placeholders use the `[[key]]` syntax and mark positions where signature fields and other interactive elements appear during signing.\n",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Upload.Placeholder"
      }
    }
  }
}