StructuredEnvelopeField

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/inkseal-net/json-schema/inkseal-net-structured-envelope-field-schema.json",
  "title": "StructuredEnvelopeField",
  "description": "A field read model with public assignment, one-based page geometry, stored value, and fill attribution.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/inkseal-net-openapi.json#/components/schemas/StructuredEnvelopeField",
  "type": "object",
  "required": [
    "id",
    "name",
    "type",
    "label",
    "assignee",
    "required",
    "readonly",
    "page",
    "bounds",
    "value",
    "valueLabel",
    "validation",
    "options",
    "filledAt",
    "filledBy",
    "signature"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Public field id. This is the `fieldId` in `/envelopes/{envelopeId}/fields/{fieldId}/signature`."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Stable integration name, or null for an unnamed ad hoc field."
    },
    "type": {
      "$ref": "#/$defs/FieldType"
    },
    "label": {
      "type": [
        "string",
        "null"
      ]
    },
    "assignee": {
      "oneOf": [
        {
          "type": "string",
          "const": "sender"
        },
        {
          "type": "object",
          "required": [
            "signerId"
          ],
          "properties": {
            "signerId": {
              "type": "string",
              "description": "Public signer id."
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "required": {
      "type": "boolean"
    },
    "readonly": {
      "type": "boolean"
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "One-based document page number."
    },
    "bounds": {
      "type": "object",
      "required": [
        "xRatio",
        "yRatio",
        "widthRatio",
        "heightRatio"
      ],
      "properties": {
        "xRatio": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "yRatio": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "widthRatio": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1
        },
        "heightRatio": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    },
    "value": {
      "type": [
        "string",
        "null"
      ],
      "description": "Stored wire value, or null when unfilled."
    },
    "valueLabel": {
      "type": [
        "string",
        "null"
      ],
      "description": "The selected option label for select and radio fields. Null for other types and unfilled choices."
    },
    "validation": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "minLength": {
          "type": "integer",
          "minimum": 0
        },
        "maxLength": {
          "type": "integer",
          "minimum": 0
        },
        "pattern": {
          "type": "string"
        },
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        },
        "minDate": {
          "type": "string",
          "format": "date"
        },
        "maxDate": {
          "type": "string",
          "format": "date"
        }
      },
      "additionalProperties": false
    },
    "options": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "required": [
          "value",
          "label"
        ],
        "properties": {
          "value": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "filledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "filledBy": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "sender",
        "signer",
        null
      ]
    },
    "signature": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "required": [
            "url",
            "expiresAt"
          ],
          "properties": {
            "url": {
              "type": "string",
              "description": "Credential-authenticated API path for the image."
            },
            "expiresAt": {
              "type": "null",
              "description": "Always null. Access is checked on every request instead of delegated to an expiring storage URL."
            }
          },
          "additionalProperties": false
        }
      ]
    }
  },
  "$defs": {
    "FieldType": {
      "type": "string",
      "description": "How the field is filled and rendered. Values are stored as strings; signature and initials use images.",
      "enum": [
        "signature",
        "initials",
        "text",
        "date",
        "checkbox",
        "number",
        "email",
        "select",
        "radio",
        "textarea"
      ]
    }
  }
}