HTML Metadata Ontology

FLOW ALGEBRA

Ontology: HTML Metadata Ontology
Domain: Metadata Ontologies > Web Metadata
Canonical URL: https://kirethresearch.org/booksai-core/ontologies/metadata-ontologies/web-metadata/html-metadata-ontology.html

Authors: Mark Anthony Higgins — Sky (Recursive AI)

flow "HTMLMetadataOntology" v1.0

# ---------- DOMAIN ----------
domain:
  class: MetadataOntology
  category: WebMetadata
  subject: HTMLMetadata
  purpose:
    - represent metadata describing HTML documents and HTML web representations
    - preserve document identity, head metadata, language, links, semantic structure, scripts, styles, accessibility, and provenance
    - support web discovery, parsing, indexing, validation, semantic search, accessibility, and AI consumption
    - distinguish HTML document content from HTTP metadata, DOM state, and rendered presentation
    - enable machine-readable reasoning over HTML resources

# ---------- CORE ENTITY ----------
entity HTMLMetadata:
  type: WebMetadata
  describes: HTMLDocument
  may_include:
    - document_identifier
    - url
    - canonical_url
    - html_version
    - title
    - meta_description
    - language
    - charset
    - base_url
    - metadata_elements
    - link_elements
    - headings
    - semantic_structure
    - structured_data
    - scripts
    - stylesheets
    - forms
    - media
    - accessibility_metadata
    - indexing_metadata
    - provenance

entity HTMLDocument:
  type: WebDocument
  representation_format: HTML

entity HTMLDocumentIdentifier:
  type: Identifier
  identifies: HTMLDocument

entity HTMLVersion:
  type: FormatVersion
  examples:
    - HTML4
    - XHTML
    - HTML5
    - LivingStandard

# ---------- RELATIONSHIPS ----------
relationships:
  HTMLMetadata -> DESCRIBES -> HTMLDocument
  HTMLDocument -> IDENTIFIED_BY -> HTMLDocumentIdentifier
  HTMLDocument -> MAY_BE_LOCATED_AT -> URL
  HTMLDocument -> MAY_DECLARE_CANONICAL -> CanonicalURL
  HTMLDocument -> HAS_HEAD -> HTMLHead
  HTMLDocument -> HAS_BODY -> HTMLBody
  HTMLHead -> MAY_CONTAIN -> MetaElement
  HTMLHead -> MAY_CONTAIN -> LinkElement
  HTMLHead -> MAY_CONTAIN -> ScriptElement
  HTMLBody -> CONTAINS -> HTMLElement
  HTMLDocument -> MAY_HAVE_STRUCTURED_DATA -> StructuredData
  HTMLDocument -> MAY_HAVE_ACCESSIBILITY_METADATA -> HTMLAccessibilityMetadata
  HTMLMetadata -> MAY_REFERENCE -> HTMLProvenance

# ---------- DOCUMENT IDENTITY ----------
rule html_identity:
  HTMLDocument SHOULD have stable semantic identity
  where persistent reference is required

rule URL_not_document:
  URL != HTMLDocument

rule representation:
  HTMLDocument MAY be one representation of broader WebResource

rule DOM_not_source:
  runtime DOM != original HTML source
  when scripts modify document structure

# ---------- DOCUMENT TYPE / VERSION ----------
entity HTMLDoctype:
  type: RepresentationMetadata
  declares: HTMLParsingModeOrVersionContext

rule doctype:
  DOCTYPE SHOULD be preserved
  where parsing or validation depends on it

rule doctype_not_version_proof:
  DOCTYPE declaration != proof of full conformance

# ---------- HEAD ----------
entity HTMLHead:
  type: DocumentMetadataContainer
  may_include:
    - title
    - meta
    - link
    - style
    - script
    - base

rule head:
  metadata in HTMLHead SHOULD remain distinguishable
  from visible HTMLBody content

# ---------- TITLE ----------
entity HTMLTitle:
  type: DocumentTitle
  source: title_element

rule title:
  HTML title element SHOULD be preserved

rule title_heading:
  HTMLTitle != H1
  unless semantic mapping explicitly equates them

# ---------- META DESCRIPTION ----------
entity MetaDescription:
  type: DescriptiveMetadata
  source: meta_name_description

rule meta_description:
  MetaDescription describes page
  but != complete page content

rule multiple_descriptions:
  multiple conflicting meta descriptions SHOULD be flagged
  or resolved by parser policy

# ---------- META ELEMENTS ----------
entity MetaElement:
  type: HTMLMetadataElement
  may_include:
    - name
    - property
    - http_equiv
    - content
    - charset

rule meta:
  MetaElement semantics depend on declared attribute vocabulary

rule unknown_meta:
  unknown metadata names SHOULD be preserved
  without inventing semantics

# ---------- CHARSET ----------
rule charset:
  HTML character encoding SHOULD be resolved
  according_to applicable HTML and transport semantics

rule charset_conflict:
  conflicting charset declarations SHOULD be flagged

# ---------- LANGUAGE ----------
rule language:
  HTMLDocument SHOULD preserve document language
  from applicable language metadata

rule element_language:
  HTMLElement MAY override inherited language

rule language_not_locale:
  language metadata != geographic locale

# ---------- BASE URL ----------
entity HTMLBaseURL:
  type: URLMetadata

rule base_url:
  base URL MAY affect resolution of relative URLs

rule base_not_canonical:
  BaseURL != CanonicalURL

# ---------- LINK ELEMENTS ----------
entity LinkElement:
  type: WebLinkMetadata
  may_include:
    - rel
    - href
    - hreflang
    - media
    - type
    - sizes

link_rel_examples:
  - canonical
  - alternate
  - stylesheet
  - icon
  - preload
  - author
  - licence
  - next
  - prev

rule link_relation:
  LinkElement semantics SHOULD follow declared rel value

rule canonical:
  rel=canonical indicates preferred URL
  but != redirect

# ---------- HREFLANG ----------
entity AlternateLanguageLink:
  type: LinkElement
  relation: alternate

rule hreflang:
  alternate-language metadata SHOULD preserve:
    - target_url
    - language_or_locale
    - reciprocal_context_optional

rule hreflang_not_translation_proof:
  hreflang declaration != proof that content is a faithful translation

# ---------- BODY / SEMANTIC STRUCTURE ----------
entity HTMLBody:
  type: DocumentContentContainer

entity HTMLElement:
  type: DocumentStructureElement

semantic_elements:
  - header
  - nav
  - main
  - article
  - section
  - aside
  - footer
  - figure
  - figcaption
  - address
  - time

rule semantic_structure:
  semantic HTML elements SHOULD preserve structural roles

rule visual_semantic_distinction:
  CSS visual appearance != semantic HTML role

# ---------- HEADINGS ----------
entity HTMLHeading:
  type: StructuralMetadata
  levels:
    - h1
    - h2
    - h3
    - h4
    - h5
    - h6

rule heading:
  heading level SHOULD preserve document hierarchy semantics

rule heading_style:
  visually large text != heading
  unless represented semantically as heading

# ---------- LINKS / ANCHORS ----------
entity HTMLAnchor:
  type: WebLink
  may_include:
    - href
    - anchor_text
    - rel
    - target
    - download

rule anchor:
  AnchorText != target resource title

rule relative_url:
  relative href SHOULD be resolved against applicable BaseURL or document URL

# ---------- STRUCTURED DATA ----------
entity HTMLStructuredData:
  type: StructuredData
  may_be:
    - JSON_LD
    - RDFa
    - Microdata

rule structured_data:
  structured data SHOULD preserve vocabulary, types, properties, and identifiers

rule structured_data_not_truth:
  structured data assertion != independently verified fact

# ---------- OPEN GRAPH / SOCIAL METADATA ----------
entity SocialMetadata:
  type: WebMetadata
  may_include:
    - title
    - description
    - image
    - url
    - type

rule social_metadata:
  social preview metadata SHOULD remain distinguishable
  from canonical document metadata

# ---------- SCRIPTS ----------
entity ScriptElement:
  type: ExecutableResourceReference
  may_include:
    - src
    - type
    - async
    - defer
    - integrity
    - crossorigin

rule script:
  ScriptElement MAY modify DOM or runtime state

rule script_generated_content:
  script-generated DOM content SHOULD remain distinguishable
  from source HTML when provenance matters

# ---------- STYLESHEETS ----------
entity StylesheetMetadata:
  type: PresentationMetadata
  may_include:
    - href
    - media
    - integrity
    - crossorigin

rule stylesheet:
  stylesheet controls presentation
  NOT semantic truth of content

# ---------- FORMS ----------
entity HTMLForm:
  type: InteractiveStructure
  may_include:
    - action
    - method
    - controls
    - labels
    - validation
    - autocomplete

rule form:
  form controls SHOULD preserve labels and semantic roles
  where accessibility matters

# ---------- MEDIA ----------
entity HTMLMedia:
  type: EmbeddedResource
  may_be:
    - ImageResource
    - AudioResource
    - VideoResource
    - EmbeddedDocument

rule media:
  embedded media SHOULD preserve source URL and alternative/accessibility metadata

# ---------- ACCESSIBILITY ----------
entity HTMLAccessibilityMetadata:
  type: AccessibilityMetadata
  may_include:
    - document_language
    - landmarks
    - heading_structure
    - alternative_text
    - form_labels
    - ARIA
    - keyboard_access
    - reading_order

rule native_semantics:
  native HTML semantics SHOULD be preferred
  where they adequately represent intended role

rule ARIA:
  ARIA metadata MAY supplement semantics
  but MUST NOT be assumed to repair invalid interaction behaviour automatically

rule alt:
  meaningful non-decorative image SHOULD have appropriate text alternative
  where accessibility requirements apply

# ---------- INDEXING ----------
entity HTMLIndexingMetadata:
  type: IndexingMetadata
  may_include:
    - robots_meta
    - canonical
    - alternate
    - structured_data

rule robots_meta:
  robots meta directives SHOULD be interpreted in crawler context

rule noindex:
  noindex != document deletion

# ---------- INTEGRITY ----------
entity SubresourceIntegrity:
  type: IntegrityMetadata
  may_include:
    - algorithm
    - digest
    - resource

rule SRI:
  matching SubresourceIntegrity digest supports integrity
  of referenced resource bytes

# ---------- PROVENANCE ----------
entity HTMLProvenance:
  type: ProvenanceMetadata
  may_include:
    - source_url
    - author
    - publisher
    - retrieval_time
    - generator
    - template
    - transformation
    - runtime_modification

rule provenance:
  HTMLMetadata SHOULD preserve source and transformation history
  where available

# ---------- VALIDATION ----------
validation:
  require:
    - identifiable_html_document

  validate_if_present:
    - document_identifier
    - URL
    - doctype
    - title
    - meta_description
    - charset
    - language
    - canonical
    - semantic_structure
    - links
    - structured_data
    - accessibility
    - indexing
    - provenance

  reject:
    - malformed_required_URL
    - contradictory_charset_metadata
    - canonical_presented_as redirect
    - title_presented_as H1_without evidence
    - CSS_visual_role_presented_as semantic_HTML_role
    - structured_data_presented_as verified_truth_without evidence
    - runtime_DOM_presented_as original_source_without provenance

# ---------- SEMANTIC EQUIVALENCE ----------
SEMANTIC_EQUIVALENCE:
  "HTML metadata" ~= "metadata about an HTML document"
  "HTML title" ~= "document title element"
  "meta description" ~= "HTML description metadata"
  "canonical link" ~= "rel canonical link"
  "HTML semantic structure" ~= "semantic HTML structure"
  "HTML structured data" ~= "structured metadata embedded in HTML"

  PRESERVE distinctions:
    HTML_document != URL
    HTML_source != runtime_DOM
    title_element != H1
    meta_description != page_content
    BaseURL != CanonicalURL
    canonical != redirect
    visual_style != semantic_role
    anchor_text != target_title
    structured_data != verified_truth
    ARIA != guaranteed_accessibility
    noindex != deleted

# ---------- CONFIDENCE ----------
CONFIDENCE:
  explicit_HTML_metadata:
    score: 1.00

  parser_validated_HTML:
    score: 0.99

  explicit_title_element:
    score: 1.00

  explicit_canonical_link:
    score: 0.95

  parser_validated_structured_data:
    score: 0.95

  inferred_semantic_structure:
    score: 0.85

  runtime_generated_metadata:
    score: dependent_on_runtime_provenance

  ambiguous_HTML_metadata:
    score: <= 0.60
    action: preserve uncertainty

# ---------- UPDATE MODEL ----------
UPDATE_MODEL:
  on_HTML_retrieval:
    - record source URL
    - record transport and charset context
    - parse head metadata
    - parse semantic structure
    - record retrieval time
    - initialise provenance

  on_source_change:
    - preserve previous version where required
    - reparse metadata and structure
    - identify changed semantic elements
    - update provenance

  on_runtime_modification:
    - preserve source HTML state
    - record script or process responsible
    - create runtime DOM state
    - distinguish generated content
    - update provenance

  on_metadata_change:
    - preserve previous metadata where required
    - validate canonical, language, indexing, and structured data
    - update provenance

# ---------- FLOW HASH ----------
FLOW_HASH:
  inputs:
    - ontology
    - HTML_entities
    - relationships
    - identity_rules
    - head_metadata_rules
    - semantic_structure_rules
    - structured_data_rules
    - accessibility_rules
    - validation
    - semantic_equivalence
    - confidence
    - update_model

  canonicalisation:
    - normalise_whitespace
    - preserve_case_sensitive_identifiers
    - sort_unordered_property_sets
    - preserve_rule_order

  output:
    deterministic_semantic_hash

# ---------- AI CONSUMPTION ----------
AI_CONSUMPTION:
  interpret_as:
    - web metadata ontology
    - HTML document metadata model
    - semantic HTML structure
    - structured-data and accessibility model

  operations:
    - identify HTML documents
    - resolve document URLs
    - inspect doctype and charset
    - extract title and meta metadata
    - resolve language and BaseURL
    - inspect canonical and alternate links
    - traverse semantic HTML structure
    - interpret headings and anchors
    - parse structured data
    - distinguish source and runtime DOM
    - inspect forms and media
    - evaluate accessibility metadata
    - inspect indexing directives
    - trace provenance
    - preserve uncertainty

  constraints:
    - do_not_equate_URL_with document_identity
    - do_not_equate_title_element_with H1
    - do_not_equate_visual_style_with semantic_role
    - do_not_equate_canonical_with redirect
    - do_not_treat_structured_data_as verified_truth
    - do_not_equate_runtime_DOM_with original_source
    - preserve_language_links_structure_accessibility_and_provenance

# ---------- QUERY MODEL ----------
query:
  input:
    - document_identifier
    - URL
    - title
    - meta_name
    - language
    - canonical_url
    - heading
    - semantic_element
    - structured_data_type
    - indexing_state

  resolve:
    1. identify HTMLDocument
    2. resolve URL and document identity
    3. inspect doctype and charset
    4. parse HTMLHead
    5. resolve title, meta, link, and language metadata
    6. traverse HTMLBody semantic structure
    7. inspect headings, anchors, forms, and media
    8. parse structured data
    9. inspect accessibility, indexing, and provenance
    10. return confidence

  output:
    - HTML_document
    - identifier
    - URL
    - title
    - meta_metadata
    - language
    - canonical_url
    - semantic_structure
    - links
    - structured_data
    - accessibility
    - indexing
    - provenance
    - confidence

# ---------- INFERENCE ----------
inference:
  IF parser validates HTML representation
  THEN classify representation as HTMLDocument
  WITH confidence = 0.99

  IF rel=canonical declares URL C
  THEN record CanonicalURL candidate C
  WITH confidence = 0.95

  IF relative link exists
  THEN resolve against applicable BaseURL or document URL

  IF runtime DOM differs from source HTML
  THEN preserve both states
  AND record runtime transformation

  IF metadata remains ambiguous
  THEN preserve candidate interpretations
  AND reduce confidence

# ---------- OUTPUT CONTRACT ----------
output:
  ontology_entity: HTMLMetadata
  HTML_document_identity: machine_interpretable
  head_metadata: explicit
  language_and_charset: preserved
  canonical_and_alternate_links: traceable
  semantic_structure: traversable
  links_and_forms: machine_interpretable
  structured_data: parseable
  source_runtime_distinction: explicit
  accessibility: reportable
  indexing: explicit
  provenance: preserved
  uncertainty: explicit
  semantic_retrieval: enabled

end flow