# htmlToFragment

> Convert an HTML string into an SDM/1 structural fragment.



- Member path: `doc.htmlToFragment(…)`
- Mutates document: no
- Idempotency: `idempotent`
- Supports tracked mode: no
- Supports dry run: no

## Expected result

Returns an SDHtmlToFragmentResult with the converted fragment, lossy flag, and diagnostics.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "html": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "html"
  ]
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "SDInboundInlineNode": {
      "oneOf": [
        {
          "$ref": "#/$defs/SDInboundRun"
        },
        {
          "$ref": "#/$defs/SDInboundHyperlink"
        },
        {
          "$ref": "#/$defs/SDInboundLineBreak"
        }
      ]
    },
    "SDInboundRun": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "run"
        },
        "run": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string"
            },
            "styleRef": {
              "type": "string"
            },
            "props": {
              "$ref": "#/$defs/SDInboundRunProps"
            }
          },
          "additionalProperties": false,
          "required": [
            "text"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "run"
      ]
    },
    "SDInboundRunProps": {
      "type": "object",
      "properties": {
        "bold": {
          "type": "boolean"
        },
        "italic": {
          "type": "boolean"
        },
        "underline": {
          "$ref": "#/$defs/SDInboundUnderline"
        },
        "strikethrough": {
          "type": "boolean"
        },
        "color": {
          "$ref": "#/$defs/SDInboundColor"
        },
        "highlight": {
          "const": "yellow"
        },
        "shading": {
          "$ref": "#/$defs/SDInboundShading"
        },
        "fontSize": {
          "type": "number",
          "exclusiveMinimum": 0
        },
        "fontFamily": {
          "type": "string",
          "minLength": 1
        },
        "verticalAlign": {
          "enum": [
            "baseline",
            "superscript",
            "subscript"
          ]
        }
      },
      "additionalProperties": false
    },
    "SDInboundUnderline": {
      "type": "object",
      "properties": {
        "style": {
          "const": "single"
        }
      },
      "additionalProperties": false
    },
    "SDInboundColor": {
      "type": "object",
      "properties": {
        "model": {
          "const": "rgb"
        },
        "value": {
          "type": "string",
          "pattern": "^[0-9A-Fa-f]{6}$"
        }
      },
      "additionalProperties": false,
      "required": [
        "model",
        "value"
      ]
    },
    "SDInboundShading": {
      "type": "object",
      "properties": {
        "pattern": {
          "type": "string"
        },
        "fill": {
          "$ref": "#/$defs/SDInboundColor"
        },
        "color": {
          "$ref": "#/$defs/SDInboundColor"
        }
      },
      "additionalProperties": false
    },
    "SDInboundHyperlink": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "hyperlink"
        },
        "hyperlink": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "pattern": "^(?:[Hh][Tt][Tt][Pp][Ss]?:|[Mm][Aa][Ii][Ll][Tt][Oo]:)"
            },
            "tooltip": {
              "type": "string"
            },
            "targetFrame": {
              "type": "string"
            },
            "history": {
              "type": "boolean"
            },
            "inlines": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/SDInboundHyperlinkLeaf"
              }
            }
          },
          "additionalProperties": false,
          "required": [
            "href",
            "inlines"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "hyperlink"
      ]
    },
    "SDInboundHyperlinkLeaf": {
      "oneOf": [
        {
          "$ref": "#/$defs/SDInboundRun"
        },
        {
          "$ref": "#/$defs/SDInboundLineBreak"
        }
      ]
    },
    "SDInboundLineBreak": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "lineBreak"
        },
        "lineBreak": {
          "type": "object",
          "properties": {},
          "additionalProperties": false
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "lineBreak"
      ]
    },
    "SDInboundParagraphProps": {
      "type": "object",
      "properties": {
        "alignment": {
          "enum": [
            "left",
            "center",
            "right",
            "justify"
          ]
        },
        "indent": {
          "$ref": "#/$defs/SDInboundParagraphIndent"
        },
        "spacing": {
          "$ref": "#/$defs/SDInboundParagraphSpacing"
        }
      },
      "additionalProperties": false
    },
    "SDInboundParagraphIndent": {
      "type": "object",
      "properties": {
        "start": {
          "type": "number"
        },
        "end": {
          "type": "number"
        },
        "left": {
          "type": "number"
        },
        "right": {
          "type": "number"
        },
        "firstLine": {
          "type": "number"
        },
        "hanging": {
          "type": "number"
        }
      },
      "additionalProperties": false
    },
    "SDInboundParagraphSpacing": {
      "type": "object",
      "properties": {
        "before": {
          "type": "number"
        },
        "after": {
          "type": "number"
        },
        "line": {
          "type": "number"
        },
        "lineRule": {
          "enum": [
            "auto",
            "exact",
            "atLeast"
          ]
        }
      },
      "additionalProperties": false
    },
    "SDInboundListLevel": {
      "type": "object",
      "properties": {
        "level": {
          "type": "integer",
          "minimum": 0,
          "maximum": 8
        },
        "kind": {
          "enum": [
            "ordered",
            "bullet"
          ]
        },
        "format": {
          "enum": [
            "decimal",
            "lowerLetter",
            "upperLetter",
            "lowerRoman",
            "upperRoman"
          ]
        },
        "text": {
          "type": "string",
          "pattern": "^%[1-9][.)]$"
        },
        "start": {
          "type": "integer",
          "minimum": 1
        }
      },
      "additionalProperties": false,
      "required": [
        "level",
        "kind"
      ]
    },
    "SDInboundListItem": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "level": {
          "type": "integer",
          "minimum": 0,
          "maximum": 8
        },
        "path": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0
          }
        },
        "marker": {
          "type": "string"
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SDInboundContentNode"
          },
          "minItems": 1
        }
      },
      "additionalProperties": false,
      "required": [
        "level",
        "content"
      ]
    },
    "SDInboundContentNode": {
      "oneOf": [
        {
          "$ref": "#/$defs/SDInboundParagraph"
        },
        {
          "$ref": "#/$defs/SDInboundHeading"
        },
        {
          "$ref": "#/$defs/SDInboundList"
        },
        {
          "$ref": "#/$defs/SDInboundTable"
        },
        {
          "$ref": "#/$defs/SDInboundHorizontalRule"
        }
      ]
    },
    "SDInboundParagraph": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "paragraph"
        },
        "paragraph": {
          "type": "object",
          "properties": {
            "inlines": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/SDInboundInlineNode"
              }
            },
            "styleRef": {
              "type": "string"
            },
            "props": {
              "$ref": "#/$defs/SDInboundParagraphProps"
            }
          },
          "additionalProperties": false,
          "required": [
            "inlines"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "paragraph"
      ]
    },
    "SDInboundHeading": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "heading"
        },
        "heading": {
          "type": "object",
          "properties": {
            "level": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6
            },
            "inlines": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/SDInboundInlineNode"
              }
            },
            "styleRef": {
              "type": "string"
            },
            "props": {
              "$ref": "#/$defs/SDInboundParagraphProps"
            }
          },
          "additionalProperties": false,
          "required": [
            "level",
            "inlines"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "heading"
      ]
    },
    "SDInboundList": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "list"
        },
        "list": {
          "type": "object",
          "properties": {
            "levels": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/SDInboundListLevel"
              }
            },
            "items": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/SDInboundListItem"
              },
              "minItems": 1
            }
          },
          "additionalProperties": false,
          "required": [
            "items"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "list"
      ]
    },
    "SDInboundTable": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "table"
        },
        "table": {
          "type": "object",
          "properties": {
            "rows": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "cells": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "props": {
                          "$ref": "#/$defs/SDInboundCellProps"
                        },
                        "colSpan": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "rowSpan": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "header": {
                          "type": "boolean"
                        },
                        "content": {
                          "type": "array",
                          "items": {
                            "$ref": "#/$defs/SDInboundContentNode"
                          },
                          "minItems": 1
                        }
                      },
                      "additionalProperties": false,
                      "required": [
                        "content"
                      ]
                    },
                    "minItems": 1
                  }
                },
                "additionalProperties": false,
                "required": [
                  "cells"
                ]
              },
              "minItems": 1
            }
          },
          "additionalProperties": false,
          "required": [
            "rows"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "table"
      ]
    },
    "SDInboundCellProps": {
      "type": "object",
      "properties": {
        "verticalAlign": {
          "enum": [
            "top",
            "center",
            "bottom"
          ]
        },
        "shading": {
          "$ref": "#/$defs/SDInboundColor"
        },
        "padding": {
          "$ref": "#/$defs/SDInboundCellPadding"
        }
      },
      "additionalProperties": false
    },
    "SDInboundCellPadding": {
      "type": "object",
      "properties": {
        "top": {
          "type": "number",
          "minimum": 0
        },
        "right": {
          "type": "number",
          "minimum": 0
        },
        "bottom": {
          "type": "number",
          "minimum": 0
        },
        "left": {
          "type": "number",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "SDInboundHorizontalRule": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "const": "horizontalRule"
        },
        "horizontalRule": {
          "type": "object",
          "properties": {},
          "additionalProperties": false
        }
      },
      "additionalProperties": false,
      "required": [
        "kind",
        "horizontalRule"
      ]
    }
  },
  "type": "object",
  "properties": {
    "fragment": {
      "oneOf": [
        {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "kind": {
                  "const": "paragraph"
                },
                "paragraph": {
                  "type": "object",
                  "properties": {
                    "inlines": {
                      "type": "array",
                      "items": {
                        "$ref": "#/$defs/SDInboundInlineNode"
                      }
                    },
                    "styleRef": {
                      "type": "string"
                    },
                    "props": {
                      "$ref": "#/$defs/SDInboundParagraphProps"
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "inlines"
                  ]
                }
              },
              "additionalProperties": false,
              "required": [
                "kind",
                "paragraph"
              ]
            },
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "kind": {
                  "const": "heading"
                },
                "heading": {
                  "type": "object",
                  "properties": {
                    "level": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 6
                    },
                    "inlines": {
                      "type": "array",
                      "items": {
                        "$ref": "#/$defs/SDInboundInlineNode"
                      }
                    },
                    "styleRef": {
                      "type": "string"
                    },
                    "props": {
                      "$ref": "#/$defs/SDInboundParagraphProps"
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "level",
                    "inlines"
                  ]
                }
              },
              "additionalProperties": false,
              "required": [
                "kind",
                "heading"
              ]
            },
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "kind": {
                  "const": "list"
                },
                "list": {
                  "type": "object",
                  "properties": {
                    "levels": {
                      "type": "array",
                      "items": {
                        "$ref": "#/$defs/SDInboundListLevel"
                      }
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/$defs/SDInboundListItem"
                      },
                      "minItems": 1
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "items"
                  ]
                }
              },
              "additionalProperties": false,
              "required": [
                "kind",
                "list"
              ]
            },
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "kind": {
                  "const": "table"
                },
                "table": {
                  "type": "object",
                  "properties": {
                    "rows": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "cells": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "props": {
                                  "$ref": "#/$defs/SDInboundCellProps"
                                },
                                "colSpan": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "rowSpan": {
                                  "type": "integer",
                                  "minimum": 1
                                },
                                "header": {
                                  "type": "boolean"
                                },
                                "content": {
                                  "type": "array",
                                  "items": {
                                    "$ref": "#/$defs/SDInboundContentNode"
                                  },
                                  "minItems": 1
                                }
                              },
                              "additionalProperties": false,
                              "required": [
                                "content"
                              ]
                            },
                            "minItems": 1
                          }
                        },
                        "additionalProperties": false,
                        "required": [
                          "cells"
                        ]
                      },
                      "minItems": 1
                    }
                  },
                  "additionalProperties": false,
                  "required": [
                    "rows"
                  ]
                }
              },
              "additionalProperties": false,
              "required": [
                "kind",
                "table"
              ]
            },
            {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "kind": {
                  "const": "horizontalRule"
                },
                "horizontalRule": {
                  "type": "object",
                  "properties": {},
                  "additionalProperties": false
                }
              },
              "additionalProperties": false,
              "required": [
                "kind",
                "horizontalRule"
              ]
            }
          ]
        },
        {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "paragraph"
                  },
                  "paragraph": {
                    "type": "object",
                    "properties": {
                      "inlines": {
                        "type": "array",
                        "items": {
                          "$ref": "#/$defs/SDInboundInlineNode"
                        }
                      },
                      "styleRef": {
                        "type": "string"
                      },
                      "props": {
                        "$ref": "#/$defs/SDInboundParagraphProps"
                      }
                    },
                    "additionalProperties": false,
                    "required": [
                      "inlines"
                    ]
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "paragraph"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "heading"
                  },
                  "heading": {
                    "type": "object",
                    "properties": {
                      "level": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 6
                      },
                      "inlines": {
                        "type": "array",
                        "items": {
                          "$ref": "#/$defs/SDInboundInlineNode"
                        }
                      },
                      "styleRef": {
                        "type": "string"
                      },
                      "props": {
                        "$ref": "#/$defs/SDInboundParagraphProps"
                      }
                    },
                    "additionalProperties": false,
                    "required": [
                      "level",
                      "inlines"
                    ]
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "heading"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "list"
                  },
                  "list": {
                    "type": "object",
                    "properties": {
                      "levels": {
                        "type": "array",
                        "items": {
                          "$ref": "#/$defs/SDInboundListLevel"
                        }
                      },
                      "items": {
                        "type": "array",
                        "items": {
                          "$ref": "#/$defs/SDInboundListItem"
                        },
                        "minItems": 1
                      }
                    },
                    "additionalProperties": false,
                    "required": [
                      "items"
                    ]
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "list"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "table"
                  },
                  "table": {
                    "type": "object",
                    "properties": {
                      "rows": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "cells": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "props": {
                                    "$ref": "#/$defs/SDInboundCellProps"
                                  },
                                  "colSpan": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "rowSpan": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "header": {
                                    "type": "boolean"
                                  },
                                  "content": {
                                    "type": "array",
                                    "items": {
                                      "$ref": "#/$defs/SDInboundContentNode"
                                    },
                                    "minItems": 1
                                  }
                                },
                                "additionalProperties": false,
                                "required": [
                                  "content"
                                ]
                              },
                              "minItems": 1
                            }
                          },
                          "additionalProperties": false,
                          "required": [
                            "cells"
                          ]
                        },
                        "minItems": 1
                      }
                    },
                    "additionalProperties": false,
                    "required": [
                      "rows"
                    ]
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "table"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "const": "horizontalRule"
                  },
                  "horizontalRule": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": false
                  }
                },
                "additionalProperties": false,
                "required": [
                  "kind",
                  "horizontalRule"
                ]
              }
            ]
          },
          "minItems": 1
        }
      ]
    },
    "lossy": {
      "type": "boolean"
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "enum": [
              "conversion-normalized-construct",
              "conversion-unsupported-construct",
              "conversion-dropped-style",
              "conversion-unsafe-content",
              "conversion-unsafe-url",
              "conversion-source-limit-exceeded",
              "conversion-depth-limit-exceeded",
              "conversion-malformed-input",
              "conversion-empty-result"
            ]
          },
          "severity": {
            "enum": [
              "error",
              "warning",
              "info"
            ]
          },
          "message": {
            "type": "string"
          },
          "path": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            }
          },
          "construct": {
            "enum": [
              "document",
              "source",
              "text",
              "paragraph",
              "emptyParagraph",
              "softBreak",
              "lineBreak",
              "heading",
              "bold",
              "italic",
              "underline",
              "strike",
              "hyperlink",
              "list",
              "table",
              "tableHeader",
              "colSpan",
              "rowSpan",
              "horizontalRule",
              "inlineCode",
              "codeBlock",
              "blockquote",
              "taskList",
              "image",
              "footnote",
              "rawHtml",
              "unknownWrapper",
              "script",
              "style",
              "eventHandler"
            ]
          },
          "disposition": {
            "enum": [
              "preserved",
              "normalized",
              "downgraded",
              "dropped",
              "rejected"
            ]
          },
          "lossy": {
            "type": "boolean"
          },
          "source": {
            "type": "object",
            "properties": {
              "format": {
                "enum": [
                  "html",
                  "markdown"
                ]
              },
              "range": {
                "type": "object",
                "properties": {
                  "startOffset": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "endOffset": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "startLine": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "startColumn": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "endLine": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "endColumn": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": false,
                "required": [
                  "startOffset",
                  "endOffset"
                ]
              }
            },
            "additionalProperties": false,
            "required": [
              "format"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "code",
          "severity",
          "message",
          "construct",
          "disposition",
          "lossy",
          "source"
        ]
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "fragment",
    "lossy",
    "diagnostics"
  ]
}
```

## Pre-apply throws

- `CAPABILITY_UNAVAILABLE`
- `INVALID_INPUT`

## Non-applied receipt codes

- None