ReferenceAutomation reference

Reading input validation results

Understand error positions, sequence normalization, and execution eligibility separately.

validate_input checks inputs against the selected tool's requirements. valid: false means the input did not meet those requirements, not that the validation API failed. Even valid: true neither authorizes execution nor establishes scientific accuracy. Check execution support separately with list_execution_options.

Original input and normalization

In a successful response, normalized contains defaults and model-specific normalization; notes contains related guidance. A failed response has no normalized suitable for execution. Do not alter the original arbitrarily just to pass validation.

sequenceDiagnostics reports character diagnostics only for sequence fields actually checked. Validation may stop at the first field error, so absent fields are not necessarily valid. It is not a complete inspection of a complex's molecule array either.

  • field — Name of the inspected input field.

  • positionBasis — One-based Unicode character positions in the original with whitespace removed. The chain separator : also counts as one position.

  • caseConversion — none means no automatic case conversion.

  • whitespaceRemoved — Whether whitespace was removed before inspection.

  • unknownResiduePolicy — The tool's policy for X. alphabet means it uses the allowed alphabet.

  • allowedAlphabet — Allowed characters for this sequence field.

  • removedUnknownResidues — Total X count and original positions removed in the normalization candidate.

  • invalidResidues — Total count, characters, and original positions of unsupported characters.

Each position list contains at most 100 entries. count is the total count; when truncated is true, some positions are omitted from the list. These positions differ from residue numbers in structure files.

When X is removed

X marks an unspecified amino acid. X-stripped removes such positions, whereas X-allowed retains X. Removal changes sequence length and position mapping. X-reject rejects inputs containing X.

For an educational example, validating AX C with an X-removing tool yields AC, with removal at position 2 in the whitespace-stripped original. AXBO may show an X-removal candidate while still failing overall because of other unsupported characters. Do not execute that partial normalization candidate.

Check erroneous characters against the original data. Do not replace or delete unverified characters. If the original contains unsupported characters, look for a tool that supports them. If you cannot establish this, leave execution on hold.

On this page