# HTML Format Schema — File Format Specification
# KNO Schema Version: 0.1.0
# Canonical XRI: kno://specs/html-format
$schema: kno@0.0.9
id: 01M50T7BJP7VW4VGEDT02Z228D
slug: html-format
type: spec
version: 0.1.0
title: "HTML Format Schema"
purpose: |
  Describe HTML as a general-purpose source format in KNO.
  It describes the format dimension independently of domain and purpose.
  It introduces no channel-specific primitive or document-source policy.

provenance:
  origin:
    id: 01M50T7BJP7VW4VGEDT02Z228D
    timestamp: "2026-10-15T22:16:48Z"
    tool: manual

taxonomy:
  topics:
    - file-formats
    - documentation
  keywords:
    - html
    - utf-8

relationships:
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to the KNO format specification"
  produces:
    - xri: "kno://specs/document-schema"
      reason: "This format can supply text for a document entity"
  related_to:
    - xri: "kno://specs/markdown-format"
      reason: "Sibling text format and spec.format house pattern"
    - xri: "kno://specs/plaintext-format"
      reason: "Another general-purpose text format with distinct interpretation rules"

quality:
  completeness: 0.8
  last_reviewed: "2026-10-16"
  review_status: draft
  reviewed_by: "Codex 01a1421a-f748-7dc3-b0f9-2cd8db0052b1"

_history:
  retention: full
  format: changelog
  changelog:
    - version: "0.1.0"
      date: "2026-10-16"
      author: "Codex 01a1421a-f748-7dc3-b0f9-2cd8db0052b1"
      summary: "Initial html format artifact (#6132)"
      changes:
        - "Uses kno://specs/html-format and existing name-based resolution"
        - "Reconciles the unpublished alias draft with the retained house-form allocation"

spec:
  status: Draft
  standards:
    - name: "WHATWG HTML Living Standard — HTML syntax"
      url: "https://html.spec.whatwg.org/multipage/syntax.html"
    - name: "HTML Living Standard — text/html media type"
      url: "https://html.spec.whatwg.org/multipage/iana.html#text/html"

  format:
    name: "HTML"
    mime_type: "text/html"
    extensions:
      - ".html"
      - ".htm"
    encoding: "UTF-8"
    line_endings:
      - "LF"
      - "CRLF"

  description: |
      HTML expresses document structure with elements, attributes and text.
      Its syntax and parsing rules come from the HTML Living Standard.
      Format identification alone establishes neither authoring conformance
      nor safe rendering.

  grammar: |
      Use the HTML Living Standard for syntax, character references and parsing.
      This KNO representation uses UTF-8. A consumer must distinguish a full
      HTML document from a fragment and supply the fragment's parsing context;
      the format name alone does not choose a context or turn a fragment into
      a complete document. Parser error recovery is not conformance approval.

  rendering: |
      HTML may contain active content, navigation and external resource links.
      Treat source as untrusted. A rendering consumer must apply its own
      established sanitization, isolation and resource-access policies before
      display. This format does not define a universal sanitizer allowlist,
      authorize external fetches, or claim that parsing makes HTML safe.
      Sanitized output must not silently replace preserved source.

  kno_integration:
    description: |
      The canonical format reference is kno://specs/html-format.
      The spec registry serves /html-format.kno and
      /html-format@0.1.0.kno through its existing routes. A local
      conforms_to reference uses html-format@0.1.0 in validate-kno.ts.
      These are different input syntaxes; no kno://formats/* alias is defined.

      A containing document may identify html using its existing
      content_format and source_format fields. The following is a partial
      field example, not a complete document or a ruling on source authority.
      Inline, embedded-local, external and reflexive source contracts remain
      governed by the document schema and its separately held #6067 decision.
    example: |
      content_format: html
      source_format: html
      content: |
        <p>Embedded HTML fragment.</p>

  validation_boundary: |
    KNO validation checks the format artifact's structure. Resolving this
    artifact does not validate arbitrary source against the format grammar,
    implement a renderer, or prove document/profile conformance. Domain
    schemas and consuming profiles impose their own requirements.

annotations:
  design_notes: |
    Follows specs/markdown-format.kno's spec.format block. Legacy
    kno://formats/html declarations in the held document schema are
    unresolved references, not aliases installed by this artifact.
    No static schema manifest entry or resolver implementation is added.