Canonical URL Ontology

FLOW ALGEBRA

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

Authors: Mark Anthony Higgins — Sky (Recursive AI)

flow "CanonicalURLOntology" v1.0

# ---------- DOMAIN ----------
domain:
  class: MetadataOntology
  category: WebMetadata
  subject: CanonicalURLMetadata
  purpose:
    - represent metadata describing preferred canonical URLs for web resources
    - preserve source URL, declared canonical target, relationship scope, evidence, validity, and provenance
    - support duplicate consolidation, crawling, indexing, semantic identity resolution, and AI consumption
    - distinguish canonical declarations from redirects, resource identity, sitemap listings, and verified equivalence
    - enable machine-readable reasoning over canonicalisation relationships

# ---------- CORE ENTITY ----------
entity CanonicalURLMetadata:
  type: WebMetadata
  describes: CanonicalRelationship
  may_include:
    - canonical_identifier
    - source_resource
    - source_url
    - canonical_url
    - declaration_method
    - relationship_scope
    - status
    - validation
    - confidence
    - timestamp
    - provenance

entity CanonicalRelationship:
  type: WebRelationship
  connects:
    - SourceWebResource
    - PreferredURL

entity CanonicalURL:
  subtype_of: URL
  role: PreferredLocator

entity CanonicalIdentifier:
  type: Identifier
  identifies: CanonicalRelationship

# ---------- RELATIONSHIPS ----------
relationships:
  CanonicalURLMetadata -> DESCRIBES -> CanonicalRelationship
  CanonicalRelationship -> HAS_SOURCE -> WebResource
  CanonicalRelationship -> HAS_SOURCE_URL -> URL
  CanonicalRelationship -> DECLARES_PREFERRED -> CanonicalURL
  WebResource -> MAY_HAVE_CANONICAL -> CanonicalURL
  CanonicalRelationship -> MAY_HAVE_VALIDATION -> CanonicalValidation
  CanonicalRelationship -> MAY_HAVE_CONFIDENCE -> CanonicalConfidence
  CanonicalURLMetadata -> MAY_REFERENCE -> CanonicalProvenance

# ---------- CANONICAL DECLARATION METHODS ----------
canonical_methods:
  - HTML_link_element
  - HTTP_Link_header
  - structured_system_configuration
  - inferred_from_consistent_signals

rule method:
  declaration method SHOULD remain explicit

rule inferred_canonical:
  inferred canonical relationship MUST remain distinguishable
  from explicit declaration

# ---------- HTML LINK CANONICAL ----------
entity HTMLCanonicalLink:
  type: CanonicalDeclaration
  representation:
    rel: canonical
    href: CanonicalURL

rule HTML_canonical:
  HTML canonical declaration SHOULD be associated
  with source document or web resource

rule href:
  canonical href SHOULD resolve to valid URL

# ---------- HTTP LINK HEADER ----------
entity HTTPCanonicalLink:
  type: CanonicalDeclaration
  source: HTTP_Link_header

rule HTTP_canonical:
  HTTP Link header with rel=canonical
  MAY declare canonical target for non-HTML or HTML resources

rule header_document:
  HTTP canonical declaration SHOULD preserve response context

# ---------- SOURCE / TARGET ----------
rule source_target:
  SourceURL MAY differ from CanonicalURL

rule self_canonical:
  SourceURL = CanonicalURL
  indicates self-referential canonical declaration

rule cross_domain:
  CanonicalURL MAY be cross-domain
  where publisher intentionally declares external preferred resource

# ---------- CANONICAL VS IDENTITY ----------
rule canonical_identity:
  CanonicalURL is preferred locator
  NOT automatically universal semantic identity

rule identity_evidence:
  canonical relationship MAY support resource-equivalence inference
  when corroborated by content, redirects, identifiers, or other metadata

rule canonical_not_sameAs:
  canonical relationship != semantic sameAs assertion
  unless explicitly modelled as such

# ---------- CANONICAL VS REDIRECT ----------
rule canonical_redirect:
  CanonicalDeclaration != HTTPRedirect

rule redirect:
  HTTP redirect changes retrieval flow
  while canonical declaration provides metadata preference

rule redirect_evidence:
  consistent redirect and canonical signals MAY increase identity confidence

# ---------- CANONICAL VS SITEMAP ----------
rule sitemap:
  SitemapEntry != CanonicalDeclaration

rule sitemap_loc:
  sitemap loc MUST NOT be treated as canonical proof
  without independent canonical evidence

# ---------- CANONICAL VS OPEN GRAPH ----------
rule OpenGraph:
  og:url != CanonicalURL
  unless independent evidence establishes equivalence

# ---------- CANONICAL VS SCHEMA.ORG ----------
rule SchemaOrg:
  SchemaOrg url property != CanonicalURL
  unless canonical relationship is independently established

# ---------- URL NORMALISATION ----------
entity CanonicalURLNormalisation:
  type: WebProcessingMetadata
  may_include:
    - scheme
    - host
    - port
    - path
    - query
    - fragment
    - percent_encoding

rule normalisation:
  URL normalisation SHOULD follow applicable URI and application semantics

rule query_parameters:
  query parameters MUST NOT be removed solely for canonicalisation
  unless equivalence is established

rule fragment:
  fragment component SHOULD be interpreted according_to URL and canonical semantics

rule trailing_slash:
  trailing-slash variants MUST NOT be assumed equivalent
  without server or application evidence

# ---------- DUPLICATE RESOURCES ----------
entity DuplicateResourceCandidate:
  type: WebResourceCandidate
  may_include:
    - URL
    - content_similarity
    - canonical_signal
    - redirect_signal
    - identifier_signal
    - confidence

rule duplicate:
  duplicate-resource consolidation SHOULD use multiple evidence signals
  where possible

rule content_similarity:
  similar content != guaranteed same resource

# ---------- CONFLICTING CANONICALS ----------
entity CanonicalConflict:
  type: ValidationMetadata
  may_include:
    - source_url
    - declared_targets
    - signal_sources
    - resolution_state

rule conflict:
  conflicting canonical targets SHOULD remain explicit
  until resolved

rule chain:
  canonical chains SHOULD be traversed cautiously
  and final target SHOULD be validated

rule loop:
  canonical loops SHOULD be flagged

# ---------- TARGET VALIDATION ----------
entity CanonicalValidation:
  type: ValidationMetadata
  may_include:
    - URL_valid
    - target_retrievable
    - target_status
    - target_canonical
    - redirect_state
    - content_compatibility
    - protocol_consistency
    - validation_time

rule target:
  canonical target SHOULD be syntactically valid

rule retrievability:
  temporary target retrieval failure != automatic invalid canonical relationship

rule target_canonical:
  target declaring different canonical MAY indicate chain or conflict

# ---------- HTTP STATUS ----------
rule status:
  source or target HTTP status SHOULD be preserved
  when evaluating canonical relationship

rule error_target:
  persistent error target MAY reduce canonical confidence
  but temporal context MUST be preserved

# ---------- TEMPORAL VALIDITY ----------
entity CanonicalValidity:
  type: ValidityMetadata
  may_include:
    - valid_from
    - valid_until
    - observed_at
    - status

canonical_status:
  - declared
  - validated
  - conflicting
  - stale
  - superseded
  - invalid
  - unknown

rule temporal:
  canonical relationships MAY change over time

rule historical:
  superseded canonical relationships SHOULD remain traceable
  where historical indexing or provenance matters

# ---------- CONFIDENCE ----------
entity CanonicalConfidence:
  type: EpistemicMetadata
  range: [0.0, 1.0]

rule confidence_bounds:
  REQUIRE 0.0 <= confidence <= 1.0

rule confidence_context:
  confidence SHOULD reflect evidence supporting preferred-resource relationship

# ---------- PROVENANCE ----------
entity CanonicalProvenance:
  type: ProvenanceMetadata
  may_include:
    - source_document
    - source_url
    - declaration_method
    - retrieval_time
    - parser
    - HTTP_response
    - validation_method
    - historical_state

rule provenance:
  CanonicalURLMetadata SHOULD preserve source, observation, and validation history

# ---------- VALIDATION ----------
validation:
  require:
    - source_url
    - canonical_url

  validate_if_present:
    - canonical_identifier
    - declaration_method
    - target_status
    - redirect_state
    - content_compatibility
    - temporal_validity
    - confidence
    - provenance

  reject:
    - malformed_canonical_URL
    - canonical_loop
    - contradictory_explicit_targets_without conflict_state
    - sitemap_URL_presented_as canonical_proof
    - og_url_presented_as canonical_proof
    - SchemaOrg_url_presented_as canonical_proof
    - canonical_declaration_presented_as HTTP_redirect
    - canonical_relationship_presented_as absolute_identity_without evidence

# ---------- SEMANTIC EQUIVALENCE ----------
SEMANTIC_EQUIVALENCE:
  "canonical URL" ~= "preferred URL" WHEN web canonicalisation semantics apply
  "canonical link" ~= "rel canonical declaration"
  "self canonical" ~= "canonical declaration pointing to source URL"
  "cross-domain canonical" ~= "canonical target on different domain"
  "canonical target" ~= "preferred locator target"

  PRESERVE distinctions:
    canonical_URL != WebResource
    canonical_URL != universal_entity_identity
    canonical != redirect
    canonical != sameAs
    canonical != sitemap_entry
    canonical_URL != og:url
    canonical_URL != SchemaOrg_url
    content_similarity != identity
    canonical_chain != validated_final_target
    declared_canonical != verified_equivalence

# ---------- CONFIDENCE MODEL ----------
CONFIDENCE:
  explicit_self_canonical:
    score: 0.98

  explicit_canonical_with_valid_target:
    score: 0.97

  explicit_canonical_plus_matching_redirect:
    score: 0.99

  canonical_plus_identifier_and_content_evidence:
    score: 0.99

  inferred_canonical_from_multiple_signals:
    score: <= 0.90

  sitemap_only_signal:
    score: <= 0.60

  og_url_only_signal:
    score: <= 0.60

  content_similarity_only:
    score: <= 0.65

  conflicting_canonical_signals:
    score: <= 0.50
    action: preserve conflict

# ---------- UPDATE MODEL ----------
UPDATE_MODEL:
  on_canonical_discovery:
    - identify source URL
    - extract explicit declaration
    - resolve canonical URL
    - record declaration method
    - initialise provenance

  on_target_validation:
    - retrieve or inspect canonical target
    - record HTTP status
    - inspect redirects and target canonical
    - compare supporting identity evidence
    - update confidence and status

  on_canonical_change:
    - preserve previous CanonicalRelationship
    - record new target
    - mark previous state superseded where applicable
    - update provenance

  on_conflict:
    - preserve all canonical signals
    - classify CanonicalConflict
    - avoid forced consolidation
    - update confidence and provenance

# ---------- FLOW HASH ----------
FLOW_HASH:
  inputs:
    - ontology
    - canonical_entities
    - relationships
    - declaration_rules
    - normalisation_rules
    - validation_rules
    - conflict_rules
    - semantic_equivalence
    - confidence_model
    - update_model

  canonicalisation:
    - preserve_URL_semantics
    - normalise_scheme_and_host_where_applicable
    - preserve_query_semantics
    - preserve_temporal_observations
    - preserve_rule_order

  output:
    deterministic_semantic_hash

# ---------- AI CONSUMPTION ----------
AI_CONSUMPTION:
  interpret_as:
    - web metadata ontology
    - canonical URL relationship model
    - duplicate-resource consolidation evidence model
    - canonical validation and provenance structure

  operations:
    - identify canonical declarations
    - resolve source and target URLs
    - distinguish explicit and inferred canonicals
    - inspect self and cross-domain canonicals
    - compare redirects and canonical signals
    - inspect sitemap, Open Graph, and Schema.org signals separately
    - validate target state
    - detect chains, loops, and conflicts
    - assess duplicate-resource evidence
    - preserve temporal canonical history
    - trace provenance
    - expose uncertainty

  constraints:
    - do_not_equate_canonical_URL_with universal_resource_identity
    - do_not_equate_canonical_with redirect
    - do_not_equate_canonical_with sameAs
    - do_not_infer_canonical_from sitemap_og_or_schema_url_alone
    - do_not_force_merge_when canonical_signals_conflict
    - preserve_source_target_method_time_confidence_and_provenance

# ---------- QUERY MODEL ----------
query:
  input:
    - source_url
    - canonical_url
    - declaration_method
    - target_status
    - redirect_target
    - sitemap_signal
    - og_url
    - SchemaOrg_url
    - observation_time

  resolve:
    1. identify SourceWebResource and source URL
    2. retrieve explicit canonical declarations
    3. resolve canonical target URL
    4. inspect declaration method
    5. inspect source and target HTTP state
    6. compare redirect and supporting identity signals
    7. detect canonical chains, loops, or conflicts
    8. evaluate temporal validity
    9. calculate confidence
    10. return provenance

  output:
    - canonical_relationship
    - source_url
    - canonical_url
    - declaration_method
    - validation_state
    - redirect_state
    - conflict_state
    - temporal_validity
    - provenance
    - confidence

# ---------- INFERENCE ----------
inference:
  IF HTML link rel=canonical declares URL C
  THEN create explicit CanonicalRelationship
  WITH confidence >= 0.95

  IF HTTP Link header rel=canonical declares URL C
  THEN create explicit CanonicalRelationship
  WITH confidence >= 0.95

  IF source redirects to C
  AND source also declares C canonical
  THEN increase canonical confidence
  WITH confidence <= 0.99

  IF canonical target declares different target D
  THEN classify canonical_chain candidate
  AND validate D before consolidation

  IF canonical signals conflict
  THEN preserve alternatives
  AND do_not force resource merge

# ---------- OUTPUT CONTRACT ----------
output:
  ontology_entity: CanonicalURLMetadata
  canonical_relationship: machine_interpretable
  source_and_target: explicit
  declaration_method: preserved
  self_cross_domain_state: resolvable
  redirect_distinction: explicit
  supporting_signals: separately_preserved
  chains_loops_conflicts: detectable
  temporal_validity: traceable
  confidence: explicit
  provenance: preserved
  uncertainty: explicit
  semantic_retrieval: enabled

end flow